Displays: Screenshot API

The Display Screenshot API captures, retrieves, and manages visual state from a running container’s X11 display. Use these endpoints to grab a fresh PNG for monitoring or vision pipelines, browse the screenshot history by Unix timestamp, fetch compact thumbnails for UI overviews, inspect the window tree, and read or write the clipboard buffer. Image responses are available as raw PNG bytes (the default) or as a base64 JSON envelope for clients that cannot handle binary payloads.

Display information

`GET /api/v1/display/info`

Returns information about the current display, including all available screenshots. This is the standardized equivalent of /display.

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

curl -X GET 'https://{projectId}-{containerId}-display-1.{server}.containers.hoody.com/api/v1/display/info' \
  -H 'Authorization: Bearer <token>'

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://67e89abc123def456789abcd-890abcdef12345678901cdef-display-1.node-example-1.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.display.get();

Display information retrieved.

{
  "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/6/1749541160.thumbnail.png",
        "size": 24576,
        "width": 384,
        "height": 216
      }
    }
  ]
}

Error Code	Title	Description	Resolution
`DISPLAY_NOT_AVAILABLE`	Display not available	—	—

Error Code	Title	Description	Resolution
`DISPLAY_INFO_FAILED`	Display info failed	—	—

Error Code	Title	Description	Resolution
`NO_DISPLAY_CONTEXT`	No display context	—	—

`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

curl -X GET 'https://{projectId}-{containerId}-display-1.{server}.containers.hoody.com/api/v1/display/screenshots' \
  -H 'Authorization: Bearer <token>'

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://67e89abc123def456789abcd-890abcdef12345678901cdef-display-1.node-example-1.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.display.screenshots.list();

Screenshot list retrieved.

{
  "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/6/1749541160.thumbnail.png",
        "size": 24576,
        "width": 384,
        "height": 216
      }
    },
    {
      "timestamp": "1749541100",
      "timestamp_human": "2026-02-23T16:55:00+00:00",
      "full": {
        "path": "/hoody/storage/hoody-display/screenshots/display_6_1749541100.png",
        "size": 241000,
        "width": 1920,
        "height": 1080
      },
      "thumbnail": null
    }
  ]
}

Error Code	Title	Description	Resolution
`DISPLAY_NOT_AVAILABLE`	Display not available	—	—

Error Code	Title	Description	Resolution
`SCREENSHOTS_FAILED`	Screenshots failed	—	—

Error Code	Title	Description	Resolution
`NO_DISPLAY_CONTEXT`	No display context	—	—

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; pass base64=true to receive a JSON envelope instead.

A capture spans the whole screen, so these are screen coordinates: the same ones POST /input/click-at takes and GET /input/display-geometry describes. The cropped image starts at x1,y1: its pixel (x, y) is screen point (x1 + x, y1 + y).

Parameters

Name	In	Type	Required	Description
`base64`	query	boolean	No	Return a base64-encoded JSON response instead of a binary image. Accepted values: `true`, `1`, or empty for base64; `false`, `0` for binary (default).
`displayId`	query	integer	No	Display ID to use (overrides the `-display-N.` hostname pattern). Valid range: `1`-`999999`
`region`	query	string	No	Crop the returned image to `x1,y1,x2,y2`. Minimum `10x10` px, maximum `65535` on each axis, `x2 > x1` and `y2 > y1`; anything else is a `400`. A capture spans the whole screen, so these are screen coordinates: the same ones `POST /input/click-at` takes and `GET /input/display-geometry` describes. The cropped image starts at `x1,y1`: its pixel (x, y) is screen point (x1 + x, y1 + y).
`cursor`	query	boolean	No	Include the pointer position in the response. Only affects the base64 JSON form. Accepted values: `true`, `1`, or empty. Anything else is off.

Response

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

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://67e89abc123def456789abcd-890abcdef12345678901cdef-display-1.node-example-1.containers.hoody.com', token: process.env.HOODY_TOKEN });

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

Screenshot captured successfully. When base64=true, the response is a JSON envelope; otherwise the body is a raw image/png byte stream.

{
  "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/6/1749541160.thumbnail.png",
      "size": 24576,
      "width": 384,
      "height": 216
    }
  },
  "image": {
    "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=",
    "mimeType": "image/png",
    "dataUrl": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII="
  }
}

No display context is available for the request.

{
  "error": "No display context found",
  "code": "NO_DISPLAY_CONTEXT",
  "details": {
    "message": "A display ID is required for this endpoint. It can be provided via a \"displayId\" query parameter or a domain in the format \"-display-X\".",
    "help": "Use a display-specific domain or pass ?displayId=N."
  }
}

Error Code	Title	Description	Resolution
`NO_DISPLAY_CONTEXT`	No display context	—	—

Screenshot capture failed.

{
  "error": "Screenshot capture failed",
  "code": "SCREENSHOT_FAILED",
  "details": {
    "message": "Screenshot payload was unavailable",
    "help": "Check if the display is active and accessible"
  }
}

Error Code	Title	Description	Resolution
`SCREENSHOT_FAILED`	Screenshot failed	—	—

Error Code	Title	Description	Resolution
`DISPLAY_NOT_AVAILABLE`	Display not available	—	—

`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/list endpoints. Do not use `timestamp_human` for path queries. Must be numeric only for security.
`base64`	query	boolean	No	Return a base64-encoded JSON response instead of a binary image. Accepted values: `true`, `1`, or empty for base64; `false`, `0` for binary (default).
`displayId`	query	integer	No	Display ID to use (overrides the `-display-N.` hostname pattern). Valid range: `1`-`999999`

Response

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

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://67e89abc123def456789abcd-890abcdef12345678901cdef-display-1.node-example-1.containers.hoody.com', token: process.env.HOODY_TOKEN });

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

Screenshot retrieved successfully. When base64=true, the response is a JSON envelope; otherwise the body is a raw image/png byte stream.

{
  "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/6/1749541160.thumbnail.png",
      "size": 24576,
      "width": 384,
      "height": 216
    }
  },
  "image": {
    "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=",
    "mimeType": "image/png",
    "dataUrl": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII="
  }
}

The supplied timestamp is not a numeric Unix value.

{
  "error": "Invalid timestamp",
  "code": "VALIDATION_ERROR",
  "details": {
    "message": "Timestamp must be a numeric Unix seconds value.",
    "help": "Use the timestamp field returned by screenshot metadata or list endpoints."
  }
}

Error Code	Title	Description	Resolution
`VALIDATION_ERROR`	Validation error	—	—
`NO_DISPLAY_CONTEXT`	No display context	The request names no display: it has neither a `displayId` query parameter nor a display-specific hostname.	Pass ?displayId=N, or call the display through its display-specific hostname.

No screenshot exists for the supplied timestamp.

{
  "error": "Screenshot not found",
  "code": "SCREENSHOT_NOT_FOUND",
  "details": {
    "message": "No screenshot found for the supplied timestamp",
    "help": "List available screenshots to discover valid timestamps."
  }
}

Error Code	Title	Description	Resolution
`SCREENSHOT_NOT_FOUND`	Screenshot not found	—	—

Screenshot retrieval failed. The response has error: "Failed to get screenshot", code: "SCREENSHOT_FAILED", and details containing the underlying error message and help.

{
  "error": "Failed to get screenshot",
  "code": "SCREENSHOT_FAILED",
  "details": {
    "message": "Screenshot file not found: 1749541160.png",
    "help": "Check if the timestamp is valid and the display is accessible"
  }
}

Error Code	Title	Description	Resolution
`SCREENSHOT_FAILED`	Screenshot failed	—	—

Error Code	Title	Description	Resolution
`DISPLAY_NOT_AVAILABLE`	Display not available	—	—

`GET /api/v1/display/screenshot/info`

Captures a fresh screenshot but returns only the metadata, with no image bytes in the body.

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

curl -X GET 'https://{projectId}-{containerId}-display-1.{server}.containers.hoody.com/api/v1/display/screenshot/info' \
  -H 'Authorization: Bearer <token>'

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://67e89abc123def456789abcd-890abcdef12345678901cdef-display-1.node-example-1.containers.hoody.com', token: process.env.HOODY_TOKEN });

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

Screenshot captured and metadata returned.

{
  "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/6/1749541160.thumbnail.png",
    "size": 24576,
    "width": 384,
    "height": 216
  }
}

No display context is available for the request.

{
  "error": "No display context found",
  "code": "NO_DISPLAY_CONTEXT",
  "details": {
    "message": "A display ID is required for this endpoint. It can be provided via a \"displayId\" query parameter or a domain in the format \"-display-X\".",
    "help": "Use a display-specific domain or pass ?displayId=N."
  }
}

Error Code	Title	Description	Resolution
`NO_DISPLAY_CONTEXT`	No display context	—	—

The screenshot operation failed. Two named examples are possible.

Display inactive:

{
  "error": "Failed to take screenshot",
  "code": "SCREENSHOT_FAILED",
  "details": {
    "message": "No screenshot data was returned for display 10. The display may be inactive or have no running programs.",
    "help": "Check if the display is active and accessible"
  }
}

Invalid screenshot payload:

{
  "error": "Failed to take screenshot",
  "code": "SCREENSHOT_FAILED",
  "details": {
    "message": "Invalid screenshot data was returned for display 10. The display may be inactive or have no running programs.",
    "help": "Check if the display is active and accessible"
  }
}

Error Code	Title	Description	Resolution
`SCREENSHOT_FAILED`	Screenshot failed	—	—

Error Code	Title	Description	Resolution
`DISPLAY_NOT_AVAILABLE`	Display not available	—	—

`GET /api/v1/display/screenshot/last`

Returns the most recently captured screenshot.

Parameters

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

Response

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

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://67e89abc123def456789abcd-890abcdef12345678901cdef-display-1.node-example-1.containers.hoody.com', token: process.env.HOODY_TOKEN });

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

Latest screenshot retrieved. When base64=true, the response is a JSON envelope; otherwise the body is a raw image/png byte stream.

{
  "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/6/1749541160.thumbnail.png",
      "size": 24576,
      "width": 384,
      "height": 216
    }
  },
  "image": {
    "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=",
    "mimeType": "image/png",
    "dataUrl": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII="
  }
}

No display context is available for the request.

{
  "error": "No display context found",
  "code": "NO_DISPLAY_CONTEXT",
  "details": {
    "message": "A display ID is required for this endpoint. It can be provided via a \"displayId\" query parameter or a domain in the format \"-display-X\".",
    "help": "Use a display-specific domain or pass ?displayId=N."
  }
}

Error Code	Title	Description	Resolution
`NO_DISPLAY_CONTEXT`	No display context	—	—

No screenshot exists for the display yet.

{
  "error": "Screenshot not found",
  "code": "SCREENSHOT_NOT_FOUND",
  "details": {
    "message": "No screenshots found",
    "help": "Capture a screenshot first, then retry."
  }
}

Error Code	Title	Description	Resolution
`SCREENSHOT_NOT_FOUND`	Screenshot not found	—	—

Latest screenshot retrieval failed. The response has error: "Failed to get latest screenshot", code: "SCREENSHOT_FAILED", and details containing the underlying error message and help.

{
  "error": "Failed to get latest screenshot",
  "code": "SCREENSHOT_FAILED",
  "details": {
    "message": "Screenshot file not found: 1749541160.png",
    "help": "Check if the display is active and accessible"
  }
}

Error Code	Title	Description	Resolution
`SCREENSHOT_FAILED`	Screenshot failed	—	—

Error Code	Title	Description	Resolution
`DISPLAY_NOT_AVAILABLE`	Display not available	—	—

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

Returns metadata about the most recent 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

curl -X GET 'https://{projectId}-{containerId}-display-1.{server}.containers.hoody.com/api/v1/display/screenshot/last/info' \
  -H 'Authorization: Bearer <token>'

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://67e89abc123def456789abcd-890abcdef12345678901cdef-display-1.node-example-1.containers.hoody.com', token: process.env.HOODY_TOKEN });

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

Latest screenshot metadata.

{
  "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/6/1749541160.thumbnail.png",
    "size": 24576,
    "width": 384,
    "height": 216
  }
}

Latest screenshot metadata retrieval failed. The response has error: "Failed to get latest screenshot info", code: "SCREENSHOT_FAILED", and details containing the underlying error message and help.

{
  "error": "Failed to get latest screenshot info",
  "code": "SCREENSHOT_FAILED",
  "details": {
    "message": "<underlying error message>",
    "help": "Check if the display is active and accessible"
  }
}

Error Code	Title	Description	Resolution
`SCREENSHOT_FAILED`	Screenshot failed	—	—

Error Code	Title	Description	Resolution
`DISPLAY_NOT_AVAILABLE`	Display not available	—	—

Error Code	Title	Description	Resolution
`SCREENSHOT_NOT_FOUND`	Screenshot not found	—	—

Error Code	Title	Description	Resolution
`NO_DISPLAY_CONTEXT`	No display context	—	—

Thumbnails

A thumbnail is the capture scaled to 20% (ImageMagick convert -resize 20%), not a fixed size. A seamless capture’s dimensions follow the windows it composited, so the thumbnail’s do too.

`GET /api/v1/display/thumbnail`

Captures a fresh screenshot and returns a thumbnail of it.

Parameters

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

Response

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

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://67e89abc123def456789abcd-890abcdef12345678901cdef-display-1.node-example-1.containers.hoody.com', token: process.env.HOODY_TOKEN });

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

Thumbnail captured successfully. When base64=true, the response is a JSON envelope; otherwise the body is a raw image/png byte stream.

{
  "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/6/1749541160.thumbnail.png",
      "size": 24576,
      "width": 384,
      "height": 216
    }
  },
  "image": {
    "data": "iVBORw0KGgoAAAANSUhEUgAAEAAAABACAYAAACqa2xkAAAACXBIWXMAAAsTAAALEwEAmpwYAAAA",
    "mimeType": "image/png",
    "dataUrl": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAEAAAABACAYAAACqa2xkAAAACXBIWXMAAAsTAAALEwEAmpwYAAAA"
  }
}

No thumbnail is available yet for the display.

{
  "error": "Thumbnail not available",
  "code": "THUMBNAIL_NOT_FOUND",
  "details": {
    "message": "No thumbnail available for the latest screenshot",
    "help": "Thumbnails are automatically generated when screenshots are taken"
  }
}

Error Code	Title	Description	Resolution
`THUMBNAIL_NOT_FOUND`	Thumbnail not found	—	—

Thumbnail operation failed.

{
  "error": "Failed to take thumbnail",
  "code": "THUMBNAIL_FAILED",
  "details": {
    "message": "No screenshot data was returned for display 10. The display may be inactive or have no running programs.",
    "help": "Check if the display is active and accessible"
  }
}

Error Code	Title	Description	Resolution
`THUMBNAIL_FAILED`	Thumbnail failed	—	—

Error Code	Title	Description	Resolution
`DISPLAY_NOT_AVAILABLE`	Display not available	—	—

Error Code	Title	Description	Resolution
`NO_DISPLAY_CONTEXT`	No display context	—	—

`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/list endpoints. Do not use `timestamp_human` for path queries. Must be numeric only for security.
`base64`	query	boolean	No	Return a base64-encoded JSON response instead of a binary image. Accepted values: `true`, `1`, or empty for base64; `false`, `0` for binary (default).
`displayId`	query	integer	No	Display ID to use (overrides the `-display-N.` hostname pattern). Valid range: `1`-`999999`

Response

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

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://67e89abc123def456789abcd-890abcdef12345678901cdef-display-1.node-example-1.containers.hoody.com', token: process.env.HOODY_TOKEN });

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

Thumbnail retrieved successfully. When base64=true, the response is a JSON envelope; otherwise the body is a raw image/png byte stream.

{
  "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/6/1749541160.thumbnail.png",
      "size": 24576,
      "width": 384,
      "height": 216
    }
  },
  "image": {
    "data": "iVBORw0KGgoAAAANSUhEUgAAEAAAABACAYAAACqa2xkAAAACXBIWXMAAAsTAAALEwEAmpwYAAAA",
    "mimeType": "image/png",
    "dataUrl": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAEAAAABACAYAAACqa2xkAAAACXBIWXMAAAsTAAALEwEAmpwYAAAA"
  }
}

The supplied timestamp is not a numeric Unix value.

{
  "error": "Invalid timestamp format",
  "code": "VALIDATION_ERROR",
  "details": {
    "message": "Timestamp must be numeric (Unix timestamp)",
    "help": "Use format like 1749541160"
  }
}

Error Code	Title	Description	Resolution
`VALIDATION_ERROR`	Validation error	—	—
`NO_DISPLAY_CONTEXT`	No display context	The request names no display: it has neither a `displayId` query parameter nor a display-specific hostname.	Pass ?displayId=N, or call the display through its display-specific hostname.

Returns 404 THUMBNAIL_NOT_FOUND when no thumbnail exists for the supplied timestamp.

{
  "error": "Thumbnail not found",
  "code": "THUMBNAIL_NOT_FOUND",
  "details": {
    "message": "No thumbnail available for the supplied timestamp",
    "help": "List available screenshots to discover valid timestamps with thumbnails."
  }
}

Error Code	Title	Description	Resolution
`THUMBNAIL_NOT_FOUND`	Thumbnail not found	—	—
`SCREENSHOT_NOT_FOUND`	Screenshot not found	No stored screenshot matches the request.	Take a screenshot first with GET /screenshot, or list the stored ones.

Thumbnail retrieval failed. The response has error: "Failed to get thumbnail", code: "THUMBNAIL_FAILED", and details containing the underlying error message and help.

{
  "error": "Failed to get thumbnail",
  "code": "THUMBNAIL_FAILED",
  "details": {
    "message": "Screenshot file not found: 1749541160.png",
    "help": "Check if the timestamp is valid and the display is accessible"
  }
}

Error Code	Title	Description	Resolution
`THUMBNAIL_FAILED`	Thumbnail failed	—	—

Error Code	Title	Description	Resolution
`DISPLAY_NOT_AVAILABLE`	Display not available	—	—

`GET /api/v1/display/thumbnail/last`

Returns the thumbnail of the most recently captured screenshot.

Parameters

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

Response

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

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://67e89abc123def456789abcd-890abcdef12345678901cdef-display-1.node-example-1.containers.hoody.com', token: process.env.HOODY_TOKEN });

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

Latest thumbnail retrieved. When base64=true, the response is a JSON envelope; otherwise the body is a raw image/png byte stream.

{
  "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/6/1749541160.thumbnail.png",
      "size": 24576,
      "width": 384,
      "height": 216
    }
  },
  "image": {
    "data": "iVBORw0KGgoAAAANSUhEUgAAEAAAABACAYAAACqa2xkAAAACXBIWXMAAAsTAAALEwEAmpwYAAAA",
    "mimeType": "image/png",
    "dataUrl": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAEAAAABACAYAAACqa2xkAAAACXBIWXMAAAsTAAALEwEAmpwYAAAA"
  }
}

Returns 404 THUMBNAIL_NOT_FOUND when no thumbnail exists for the latest screenshot.

{
  "error": "Thumbnail not available",
  "code": "THUMBNAIL_NOT_FOUND",
  "details": {
    "message": "No thumbnail available for the latest screenshot",
    "help": "Thumbnails are automatically generated when screenshots are taken"
  }
}

Error Code	Title	Description	Resolution
`THUMBNAIL_NOT_FOUND`	Thumbnail not found	—	—
`SCREENSHOT_NOT_FOUND`	Screenshot not found	No stored screenshot matches the request.	Take a screenshot first with GET /screenshot, or list the stored ones.

Latest thumbnail retrieval failed. The response has error: "Failed to get latest thumbnail", code: "THUMBNAIL_FAILED", and details containing the underlying error message and help.

{
  "error": "Failed to get latest thumbnail",
  "code": "THUMBNAIL_FAILED",
  "details": {
    "message": "Screenshot file not found: 1749541160.png",
    "help": "Check if the display is active and accessible"
  }
}

Error Code	Title	Description	Resolution
`THUMBNAIL_FAILED`	Thumbnail failed	—	—

Error Code	Title	Description	Resolution
`DISPLAY_NOT_AVAILABLE`	Display not available	—	—

Error Code	Title	Description	Resolution
`NO_DISPLAY_CONTEXT`	No display context	—	—

Windows

`GET /api/v1/display/windows`

Lists the windows currently known to the display.

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`, drop windows carrying `_NET_WM_STATE_HIDDEN`. A minimized window carries that state, so this does exclude minimized windows. It is a different test from the `onlyVisible` on `window/search` and `input/wait-until`, which ask the X server whether the window is viewable and, under xpra, still match a minimized one.

Response

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

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://67e89abc123def456789abcd-890abcdef12345678901cdef-display-1.node-example-1.containers.hoody.com', token: process.env.HOODY_TOKEN });

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

Window list retrieved.

{
  "success": true,
  "display": 6,
  "focusedWindowId": 12345,
  "windows": [
    {
      "windowId": 12345,
      "name": "Main Editor",
      "class": ["code", "Code"],
      "desktop": 0,
      "geometry": {
        "x": 100,
        "y": 100,
        "width": 1280,
        "height": 800
      },
      "focused": true,
      "states": ["_NET_WM_STATE_FOCUSED", "_NET_WM_STATE_MAXIMIZED_VERT", "_NET_WM_STATE_MAXIMIZED_HORZ"]
    },
    {
      "windowId": 12346,
      "name": "Terminal",
      "class": ["xterm", "XTerm"],
      "desktop": 0,
      "geometry": {
        "x": 1400,
        "y": 100,
        "width": 480,
        "height": 600
      },
      "focused": false,
      "states": []
    }
  ]
}

No display context is available for the request.

{
  "error": "No display context found",
  "code": "NO_DISPLAY_CONTEXT",
  "details": {
    "message": "A display ID is required for this endpoint. It can be provided via a \"displayId\" query parameter or a domain in the format \"-display-X\".",
    "help": "Use a display-specific domain or pass ?displayId=N."
  }
}

Error Code	Title	Description	Resolution
`NO_DISPLAY_CONTEXT`	No display context	—	—

Listing windows failed.

{
  "error": "Failed to list windows",
  "code": "WINDOW_LIST_FAILED",
  "details": {
    "message": "Window query failed: ...",
    "help": "Check if the display is active and wmctrl is available"
  }
}

Error Code	Title	Description	Resolution
`WINDOW_LIST_FAILED`	Window list failed	—	—

The display backend is not currently reachable.

{
  "error": "Display is not available or not running",
  "code": "DISPLAY_NOT_AVAILABLE",
  "details": {
    "message": "Display is not available or not running",
    "help": "Check if the display is running and the displayId is correct"
  }
}

Error Code	Title	Description	Resolution
`DISPLAY_NOT_AVAILABLE`	Display not available	—	—

Error Code	Title	Description	Resolution
`NO_WINDOW_MANAGER`	No window manager	—	—

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

Returns extended properties (WM class, WM name, role, PID, state, type, transient parent) for a single window.

Parameters

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

Response

curl -X GET 'https://{projectId}-{containerId}-display-1.{server}.containers.hoody.com/api/v1/display/window/12345/properties' \
  -H 'Authorization: Bearer <token>'

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://67e89abc123def456789abcd-890abcdef12345678901cdef-display-1.node-example-1.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.display.windows.get('12345');

Window properties retrieved.

{
  "success": true,
  "windowId": "12345",
  "properties": {
    "wmClass": ["code", "Code"],
    "wmName": "Main Editor",
    "wmRole": null,
    "pid": 4321,
    "wmState": ["_NET_WM_STATE_FOCUSED", "_NET_WM_STATE_MAXIMIZED_VERT", "_NET_WM_STATE_MAXIMIZED_HORZ"],
    "wmType": ["_NET_WM_WINDOW_TYPE_NORMAL"],
    "transientFor": null
  }
}

No display context is available for the request.

{
  "error": "No display context found",
  "code": "NO_DISPLAY_CONTEXT",
  "details": {
    "message": "A display ID is required for this endpoint. It can be provided via a \"displayId\" query parameter or a domain in the format \"-display-X\".",
    "help": "Use a display-specific domain or pass ?displayId=N."
  }
}

Error Code	Title	Description	Resolution
`NO_DISPLAY_CONTEXT`	No display context	—	—

The requested window is not known to the display.

{
  "error": "Window not found",
  "code": "WINDOW_NOT_FOUND",
  "details": {
    "message": "Window not found",
    "help": "Check if the window still exists using /window/search. Windows the window manager does not manage (override-redirect, withdrawn, never mapped) also report this."
  }
}

Error Code	Title	Description	Resolution
`WINDOW_NOT_FOUND`	Window not found	—	—

Reading window properties failed.

{
  "error": "Failed to get window properties",
  "code": "WINDOW_PROPERTIES_FAILED",
  "details": {
    "message": "Window query failed: ...",
    "help": "Check if the display is active and xprop is available"
  }
}

Error Code	Title	Description	Resolution
`WINDOW_PROPERTIES_FAILED`	Window properties failed	—	—

The display backend is not currently reachable.

{
  "error": "Display is not available or not running",
  "code": "DISPLAY_NOT_AVAILABLE",
  "details": {
    "message": "Display is not available or not running",
    "help": "Check if the display is running and the displayId is correct"
  }
}

Error Code	Title	Description	Resolution
`DISPLAY_NOT_AVAILABLE`	Display not available	—	—

Clipboard

`GET /api/v1/display/clipboard`

Reads the current text content of 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`
`selection`	query	string	No	Clipboard buffer selection. One of `clipboard`, `primary`, `secondary`. Default: `clipboard`

Response

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

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://67e89abc123def456789abcd-890abcdef12345678901cdef-display-1.node-example-1.containers.hoody.com', token: process.env.HOODY_TOKEN });

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

Clipboard text retrieved.

{
  "success": true,
  "text": "echo 'Hello, World!'",
  "selection": "clipboard"
}

No display context is available for the request.

{
  "error": "No display context found",
  "code": "NO_DISPLAY_CONTEXT",
  "details": {
    "message": "A display ID is required for this endpoint. It can be provided via a \"displayId\" query parameter or a domain in the format \"-display-X\".",
    "help": "Use a display-specific domain or pass ?displayId=N."
  }
}

Error Code	Title	Description	Resolution
`NO_DISPLAY_CONTEXT`	No display context	—	—

Reading the clipboard failed.

{
  "error": "Failed to read clipboard",
  "code": "CLIPBOARD_FAILED",
  "details": {
    "message": "Clipboard operation failed: ...",
    "help": "Check if the display is active and xsel is available"
  }
}

Error Code	Title	Description	Resolution
`CLIPBOARD_FAILED`	Clipboard failed	—	—

The display backend is not currently reachable.

{
  "error": "Display is not available or not running",
  "code": "DISPLAY_NOT_AVAILABLE",
  "details": {
    "message": "Display is not available or not running",
    "help": "Check if the display is running and the displayId is correct"
  }
}

Error Code	Title	Description	Resolution
`DISPLAY_NOT_AVAILABLE`	Display not available	—	—

`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. Maximum length: `1048576` bytes.
`selection`	string	No	Clipboard buffer selection. One of `clipboard`, `primary`, `secondary`. Default: `clipboard`

Response

curl -X POST 'https://{projectId}-{containerId}-display-1.{server}.containers.hoody.com/api/v1/display/clipboard' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"text":"Hello, World!","selection":"clipboard"}'

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://67e89abc123def456789abcd-890abcdef12345678901cdef-display-1.node-example-1.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.display.clipboard.set({ text: 'Hello, World!', selection: 'clipboard' });

Clipboard text written.

{
  "success": true,
  "action": "clipboard-write",
  "details": {
    "length": 13,
    "selection": "clipboard"
  }
}

No display context is available for the request.

{
  "error": "No display context found",
  "code": "NO_DISPLAY_CONTEXT",
  "details": {
    "message": "A display ID is required for this endpoint. It can be provided via a \"displayId\" query parameter or a domain in the format \"-display-X\".",
    "help": "Use a display-specific domain or pass ?displayId=N."
  }
}

Error Code	Title	Description	Resolution
`NO_DISPLAY_CONTEXT`	No display context	—	—
`INVALID_JSON`	Invalid JSON body	The request body could not be parsed as JSON, or a body was sent without `Content-Type: application/json`.	Send a valid JSON body with `Content-Type: application/json`.

Writing the clipboard failed.

{
  "error": "Failed to read clipboard",
  "code": "CLIPBOARD_FAILED",
  "details": {
    "message": "Clipboard operation failed: ...",
    "help": "Check if the display is active and xsel is available"
  }
}

Error Code	Title	Description	Resolution
`CLIPBOARD_FAILED`	Clipboard failed	—	—

The display backend is not currently reachable.

{
  "error": "Display is not available or not running",
  "code": "DISPLAY_NOT_AVAILABLE",
  "details": {
    "message": "Display is not available or not running",
    "help": "Check if the display is running and the displayId is correct"
  }
}

Error Code	Title	Description	Resolution
`DISPLAY_NOT_AVAILABLE`	Display not available	—	—

Error Code	Title	Description	Resolution
`PAYLOAD_TOO_LARGE`	Payload too large	—	—