Skip to content

The Displays: Screenshot API provides RESTful endpoints for capturing display screenshots, retrieving previously captured screenshots by timestamp, generating thumbnails, and managing clipboard text. Use these endpoints to build display monitoring tools, screenshot history browsers, and AI-driven visual inspection pipelines.

All endpoints accept an optional displayId query parameter to target a specific display, overriding the *-display-N.* hostname pattern. Image responses can be returned as binary PNG (default) or as a base64-encoded JSON object using ?base64=true.


Retrieves information about the current display, including a list of all available screenshots with their metadata. This is the standardized API version of /display.

Use this for:

  • RESTful API integrations
  • Display management systems
  • Screenshot inventory queries
NameInTypeRequiredDescription
displayIdqueryintegerNoDisplay ID to use (overrides the *-display-N.* hostname pattern). Valid range: 1-999999
const result = await client.display.getInformation({ displayId: 6 });
result = client.display.get_information(display_id=6)
Terminal window
curl -X GET "https://api.hoody.com/api/v1/display/info?displayId=6" \
-H "Authorization: Bearer <token>"
{
"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": 12288,
"width": 320,
"height": 180
}
}
]
}

Lists all windows currently open on the target display, including the focused window ID. Use onlyVisible=true to exclude hidden or minimized windows.

NameInTypeRequiredDescription
displayIdqueryintegerNoDisplay ID to use (overrides the *-display-N.* hostname pattern). Valid range: 1-999999
onlyVisiblequerybooleanNoIf true, only include visible windows
const result = await client.display.listWindows({ displayId: 6, onlyVisible: true });
result = client.display.list_windows(display_id=6, only_visible=True)
Terminal window
curl -X GET "https://api.hoody.com/api/v1/display/windows?displayId=6&onlyVisible=true" \
-H "Authorization: Bearer <token>"
{
"success": true,
"display": 6,
"focusedWindowId": 1048576,
"windows": [
{
"windowId": 1048576,
"name": "Hoody Terminal",
"class": ["hoody-terminal", "Hoody-terminal"],
"desktop": 0,
"geometry": {
"x": 100,
"y": 100,
"width": 1200,
"height": 800
},
"focused": true,
"states": ["MAXIMIZED_VERT", "FOCUSED"]
}
]
}
Error CodeTitleDescriptionResolution
NO_DISPLAY_CONTEXTNo display contextThe request could not be associated with any active displayEnsure you are routing the request to the correct display hostname or pass a valid displayId
Error CodeTitleDescriptionResolution
INPUT_ACTION_FAILEDInput action failedThe window list operation failed at the input layerRetry the request; if the failure persists, check the display agent logs
Error CodeTitleDescriptionResolution
DISPLAY_NOT_AVAILABLEDisplay not availableThe target display is not currently availableVerify the display is powered on and the agent is connected

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

Section titled “GET /api/v1/display/window/{windowId}/properties”

Retrieves extended EWMH properties for a specific window, including WM class, name, role, PID, state, and transient-for relationship.

NameInTypeRequiredDescription
windowIdpathstringYesWindow ID (decimal or hex 0x...)
displayIdqueryintegerNoDisplay ID to use (overrides the *-display-N.* hostname pattern). Valid range: 1-999999
const result = await client.display.getWindowProperties({ windowId: "1048576", displayId: 6 });
result = client.display.get_window_properties(window_id="1048576", display_id=6)
Terminal window
curl -X GET "https://api.hoody.com/api/v1/display/window/1048576/properties?displayId=6" \
-H "Authorization: Bearer <token>"
{
"success": true,
"windowId": "1048576",
"properties": {
"wmClass": ["hoody-terminal", "Hoody-terminal"],
"wmName": "Hoody Terminal — main",
"wmRole": "terminal",
"pid": 4218,
"wmState": ["NORMAL"],
"wmType": ["NORMAL"],
"transientFor": null
}
}
Error CodeTitleDescriptionResolution
NO_DISPLAY_CONTEXTNo display contextThe request could not be associated with any active displayEnsure you are routing the request to the correct display hostname or pass a valid displayId
Error CodeTitleDescriptionResolution
WINDOW_NOT_FOUNDWindow not foundNo window matches the provided windowId on the target displayVerify the window ID is valid and the window is still open
Error CodeTitleDescriptionResolution
INPUT_ACTION_FAILEDInput action failedThe window properties operation failed at the input layerRetry the request; if the failure persists, check the display agent logs
Error CodeTitleDescriptionResolution
DISPLAY_NOT_AVAILABLEDisplay not availableThe target display is not currently availableVerify the display is powered on and the agent is connected

Reads text from a display clipboard buffer. By default, the standard clipboard selection is read; use the selection parameter to read from the primary or secondary X11 selections.

NameInTypeRequiredDescription
displayIdqueryintegerNoDisplay ID to use (overrides the *-display-N.* hostname pattern). Valid range: 1-999999
selectionquerystringNoClipboard buffer selection. Default: "clipboard". Allowed values: clipboard, primary, secondary
const result = await client.display.getClipboard({ displayId: 6, selection: "clipboard" });
result = client.display.get_clipboard(display_id=6, selection="clipboard")
Terminal window
curl -X GET "https://api.hoody.com/api/v1/display/clipboard?displayId=6&selection=clipboard" \
-H "Authorization: Bearer <token>"
{
"success": true,
"text": "echo 'Hello from clipboard'",
"selection": "clipboard"
}
Error CodeTitleDescriptionResolution
NO_DISPLAY_CONTEXTNo display contextThe request could not be associated with any active displayEnsure you are routing the request to the correct display hostname or pass a valid displayId
Error CodeTitleDescriptionResolution
INPUT_ACTION_FAILEDInput action failedThe clipboard read operation failed at the input layerRetry the request; if the failure persists, check the display agent logs
Error CodeTitleDescriptionResolution
DISPLAY_NOT_AVAILABLEDisplay not availableThe target display is not currently availableVerify the display is powered on and the agent is connected

Writes text to a display clipboard buffer. The text payload is required and may be up to 1,048,576 characters. By default, text is written to the standard clipboard selection; use the selection field to target primary or secondary.

NameInTypeRequiredDescription
displayIdqueryintegerNoDisplay ID to use (overrides the *-display-N.* hostname pattern). Valid range: 1-999999

The request body is a JSON object with the following fields:

NameTypeRequiredDescription
textstringYesClipboard text content. Max length: 1,048,576 characters
selectionstringNoClipboard buffer selection. Default: "clipboard". Allowed values: clipboard, primary, secondary
const result = await client.display.setClipboard({
displayId: 6,
data: {
text: "echo 'Hello from Hoody'",
selection: "clipboard"
}
});
result = client.display.set_clipboard(
display_id=6,
data={
"text": "echo 'Hello from Hoody'",
"selection": "clipboard"
}
)
Terminal window
curl -X POST "https://api.hoody.com/api/v1/display/clipboard?displayId=6" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
"text": "echo '\''Hello from Hoody'\''",
"selection": "clipboard"
}'
{
"success": true,
"action": "clipboard_write",
"details": {
"selection": "clipboard",
"length": 24
}
}
Error CodeTitleDescriptionResolution
NO_DISPLAY_CONTEXTNo display contextThe request could not be associated with any active displayEnsure you are routing the request to the correct display hostname or pass a valid displayId
Error CodeTitleDescriptionResolution
INPUT_ACTION_FAILEDInput action failedThe clipboard write operation failed at the input layerRetry the request; if the failure persists, check the display agent logs
Error CodeTitleDescriptionResolution
DISPLAY_NOT_AVAILABLEDisplay not availableThe target display is not currently availableVerify the display is powered on and the agent is connected

Captures a fresh screenshot of the display and returns the image file. This is the standardized API endpoint, identical to /screenshot.

Response formats:

  • Binary PNG image (default)
  • Base64 JSON (with ?base64=true)
NameInTypeRequiredDescription
base64querybooleanNoReturn base64-encoded JSON response instead of binary image. Useful for AI agents and systems that can’t handle binary data. Accepted values: true, 1, “ (empty) return base64 JSON; false, 0 return binary (default)
displayIdqueryintegerNoDisplay ID to use (overrides the *-display-N.* hostname pattern). Valid range: 1-999999
const result = await client.display.screenshots.capture({ base64: true, displayId: 6 });
result = client.display.screenshots.capture(base64=True, display_id=6)
Terminal window
curl -X GET "https://api.hoody.com/api/v1/display/screenshot?displayId=6&base64=true" \
-H "Authorization: Bearer <token>"
{
"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": 12288,
"width": 320,
"height": 180
}
},
"image": {
"data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=",
"mimeType": "image/png",
"dataUrl": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII="
}
}
Error CodeTitleDescriptionResolution
NO_DISPLAY_CONTEXTNo display contextThe request could not be associated with any active displayEnsure you are routing the request to the correct display hostname or pass a valid displayId
Error CodeTitleDescriptionResolution
SCREENSHOT_FAILEDScreenshot failedThe screenshot payload is unavailable (inactive display, no running programs, or capture error)Verify the display is active and has running content, then retry

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

Section titled “GET /api/v1/display/screenshot/{timestamp}”

Retrieves a previously captured screenshot using its Unix timestamp. Use the timestamp field returned by screenshot metadata or list endpoints — do not use timestamp_human for path queries.

NameInTypeRequiredDescription
timestamppathstringYesUnix timestamp of the screenshot. Must be numeric only for security
base64querybooleanNoReturn base64-encoded JSON response instead of binary image. Useful for AI agents and systems that can’t handle binary data. Accepted values: true, 1, “ (empty) return base64 JSON; false, 0 return binary (default)
displayIdqueryintegerNoDisplay ID to use (overrides the *-display-N.* hostname pattern). Valid range: 1-999999
const result = await client.display.screenshots.getByTimestamp({
timestamp: "1749541160",
base64: true,
displayId: 6
});
result = client.display.screenshots.get_by_timestamp(
timestamp="1749541160",
base64=True,
display_id=6
)
Terminal window
curl -X GET "https://api.hoody.com/api/v1/display/screenshot/1749541160?displayId=6&base64=true" \
-H "Authorization: Bearer <token>"
{
"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": 12288,
"width": 320,
"height": 180
}
},
"image": {
"data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=",
"mimeType": "image/png",
"dataUrl": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII="
}
}
Error CodeTitleDescriptionResolution
INVALID_TIMESTAMPInvalid timestampThe provided timestamp is not numeric or has an invalid formatEnsure the timestamp is a numeric Unix timestamp string
Error CodeTitleDescriptionResolution
SCREENSHOT_NOT_FOUNDScreenshot not foundNo screenshot exists for the given timestamp on the target displayVerify the timestamp by listing available screenshots, then retry

Takes a new screenshot but returns only metadata, without the image data. Use this endpoint when you only need to record the capture timestamp and file information.

NameInTypeRequiredDescription
displayIdqueryintegerNoDisplay ID to use (overrides the *-display-N.* hostname pattern). Valid range: 1-999999
const result = await client.display.screenshots.captureMetadata({ displayId: 6 });
result = client.display.screenshots.capture_metadata(display_id=6)
Terminal window
curl -X GET "https://api.hoody.com/api/v1/display/screenshot/info?displayId=6" \
-H "Authorization: Bearer <token>"
{
"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": 12288,
"width": 320,
"height": 180
}
}
Error CodeTitleDescriptionResolution
NO_DISPLAY_CONTEXTNo display contextThe request could not be associated with any active displayEnsure you are routing the request to the correct display hostname or pass a valid displayId
Error CodeTitleDescriptionResolution
SCREENSHOT_FAILEDScreenshot failedThe screenshot payload is unavailable (inactive display, no running programs, or capture error)Verify the display is active and has running content, then retry

Returns the most recently captured screenshot. This is the standardized API version of /screenshot/last.

NameInTypeRequiredDescription
base64querybooleanNoReturn base64-encoded JSON response instead of binary image. Useful for AI agents and systems that can’t handle binary data. Accepted values: true, 1, “ (empty) return base64 JSON; false, 0 return binary (default)
displayIdqueryintegerNoDisplay ID to use (overrides the *-display-N.* hostname pattern). Valid range: 1-999999
const result = await client.display.screenshots.getLatest({ base64: true, displayId: 6 });
result = client.display.screenshots.get_latest(base64=True, display_id=6)
Terminal window
curl -X GET "https://api.hoody.com/api/v1/display/screenshot/last?displayId=6&base64=true" \
-H "Authorization: Bearer <token>"
{
"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": 12288,
"width": 320,
"height": 180
}
},
"image": {
"data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=",
"mimeType": "image/png",
"dataUrl": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII="
}
}
Error CodeTitleDescriptionResolution
NO_DISPLAY_CONTEXTNo display contextThe request could not be associated with any active displayEnsure you are routing the request to the correct display hostname or pass a valid displayId
Error CodeTitleDescriptionResolution
SCREENSHOT_NOT_FOUNDScreenshot not foundNo screenshots are available for the target displayCapture a new screenshot first, then retry
Error CodeTitleDescriptionResolution
SCREENSHOT_FAILEDScreenshot failedThe latest screenshot payload is unavailable or corruptedCapture a new screenshot, then retry

Returns metadata about the most recent screenshot without downloading the image data.

NameInTypeRequiredDescription
displayIdqueryintegerNoDisplay ID to use (overrides the *-display-N.* hostname pattern). Valid range: 1-999999
const result = await client.display.screenshots.getLatestMetadata({ displayId: 6 });
result = client.display.screenshots.get_latest_metadata(display_id=6)
Terminal window
curl -X GET "https://api.hoody.com/api/v1/display/screenshot/last/info?displayId=6" \
-H "Authorization: Bearer <token>"
{
"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": 12288,
"width": 320,
"height": 180
}
}

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

Use this for:

  • RESTful API integrations
  • Screenshot management applications
  • Historical screenshot browsing
NameInTypeRequiredDescription
displayIdqueryintegerNoDisplay ID to use (overrides the *-display-N.* hostname pattern). Valid range: 1-999999
const result = await client.display.listScreenshots({ displayId: 6 });
result = client.display.list_screenshots(display_id=6)
Terminal window
curl -X GET "https://api.hoody.com/api/v1/display/screenshots?displayId=6" \
-H "Authorization: Bearer <token>"
{
"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": 12288,
"width": 320,
"height": 180
}
}
]
}

Thumbnails are 320x180 scaled-down versions of full screenshots, useful for previews, galleries, and low-bandwidth review tools.

Captures a new screenshot and returns the thumbnail version (320x180 scaled).

NameInTypeRequiredDescription
base64querybooleanNoReturn base64-encoded JSON response instead of binary image. Useful for AI agents and systems that can’t handle binary data. Accepted values: true, 1, “ (empty) return base64 JSON; false, 0 return binary (default)
displayIdqueryintegerNoDisplay ID to use (overrides the *-display-N.* hostname pattern). Valid range: 1-999999
const result = await client.display.thumbnails.capture({ base64: true, displayId: 6 });
result = client.display.thumbnails.capture(base64=True, display_id=6)
Terminal window
curl -X GET "https://api.hoody.com/api/v1/display/thumbnail?displayId=6&base64=true" \
-H "Authorization: Bearer <token>"
{
"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": 12288,
"width": 320,
"height": 180
}
},
"image": {
"data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=",
"mimeType": "image/png",
"dataUrl": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII="
}
}
Error CodeTitleDescriptionResolution
THUMBNAIL_NOT_FOUNDThumbnail not foundThe thumbnail could not be generated or retrieved for the target displayVerify the display is active, then retry

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

NameInTypeRequiredDescription
timestamppathstringYesUnix timestamp of the screenshot. Must be numeric only for security
base64querybooleanNoReturn base64-encoded JSON response instead of binary image. Useful for AI agents and systems that can’t handle binary data. Accepted values: true, 1, “ (empty) return base64 JSON; false, 0 return binary (default)
displayIdqueryintegerNoDisplay ID to use (overrides the *-display-N.* hostname pattern). Valid range: 1-999999
const result = await client.display.thumbnails.getByTimestamp({
timestamp: "1749541160",
base64: true,
displayId: 6
});
result = client.display.thumbnails.get_by_timestamp(
timestamp="1749541160",
base64=True,
display_id=6
)
Terminal window
curl -X GET "https://api.hoody.com/api/v1/display/thumbnail/1749541160?displayId=6&base64=true" \
-H "Authorization: Bearer <token>"
{
"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": 12288,
"width": 320,
"height": 180
}
},
"image": {
"data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=",
"mimeType": "image/png",
"dataUrl": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII="
}
}
Error CodeTitleDescriptionResolution
THUMBNAIL_NOT_FOUNDThumbnail not foundNo thumbnail exists for the given timestamp on the target displayVerify the timestamp by listing available screenshots, then retry

Returns the thumbnail of the most recent screenshot.

NameInTypeRequiredDescription
base64querybooleanNoReturn base64-encoded JSON response instead of binary image. Useful for AI agents and systems that can’t handle binary data. Accepted values: true, 1, “ (empty) return base64 JSON; false, 0 return binary (default)
displayIdqueryintegerNoDisplay ID to use (overrides the *-display-N.* hostname pattern). Valid range: 1-999999
const result = await client.display.thumbnails.getLatest({ base64: true, displayId: 6 });
result = client.display.thumbnails.get_latest(base64=True, display_id=6)
Terminal window
curl -X GET "https://api.hoody.com/api/v1/display/thumbnail/last?displayId=6&base64=true" \
-H "Authorization: Bearer <token>"
{
"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": 12288,
"width": 320,
"height": 180
}
},
"image": {
"data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=",
"mimeType": "image/png",
"dataUrl": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII="
}
}
Error CodeTitleDescriptionResolution
THUMBNAIL_NOT_FOUNDThumbnail not foundNo latest thumbnail is available for the target displayCapture a new screenshot first, then retry