Displays Screenshot API

Capture, retrieve, and manage display screenshots, thumbnails, window information, and clipboard text. These endpoints run on the container-scoped display service and operate against the active display for the container.

Note

All endpoints in this section use the container-scoped base URL https://{projectId}-{containerId}-display-1.{server}.containers.hoody.icu. The displayId query parameter is optional and overrides the *-display-N.* hostname pattern when set.

Display Information

GET /api/v1/display/info

Retrieves information about the current display including all available screenshots.

Parameters

Name	In	Type	Required	Description
displayId	query	integer	No	Display ID to use (overrides the *-display-N.* hostname pattern). Valid range: 1-999999

Response

200

{
  "display": 6,
  "screenshots": [
    {
      "timestamp": "1749541160",
      "timestamp_human": "2026-02-23T16:57:02+00:00",
      "full": {
        "path": "/hoody/storage/hoody-display/screenshots/display_6_1749541160.png",
        "size": 245760,
        "width": 1920,
        "height": 1080
      },
      "thumbnail": {
        "path": "/hoody/storage/hoody-display/screenshots/display_6_1749541160_thumb.png",
        "size": 18432,
        "width": 320,
        "height": 180
      }
    }
  ]
}

SDK usage

await client.display.getInformation();

curl "https://proj_8x7k2m-ct_4f9d1a-display-1.eu-west-1.containers.hoody.icu/api/v1/display/info"

GET /api/v1/display/screenshots

Returns a list of all available screenshots for the current display with their metadata.

Parameters

Name	In	Type	Required	Description
displayId	query	integer	No	Display ID to use (overrides the *-display-N.* hostname pattern). Valid range: 1-999999

Response

200

{
  "display": 6,
  "screenshots": [
    {
      "timestamp": "1749541160",
      "timestamp_human": "2026-02-23T16:57:02+00:00",
      "full": {
        "path": "/hoody/storage/hoody-display/screenshots/display_6_1749541160.png",
        "size": 245760,
        "width": 1920,
        "height": 1080
      },
      "thumbnail": {
        "path": "/hoody/storage/hoody-display/screenshots/display_6_1749541160_thumb.png",
        "size": 18432,
        "width": 320,
        "height": 180
      }
    },
    {
      "timestamp": "1749537000",
      "timestamp_human": "2026-02-23T16:50:00+00:00",
      "full": {
        "path": "/hoody/storage/hoody-display/screenshots/display_6_1749537000.png",
        "size": 241102,
        "width": 1920,
        "height": 1080
      },
      "thumbnail": null
    }
  ]
}

SDK usage

await client.display.listScreenshots();

curl "https://proj_8x7k2m-ct_4f9d1a-display-1.eu-west-1.containers.hoody.icu/api/v1/display/screenshots"

Screenshots

GET /api/v1/display/screenshot

Captures a fresh screenshot of the display and returns the image file.

By default the response is a binary PNG image. Pass base64=true to receive a JSON envelope instead, which is useful for AI agents and systems that cannot handle binary data.

Caution

Returns SCREENSHOT_FAILED when screenshot payload is unavailable, for example when the display is inactive or no running programs are present.

Parameters

Name	In	Type	Required	Description
base64	query	boolean	No	Return base64-encoded JSON response instead of binary image. Accepted values: true, 1, empty string — return base64 JSON. false, 0 — return binary (default)
displayId	query	integer	No	Display ID to use (overrides the *-display-N.* hostname pattern). Valid range: 1-999999

Response

200

{
  "info": {
    "timestamp": "1749541160",
    "timestamp_human": "2026-02-23T16:57:02+00:00",
    "full": {
      "path": "/hoody/storage/hoody-display/screenshots/display_6_1749541160.png",
      "size": 245760,
      "width": 1920,
      "height": 1080
    },
    "thumbnail": {
      "path": "/hoody/storage/hoody-display/screenshots/display_6_1749541160_thumb.png",
      "size": 18432,
      "width": 320,
      "height": 180
    }
  },
  "image": {
    "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAAB...",
    "mimeType": "image/png",
    "dataUrl": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg..."
  }
}

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "No display context available"
}

500

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Screenshot capture failed"
}

SDK usage

await client.display.screenshots.capture();

// Base64 JSON response
await client.display.screenshots.capture({ base64: true });

curl -o screenshot.png \
  "https://proj_8x7k2m-ct_4f9d1a-display-1.eu-west-1.containers.hoody.icu/api/v1/display/screenshot"

# Base64 JSON response
curl "https://proj_8x7k2m-ct_4f9d1a-display-1.eu-west-1.containers.hoody.icu/api/v1/display/screenshot?base64=true"

GET /api/v1/display/screenshot/{timestamp}

Retrieves a previously captured screenshot using its Unix timestamp.

Parameters

Name	In	Type	Required	Description
timestamp	path	string	Yes	Unix timestamp of the screenshot. Use the timestamp field returned by screenshot metadata and list endpoints. Do not use timestamp_human for path queries. Must be numeric only for security
base64	query	boolean	No	Return base64-encoded JSON response instead of binary image. Accepted values: true, 1, empty string — return base64 JSON. false, 0 — return binary (default)
displayId	query	integer	No	Display ID to use (overrides the *-display-N.* hostname pattern). Valid range: 1-999999

Response

200

{
  "info": {
    "timestamp": "1749541160",
    "timestamp_human": "2026-02-23T16:57:02+00:00",
    "full": {
      "path": "/hoody/storage/hoody-display/screenshots/display_6_1749541160.png",
      "size": 245760,
      "width": 1920,
      "height": 1080
    },
    "thumbnail": {
      "path": "/hoody/storage/hoody-display/screenshots/display_6_1749541160_thumb.png",
      "size": 18432,
      "width": 320,
      "height": 180
    }
  },
  "image": {
    "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAAB...",
    "mimeType": "image/png",
    "dataUrl": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg..."
  }
}

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid timestamp format"
}

404

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Screenshot not found"
}

SDK usage

await client.display.screenshots.getByTimestamp("1749541160");

// Base64 JSON response
await client.display.screenshots.getByTimestamp("1749541160", { base64: true });

curl -o screenshot.png \
  "https://proj_8x7k2m-ct_4f9d1a-display-1.eu-west-1.containers.hoody.icu/api/v1/display/screenshot/1749541160"

GET /api/v1/display/screenshot/info

Takes a new screenshot but returns only metadata without the image data.

Parameters

Name	In	Type	Required	Description
displayId	query	integer	No	Display ID to use (overrides the *-display-N.* hostname pattern). Valid range: 1-999999

Response

200

{
  "timestamp": "1749541160",
  "timestamp_human": "2026-02-23T16:57:02+00:00",
  "full": {
    "path": "/hoody/storage/hoody-display/screenshots/display_6_1749541160.png",
    "size": 245760,
    "width": 1920,
    "height": 1080
  },
  "thumbnail": {
    "path": "/hoody/storage/hoody-display/screenshots/display_6_1749541160_thumb.png",
    "size": 18432,
    "width": 320,
    "height": 180
  }
}

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "No display context available"
}

500

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Screenshot capture failed"
}

SDK usage

await client.display.screenshots.captureMetadata();

curl "https://proj_8x7k2m-ct_4f9d1a-display-1.eu-west-1.containers.hoody.icu/api/v1/display/screenshot/info"

GET /api/v1/display/screenshot/last

Returns the latest screenshot that was previously captured.

Parameters

Name	In	Type	Required	Description
base64	query	boolean	No	Return base64-encoded JSON response instead of binary image. Accepted values: true, 1, empty string — return base64 JSON. false, 0 — return binary (default)
displayId	query	integer	No	Display ID to use (overrides the *-display-N.* hostname pattern). Valid range: 1-999999

Response

200

{
  "info": {
    "timestamp": "1749541160",
    "timestamp_human": "2026-02-23T16:57:02+00:00",
    "full": {
      "path": "/hoody/storage/hoody-display/screenshots/display_6_1749541160.png",
      "size": 245760,
      "width": 1920,
      "height": 1080
    },
    "thumbnail": {
      "path": "/hoody/storage/hoody-display/screenshots/display_6_1749541160_thumb.png",
      "size": 18432,
      "width": 320,
      "height": 180
    }
  },
  "image": {
    "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAAB...",
    "mimeType": "image/png",
    "dataUrl": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg..."
  }
}

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "No display context available"
}

404

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Screenshot not found"
}

500

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Screenshot capture failed"
}

SDK usage

await client.display.screenshots.getLatest();

// Base64 JSON response
await client.display.screenshots.getLatest({ base64: true });

curl -o screenshot.png \
  "https://proj_8x7k2m-ct_4f9d1a-display-1.eu-west-1.containers.hoody.icu/api/v1/display/screenshot/last"

GET /api/v1/display/screenshot/last/info

Returns metadata about the latest screenshot without downloading the image.

Parameters

Name	In	Type	Required	Description
displayId	query	integer	No	Display ID to use (overrides the *-display-N.* hostname pattern). Valid range: 1-999999

Response

200

{
  "timestamp": "1749541160",
  "timestamp_human": "2026-02-23T16:57:02+00:00",
  "full": {
    "path": "/hoody/storage/hoody-display/screenshots/display_6_1749541160.png",
    "size": 245760,
    "width": 1920,
    "height": 1080
  },
  "thumbnail": {
    "path": "/hoody/storage/hoody-display/screenshots/display_6_1749541160_thumb.png",
    "size": 18432,
    "width": 320,
    "height": 180
  }
}

SDK usage

await client.display.screenshots.getLatestMetadata();

curl "https://proj_8x7k2m-ct_4f9d1a-display-1.eu-west-1.containers.hoody.icu/api/v1/display/screenshot/last/info"

Thumbnails

Thumbnails are 320x180 scaled versions of screenshots and are useful for previews and gallery listings.

GET /api/v1/display/thumbnail

Captures a new screenshot and returns the thumbnail version.

Parameters

Name	In	Type	Required	Description
base64	query	boolean	No	Return base64-encoded JSON response instead of binary image. Accepted values: true, 1, empty string — return base64 JSON. false, 0 — return binary (default)
displayId	query	integer	No	Display ID to use (overrides the *-display-N.* hostname pattern). Valid range: 1-999999

Response

200

{
  "info": {
    "timestamp": "1749541160",
    "timestamp_human": "2026-02-23T16:57:02+00:00",
    "full": {
      "path": "/hoody/storage/hoody-display/screenshots/display_6_1749541160.png",
      "size": 245760,
      "width": 1920,
      "height": 1080
    },
    "thumbnail": {
      "path": "/hoody/storage/hoody-display/screenshots/display_6_1749541160_thumb.png",
      "size": 18432,
      "width": 320,
      "height": 180
    }
  },
  "image": {
    "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAAB...",
    "mimeType": "image/png",
    "dataUrl": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg..."
  }
}

404

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Thumbnail not found"
}

SDK usage

await client.display.thumbnails.capture();

// Base64 JSON response
await client.display.thumbnails.capture({ base64: true });

curl -o thumbnail.png \
  "https://proj_8x7k2m-ct_4f9d1a-display-1.eu-west-1.containers.hoody.icu/api/v1/display/thumbnail"

GET /api/v1/display/thumbnail/{timestamp}

Retrieves the thumbnail for a specific screenshot by its Unix timestamp.

Parameters

Name	In	Type	Required	Description
timestamp	path	string	Yes	Unix timestamp of the screenshot. Use the timestamp field returned by screenshot metadata and list endpoints. Do not use timestamp_human for path queries. Must be numeric only for security
base64	query	boolean	No	Return base64-encoded JSON response instead of binary image. Accepted values: true, 1, empty string — return base64 JSON. false, 0 — return binary (default)
displayId	query	integer	No	Display ID to use (overrides the *-display-N.* hostname pattern). Valid range: 1-999999

Response

200

{
  "info": {
    "timestamp": "1749541160",
    "timestamp_human": "2026-02-23T16:57:02+00:00",
    "full": {
      "path": "/hoody/storage/hoody-display/screenshots/display_6_1749541160.png",
      "size": 245760,
      "width": 1920,
      "height": 1080
    },
    "thumbnail": {
      "path": "/hoody/storage/hoody-display/screenshots/display_6_1749541160_thumb.png",
      "size": 18432,
      "width": 320,
      "height": 180
    }
  },
  "image": {
    "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAAB...",
    "mimeType": "image/png",
    "dataUrl": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg..."
  }
}

404

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Thumbnail not found"
}

SDK usage

await client.display.thumbnails.getByTimestamp("1749541160");

// Base64 JSON response
await client.display.thumbnails.getByTimestamp("1749541160", { base64: true });

curl -o thumbnail.png \
  "https://proj_8x7k2m-ct_4f9d1a-display-1.eu-west-1.containers.hoody.icu/api/v1/display/thumbnail/1749541160"

GET /api/v1/display/thumbnail/last

Returns the thumbnail of the latest screenshot.

Parameters

Name	In	Type	Required	Description
base64	query	boolean	No	Return base64-encoded JSON response instead of binary image. Accepted values: true, 1, empty string — return base64 JSON. false, 0 — return binary (default)
displayId	query	integer	No	Display ID to use (overrides the *-display-N.* hostname pattern). Valid range: 1-999999

Response

200

{
  "info": {
    "timestamp": "1749541160",
    "timestamp_human": "2026-02-23T16:57:02+00:00",
    "full": {
      "path": "/hoody/storage/hoody-display/screenshots/display_6_1749541160.png",
      "size": 245760,
      "width": 1920,
      "height": 1080
    },
    "thumbnail": {
      "path": "/hoody/storage/hoody-display/screenshots/display_6_1749541160_thumb.png",
      "size": 18432,
      "width": 320,
      "height": 180
    }
  },
  "image": {
    "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAAB...",
    "mimeType": "image/png",
    "dataUrl": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg..."
  }
}

404

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Thumbnail not found"
}

SDK usage

await client.display.thumbnails.getLatest();

// Base64 JSON response
await client.display.thumbnails.getLatest({ base64: true });

curl -o thumbnail.png \
  "https://proj_8x7k2m-ct_4f9d1a-display-1.eu-west-1.containers.hoody.icu/api/v1/display/thumbnail/last"

Windows

GET /api/v1/display/windows

Lists the windows currently present on the display, including geometry and focus state.

Parameters

Name	In	Type	Required	Description
displayId	query	integer	No	Display ID to use (overrides the *-display-N.* hostname pattern). Valid range: 1-999999
onlyVisible	query	boolean	No	If true, only include visible windows

Response

200

{
  "success": true,
  "display": 6,
  "focusedWindowId": 4194305,
  "windows": [
    {
      "windowId": 4194305,
      "name": "Main — MyApp",
      "class": ["myapp", "Myapp"],
      "desktop": 0,
      "geometry": {
        "x": 120,
        "y": 80,
        "width": 1680,
        "height": 920
      },
      "focused": true,
      "states": ["Modal", "Active"]
    }
  ]
}

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "No display context available"
}

500

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Input action failed"
}

503

{
  "statusCode": 503,
  "error": "Service Unavailable",
  "message": "Display not available"
}

SDK usage

await client.display.listWindows();

// Only visible windows
await client.display.listWindows({ onlyVisible: true });

curl "https://proj_8x7k2m-ct_4f9d1a-display-1.eu-west-1.containers.hoody.icu/api/v1/display/windows?onlyVisible=true"

GET /api/v1/display/window/{windowId}/properties

Retrieves extended properties for a specific window, including wmClass, wmName, wmRole, pid, and wmState.

Parameters

Name	In	Type	Required	Description
windowId	path	string	Yes	Window ID (decimal or hex 0x...)
displayId	query	integer	No	Display ID to use (overrides the *-display-N.* hostname pattern). Valid range: 1-999999

Response

200

{
  "success": true,
  "windowId": "0x400001",
  "properties": {
    "wmClass": ["myapp", "Myapp"],
    "wmName": "Main — MyApp",
    "wmRole": "MainWindow",
    "pid": 4123,
    "wmState": ["Modal", "Active"],
    "wmType": ["Normal"],
    "transientFor": null
  }
}

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "No display context available"
}

404

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Window not found"
}

500

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Input action failed"
}

503

{
  "statusCode": 503,
  "error": "Service Unavailable",
  "message": "Display not available"
}

SDK usage

await client.display.getWindowProperties("0x400001");

curl "https://proj_8x7k2m-ct_4f9d1a-display-1.eu-west-1.containers.hoody.icu/api/v1/display/window/0x400001/properties"

Clipboard

GET /api/v1/display/clipboard

Reads the current clipboard text. Supports the standard X11-style selections: clipboard, primary, and secondary.

Parameters

Name	In	Type	Required	Description
displayId	query	integer	No	Display ID to use (overrides the *-display-N.* hostname pattern). Valid range: 1-999999
selection	query	string	No	Clipboard buffer selection. Allowed values: clipboard (default), primary, secondary

Response

200

{
  "success": true,
  "text": "echo hello world",
  "selection": "clipboard"
}

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "No display context available"
}

500

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Input action failed"
}

503

{
  "statusCode": 503,
  "error": "Service Unavailable",
  "message": "Display not available"
}

SDK usage

await client.display.getClipboard();

// Read from the primary selection
await client.display.getClipboard({ selection: "primary" });

curl "https://proj_8x7k2m-ct_4f9d1a-display-1.eu-west-1.containers.hoody.icu/api/v1/display/clipboard"

# Read from the primary selection
curl "https://proj_8x7k2m-ct_4f9d1a-display-1.eu-west-1.containers.hoody.icu/api/v1/display/clipboard?selection=primary"

POST /api/v1/display/clipboard

Writes text to the clipboard. The text field is required and capped at 1048576 bytes; selection defaults to clipboard and accepts clipboard, primary, or secondary.

Parameters

Name	In	Type	Required	Description
displayId	query	integer	No	Display ID to use (overrides the *-display-N.* hostname pattern). Valid range: 1-999999

Request Body

Name	Type	Required	Description
text	string	Yes	Clipboard text content. Maximum length 1048576 bytes
selection	string	No	Clipboard buffer selection. Allowed values: clipboard (default), primary, secondary

{
  "text": "echo hello world",
  "selection": "clipboard"
}

Response

200

{
  "success": true,
  "action": "clipboard_set",
  "details": {}
}

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "No display context available"
}

500

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Input action failed"
}

503

{
  "statusCode": 503,
  "error": "Service Unavailable",
  "message": "Display not available"
}

SDK usage

await client.display.setClipboard({
  text: "echo hello world",
  selection: "clipboard"
});

curl -X POST "https://proj_8x7k2m-ct_4f9d1a-display-1.eu-west-1.containers.hoody.icu/api/v1/display/clipboard" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "echo hello world",
    "selection": "clipboard"
  }'