The Display Screenshot API provides endpoints to capture, retrieve, and manage display screenshots, thumbnails, window information, and clipboard contents. Use these endpoints to integrate visual display access into applications, build screenshot inventory systems, or programmatically interact with a display’s window manager.

All endpoints accept an optional displayId query parameter to target a specific display, overriding the *-display-N.* hostname pattern.

Display Information

GET /api/v1/display/info

Retrieves information about the current display including all available screenshots. This is the standardized RESTful version of /display.

Use this for: RESTful API integrations, display management systems, screenshot inventory queries.

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": 12800,
        "width": 320,
        "height": 180
      }
    }
  ]
}

SDK Usage

const result = await client.display.getInformation({
  displayId: 6,
});

GET /api/v1/display/screenshots

Returns a list of all available screenshots for the current display with their metadata. Standardized API version of /screenshots.

Use this for: RESTful API integrations, screenshot management applications, historical screenshot browsing.

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": 12800,
        "width": 320,
        "height": 180
      }
    },
    {
      "timestamp": "1749537600",
      "timestamp_human": "2026-02-23T16:00:00+00:00",
      "full": {
        "path": "/hoody/storage/hoody-display/screenshots/display_6_1749537600.png",
        "size": 238104,
        "width": 1920,
        "height": 1080
      },
      "thumbnail": null
    }
  ]
}

SDK Usage

const result = await client.display.listScreenshots({
  displayId: 6,
});

Screenshots

GET /api/v1/display/screenshot

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

Response Formats:

• Binary PNG image (default)
• Base64 JSON (with ?base64=true)

Caution

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

Parameters

Name	In	Type	Required	Description
base64	query	boolean	No	Return 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)
displayId	query	integer	No	Display ID to use (overrides the *-display-N.* hostname pattern). Valid range: 1-999999

Response

200 (Base64 JSON)

{
  "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": 12800,
      "width": 320,
      "height": 180
    }
  },
  "image": {
    "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=",
    "mimeType": "image/png",
    "dataUrl": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII="
  }
}

200 (Binary PNG)

Content-Type: image/png

<binary PNG data>

400

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

500

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

SDK Usage

const result = await client.display.screenshots.capture({
  displayId: 6,
  base64: true,
});

GET /api/v1/display/screenshot/info

Takes a new screenshot but returns only metadata without the image data. Standardized API version of /screenshot/info.

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": 12800,
    "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",
  "code": "SCREENSHOT_FAILED"
}

SDK Usage

const result = await client.display.screenshots.captureMetadata({
  displayId: 6,
});

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

Retrieves a previously captured screenshot using its Unix timestamp. Standardized API version of /screenshot/{timestamp}.

Parameters

Name	In	Type	Required	Description
timestamp	path	string	Yes	Unix timestamp of the screenshot. Use the timestamp field returned by screenshot metadata/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. 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)
displayId	query	integer	No	Display ID to use (overrides the *-display-N.* hostname pattern). Valid range: 1-999999

Response

200 (Base64 JSON)

{
  "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": 12800,
      "width": 320,
      "height": 180
    }
  },
  "image": {
    "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=",
    "mimeType": "image/png",
    "dataUrl": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII="
  }
}

200 (Binary PNG)

Content-Type: image/png

<binary PNG data>

400

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

404

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Screenshot not found for the specified timestamp",
  "code": "SCREENSHOT_NOT_FOUND"
}

SDK Usage

const result = await client.display.screenshots.getByTimestamp({
  timestamp: "1749541160",
  displayId: 6,
});

GET /api/v1/display/screenshot/last

Returns the latest screenshot that was previously captured. Standardized API version of /screenshot/last.

Parameters

Name	In	Type	Required	Description
base64	query	boolean	No	Return 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)
displayId	query	integer	No	Display ID to use (overrides the *-display-N.* hostname pattern). Valid range: 1-999999

Response

200 (Base64 JSON)

{
  "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": 12800,
      "width": 320,
      "height": 180
    }
  },
  "image": {
    "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=",
    "mimeType": "image/png",
    "dataUrl": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII="
  }
}

200 (Binary PNG)

Content-Type: image/png

<binary PNG data>

400

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

404

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "No screenshot available",
  "code": "SCREENSHOT_NOT_FOUND"
}

500

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Screenshot retrieval failed",
  "code": "SCREENSHOT_FAILED"
}

SDK Usage

const result = await client.display.screenshots.getLatest({
  displayId: 6,
});

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

Returns metadata about the latest screenshot without downloading the image. Standardized API version of /screenshot/last/info.

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": 12800,
    "width": 320,
    "height": 180
  }
}

SDK Usage

const result = await client.display.screenshots.getLatestMetadata({
  displayId: 6,
});

Thumbnails

GET /api/v1/display/thumbnail

Captures a new screenshot and returns the thumbnail version (320x180 scaled). Standardized API version of /thumbnail.

Parameters

Name	In	Type	Required	Description
base64	query	boolean	No	Return 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)
displayId	query	integer	No	Display ID to use (overrides the *-display-N.* hostname pattern). Valid range: 1-999999

Response

200 (Base64 JSON)

{
  "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": 12800,
      "width": 320,
      "height": 180
    }
  },
  "image": {
    "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=",
    "mimeType": "image/png",
    "dataUrl": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII="
  }
}

200 (Binary PNG)

Content-Type: image/png

<binary PNG data>

404

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

SDK Usage

const result = await client.display.thumbnails.capture({
  displayId: 6,
});

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

Retrieves the thumbnail for a specific screenshot by its Unix timestamp. Standardized API version of /thumbnail/{timestamp}.

Parameters

Name	In	Type	Required	Description
timestamp	path	string	Yes	Unix timestamp of the screenshot. Use the timestamp field returned by screenshot metadata/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. 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)
displayId	query	integer	No	Display ID to use (overrides the *-display-N.* hostname pattern). Valid range: 1-999999

Response

200 (Base64 JSON)

{
  "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": 12800,
      "width": 320,
      "height": 180
    }
  },
  "image": {
    "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=",
    "mimeType": "image/png",
    "dataUrl": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII="
  }
}

200 (Binary PNG)

Content-Type: image/png

<binary PNG data>

404

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Thumbnail not found for the specified timestamp",
  "code": "THUMBNAIL_NOT_FOUND"
}

SDK Usage

const result = await client.display.thumbnails.getByTimestamp({
  timestamp: "1749541160",
  displayId: 6,
});

GET /api/v1/display/thumbnail/last

Returns the thumbnail of the latest screenshot. Standardized API version of /thumbnail/last.

Parameters

Name	In	Type	Required	Description
base64	query	boolean	No	Return 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)
displayId	query	integer	No	Display ID to use (overrides the *-display-N.* hostname pattern). Valid range: 1-999999

Response

200 (Base64 JSON)

{
  "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": 12800,
      "width": 320,
      "height": 180
    }
  },
  "image": {
    "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=",
    "mimeType": "image/png",
    "dataUrl": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII="
  }
}

200 (Binary PNG)

Content-Type: image/png

<binary PNG data>

404

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "No thumbnail available",
  "code": "THUMBNAIL_NOT_FOUND"
}

SDK Usage

const result = await client.display.thumbnails.getLatest({
  displayId: 6,
});

Windows

GET /api/v1/display/windows

Lists all windows on the current display, optionally filtered to visible windows only.

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": 1048579,
  "windows": [
    {
      "windowId": 1048579,
      "name": "Terminal — bash",
      "class": ["terminal", "Terminal"],
      "desktop": 0,
      "geometry": {
        "x": 120,
        "y": 80,
        "width": 1024,
        "height": 768
      },
      "focused": true,
      "states": ["focused", "active"]
    },
    {
      "windowId": 1048580,
      "name": "Code Editor",
      "class": ["code", "Code"],
      "desktop": 0,
      "geometry": {
        "x": 0,
        "y": 0,
        "width": 1920,
        "height": 1080
      },
      "focused": false,
      "states": ["maximized"]
    }
  ]
}

400

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

500

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Window listing failed",
  "code": "INPUT_ACTION_FAILED"
}

503

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

SDK Usage

const result = await client.display.listWindows({
  displayId: 6,
  onlyVisible: true,
});

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

Retrieves extended properties for a specific window, including WM class, name, role, PID, and state information.

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": "1048579",
  "properties": {
    "wmClass": ["terminal", "Terminal"],
    "wmName": "Terminal — bash",
    "wmRole": "terminal",
    "pid": 4321,
    "wmState": ["focused", "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 for the specified windowId",
  "code": "WINDOW_NOT_FOUND"
}

500

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Window property retrieval failed",
  "code": "INPUT_ACTION_FAILED"
}

503

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

SDK Usage

const result = await client.display.getWindowProperties({
  windowId: "1048579",
  displayId: 6,
});

Clipboard

GET /api/v1/display/clipboard

Reads the current clipboard text from a specific buffer selection. Use the selection parameter to target the primary, secondary, or clipboard buffer.

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. Default: "clipboard". Allowed values: "clipboard", "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": "Clipboard read failed",
  "code": "INPUT_ACTION_FAILED"
}

503

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

SDK Usage

const result = await client.display.getClipboard({
  displayId: 6,
  selection: "clipboard",
});

POST /api/v1/display/clipboard

Writes text to the display’s clipboard buffer.

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. Max length: 1,048,576 characters
selection	string	No	Clipboard buffer selection. Default: "clipboard". Allowed values: "clipboard", "primary", "secondary"

{
  "text": "echo 'Hello, world!'",
  "selection": "clipboard"
}

Response

200

{
  "success": true,
  "action": "clipboard_write",
  "details": {
    "bytes_written": 21,
    "selection": "clipboard"
  }
}

400

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

500

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Clipboard write failed",
  "code": "INPUT_ACTION_FAILED"
}

503

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

SDK Usage

const result = await client.display.setClipboard({
  displayId: 6,
  data: {
    text: "echo 'Hello, world!'",
    selection: "clipboard",
  },
});