# Displays: Screenshot API

**Page:** api/displays/screenshots

[Download Raw Markdown](./api/displays/screenshots.md)

---

{/* AUTO-GENERATED — Do not edit manually. Regenerate with: npm run docs:api:generate */}



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



```json
{
  "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

```typescript
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



```json
{
  "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

```typescript
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`)


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



```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="
  }
}
```


```
Content-Type: image/png

<binary PNG data>
```


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


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



### SDK Usage

```typescript
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



```json
{
  "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
  }
}
```


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


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



### SDK Usage

```typescript
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



```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="
  }
}
```


```
Content-Type: image/png

<binary PNG data>
```


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


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



### SDK Usage

```typescript
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



```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="
  }
}
```


```
Content-Type: image/png

<binary PNG data>
```


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


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


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



### SDK Usage

```typescript
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



```json
{
  "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

```typescript
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



```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="
  }
}
```


```
Content-Type: image/png

<binary PNG data>
```


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



### SDK Usage

```typescript
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



```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="
  }
}
```


```
Content-Type: image/png

<binary PNG data>
```


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



### SDK Usage

```typescript
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



```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="
  }
}
```


```
Content-Type: image/png

<binary PNG data>
```


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



### SDK Usage

```typescript
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



```json
{
  "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"]
    }
  ]
}
```


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


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


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



### SDK Usage

```typescript
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



```json
{
  "success": true,
  "windowId": "1048579",
  "properties": {
    "wmClass": ["terminal", "Terminal"],
    "wmName": "Terminal — bash",
    "wmRole": "terminal",
    "pid": 4321,
    "wmState": ["focused", "active"],
    "wmType": ["normal"],
    "transientFor": null
  }
}
```


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


```json
{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Window not found for the specified windowId",
  "code": "WINDOW_NOT_FOUND"
}
```


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


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



### SDK Usage

```typescript
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



```json
{
  "success": true,
  "text": "echo 'Hello, world!'",
  "selection": "clipboard"
}
```


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


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


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



### SDK Usage

```typescript
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"` |

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

### Response



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


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


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


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



### SDK Usage

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