Displays: Screenshot API

Capture, retrieve, and manage display screenshots, thumbnails, window listings, and clipboard contents from a containerized display instance. Use these endpoints to integrate visual capture into automated workflows, build screenshot-based user interfaces, query historical captures, or inspect the state of windows on the display. All requests target the display service hostname of your container.

Note

Screenshots and thumbnails can be returned as binary PNG images or as base64-encoded JSON (pass base64=true). The base64 form is recommended for AI agents and systems that cannot handle raw binary payloads.

Display Information

GET /api/v1/display/info

Retrieve information about the current display, including the list of available screenshots.

cURL

curl -X GET "https://{projectId}-{containerId}-display-1.{server}.containers.hoody.com/api/v1/display/info" \
  -H "Authorization: Bearer $HOODY_TOKEN"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-display-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.display.getInformation();

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
      }
    }
  ]
}

Parameters

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

GET /api/v1/display/screenshots

List all available screenshots for the current display with their metadata. Useful for screenshot management applications and historical browsing.

cURL

curl -X GET "https://{projectId}-{containerId}-display-1.{server}.containers.hoody.com/api/v1/display/screenshots" \
  -H "Authorization: Bearer $HOODY_TOKEN"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-display-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.display.listScreenshots();

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": null
    }
  ]
}

Parameters

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

Window Management

GET /api/v1/display/windows

List the windows currently present on the display, including their geometry, class, focus state, and EWMH states.

cURL

curl -X GET "https://{projectId}-{containerId}-display-1.{server}.containers.hoody.com/api/v1/display/windows?onlyVisible=true" \
  -H "Authorization: Bearer $HOODY_TOKEN"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-display-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.display.listWindows({ onlyVisible: true });

Response 200

{
  "success": true,
  "display": 6,
  "focusedWindowId": 12345,
  "windows": [
    {
      "windowId": 12345,
      "name": "Mozilla Firefox",
      "class": ["firefox", "Firefox"],
      "desktop": 0,
      "geometry": {
        "x": 0,
        "y": 0,
        "width": 1920,
        "height": 1080
      },
      "focused": true,
      "states": ["Normal"]
    }
  ]
}

Response 400

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

Response 500

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

Response 503

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

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.

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

Retrieve extended EWMH properties (such as wmClass, wmName, wmRole, pid, wmState, wmType, and transientFor) for a specific window.

cURL

curl -X GET "https://{projectId}-{containerId}-display-1.{server}.containers.hoody.com/api/v1/display/window/12345/properties" \
  -H "Authorization: Bearer $HOODY_TOKEN"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-display-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.display.getWindowProperties('12345');

Response 200

{
  "success": true,
  "windowId": "12345",
  "properties": {
    "wmClass": ["firefox", "Firefox"],
    "wmName": "Mozilla Firefox",
    "wmRole": null,
    "pid": 1234,
    "wmState": ["Normal"],
    "wmType": ["Normal"],
    "transientFor": null
  }
}

Response 400

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

Response 404

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

Response 500

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

Response 503

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

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.

Clipboard

GET /api/v1/display/clipboard

Read the text content of the display’s clipboard. The buffer selection defaults to clipboard, but primary and secondary are also supported on X11.

cURL

curl -X GET "https://{projectId}-{containerId}-display-1.{server}.containers.hoody.com/api/v1/display/clipboard?selection=clipboard" \
  -H "Authorization: Bearer $HOODY_TOKEN"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-display-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.display.getClipboard({ selection: 'clipboard' });

Response 200

{
  "success": true,
  "text": "Hello from clipboard",
  "selection": "clipboard"
}

Response 400

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

Response 500

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

Response 503

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

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. Defaults to "clipboard". One of "clipboard", "primary", "secondary".

POST /api/v1/display/clipboard

Write text to the display’s clipboard.

cURL

curl -X POST "https://{projectId}-{containerId}-display-1.{server}.containers.hoody.com/api/v1/display/clipboard" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Copied via API",
    "selection": "clipboard"
  }'

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-display-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.display.setClipboard({
  text: 'Copied via API',
  selection: 'clipboard'
});

Response 200

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

Response 400

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

Response 500

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

Response 503

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

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 characters.
selection	string	No	Clipboard buffer selection. Defaults to "clipboard". One of "clipboard", "primary", "secondary".

Screenshots

GET /api/v1/display/screenshot

Capture a fresh screenshot of the display and return the image. Returns binary PNG by default; pass base64=true to receive a base64-encoded JSON envelope.

cURL

curl -X GET "https://{projectId}-{containerId}-display-1.{server}.containers.hoody.com/api/v1/display/screenshot?base64=true" \
  -H "Authorization: Bearer $HOODY_TOKEN"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-display-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.display.screenshots.capture({ base64: true });

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..."
  }
}

Response 400

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

Response 500

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

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.
displayId	query	integer	No	Display ID to use (overrides the *-display-N.* hostname pattern). Valid range: 1-999999.

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

Retrieve a previously captured screenshot by its Unix timestamp.

cURL

curl -X GET "https://{projectId}-{containerId}-display-1.{server}.containers.hoody.com/api/v1/display/screenshot/1749541160?base64=true" \
  -H "Authorization: Bearer $HOODY_TOKEN"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-display-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.display.screenshots.getByTimestamp('1749541160', { base64: true });

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..."
  }
}

Response 400

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

Response 404

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

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. 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.
displayId	query	integer	No	Display ID to use (overrides the *-display-N.* hostname pattern). Valid range: 1-999999.

GET /api/v1/display/screenshot/info

Capture a new screenshot and return only the metadata, without the image payload.

cURL

curl -X GET "https://{projectId}-{containerId}-display-1.{server}.containers.hoody.com/api/v1/display/screenshot/info" \
  -H "Authorization: Bearer $HOODY_TOKEN"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-display-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.display.screenshots.captureMetadata();

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
  }
}

Response 400

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

Response 500

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

Parameters

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

GET /api/v1/display/screenshot/last

Return the most recently captured screenshot.

cURL

curl -X GET "https://{projectId}-{containerId}-display-1.{server}.containers.hoody.com/api/v1/display/screenshot/last?base64=true" \
  -H "Authorization: Bearer $HOODY_TOKEN"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-display-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.display.screenshots.getLatest({ base64: true });

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..."
  }
}

Response 400

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

Response 404

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

Response 500

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

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.
displayId	query	integer	No	Display ID to use (overrides the *-display-N.* hostname pattern). Valid range: 1-999999.

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

Return metadata for the most recent screenshot without downloading the image payload.

cURL

curl -X GET "https://{projectId}-{containerId}-display-1.{server}.containers.hoody.com/api/v1/display/screenshot/last/info" \
  -H "Authorization: Bearer $HOODY_TOKEN"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-display-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.display.screenshots.getLatestMetadata();

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
  }
}

Parameters

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

Thumbnails

GET /api/v1/display/thumbnail

Capture a new screenshot and return the thumbnail version (320x180 scaled). Returns binary PNG by default; pass base64=true to receive a base64-encoded JSON envelope.

cURL

curl -X GET "https://{projectId}-{containerId}-display-1.{server}.containers.hoody.com/api/v1/display/thumbnail?base64=true" \
  -H "Authorization: Bearer $HOODY_TOKEN"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-display-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.display.thumbnails.capture({ base64: true });

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..."
  }
}

Response 404

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

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.
displayId	query	integer	No	Display ID to use (overrides the *-display-N.* hostname pattern). Valid range: 1-999999.

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

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

cURL

curl -X GET "https://{projectId}-{containerId}-display-1.{server}.containers.hoody.com/api/v1/display/thumbnail/1749541160?base64=true" \
  -H "Authorization: Bearer $HOODY_TOKEN"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-display-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.display.thumbnails.getByTimestamp('1749541160', { base64: true });

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..."
  }
}

Response 404

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

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. 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.
displayId	query	integer	No	Display ID to use (overrides the *-display-N.* hostname pattern). Valid range: 1-999999.

GET /api/v1/display/thumbnail/last

Return the thumbnail of the most recent screenshot.

cURL

curl -X GET "https://{projectId}-{containerId}-display-1.{server}.containers.hoody.com/api/v1/display/thumbnail/last?base64=true" \
  -H "Authorization: Bearer $HOODY_TOKEN"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-display-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.display.thumbnails.getLatest({ base64: true });

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..."
  }
}

Response 404

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

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.
displayId	query	integer	No	Display ID to use (overrides the *-display-N.* hostname pattern). Valid range: 1-999999.