# Displays: Input Actions

**Page:** api/displays/input-actions

[Download Raw Markdown](./api/displays/input-actions.md)

---

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



The Display Input API provides low-level control over mouse, keyboard, and window management on a remote display. Use these endpoints to automate UI interactions, capture screenshots, manipulate windows, and build scripted workflows against a virtualized desktop.


Most endpoints accept an optional `displayId` query parameter (range: `1`–`999999`) that overrides the `*-display-N.*` hostname pattern for selecting a target display.


## Display & Window Information

Query the current state of the display, cursor, and windows.

### `GET /api/v1/display/input/display-geometry`

Returns the dimensions of the current 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



```json
{
  "success": true,
  "width": 1920,
  "height": 1080,
  "screen": 0
}
```


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


```json
{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Failed to read display geometry"
}
```


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



### SDK Usage

```ts
const geometry = await client.display.input.geometry();
```

---

### `GET /api/v1/display/mouse/location`

Returns the current cursor position, screen, and the window under the cursor.

### 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
{
  "success": true,
  "x": 540,
  "y": 312,
  "screen": 0,
  "window": 1234567
}
```


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


```json
{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Failed to read mouse location"
}
```


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



### SDK Usage

```ts
const location = await client.display.input.mouseLocation();
```

---

### `GET /api/v1/display/window/active`

Returns the currently active (focused) window ID.

### 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
{
  "success": true,
  "windowId": 1234567
}
```


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


```json
{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Failed to read active window"
}
```


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



### SDK Usage

```ts
const active = await client.display.input.windowActive();
```

---

### `GET /api/v1/display/window/{windowId}/geometry`

Returns the position and size of a specific window.

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `windowId` | path | string | Yes | Window ID (decimal or hex) |
| `displayId` | query | integer | No | Display ID to use (overrides the `*-display-N.*` hostname pattern). Valid range: `1`–`999999` |

### Response



```json
{
  "success": true,
  "windowId": 1234567,
  "x": 100,
  "y": 50,
  "width": 1280,
  "height": 720
}
```


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


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


```json
{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Failed to read window geometry"
}
```


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



### SDK Usage

```ts
const geometry = await client.display.input.windowGeometry({ windowId: "0x12d687" });
```

---

### `GET /api/v1/display/window/{windowId}/name`

Returns the title of a specific window.

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `windowId` | path | string | Yes | Window ID (decimal or hex) |
| `displayId` | query | integer | No | Display ID to use (overrides the `*-display-N.*` hostname pattern). Valid range: `1`–`999999` |

### Response



```json
{
  "success": true,
  "windowId": 1234567,
  "name": "Visual Studio Code"
}
```


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


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


```json
{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Failed to read window name"
}
```


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



### SDK Usage

```ts
const name = await client.display.input.windowName({ windowId: "0x12d687" });
```

---

## High-Level Input Actions

Composite actions that bundle multiple low-level operations into a single request.

### `POST /api/v1/display/input/act`

Executes a single named action (e.g. `mouse/click`, `keyboard/type`) with an optional screenshot.

### 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 | Default | Description |
|------|------|----------|---------|-------------|
| `action` | string | Yes | — | Action path (e.g. `mouse/click`, `keyboard/type`). Max length: `50` |
| `params` | object | No | `{}` | Action-specific parameters |
| `screenshot` | boolean | No | `true` | Capture screenshot after action |
| `screenshotDelay` | integer | No | `100` | Delay before screenshot in milliseconds. Range: `0`–`5000` |
| `screenshotRegion` | string | No | — | Crop region in format `x1,y1,x2,y2` |

### Response



```json
{
  "success": true,
  "action": {
    "success": true,
    "action": "mouse/click",
    "details": {
      "button": 1,
      "x": 540,
      "y": 312
    }
  },
  "screenshot": {
    "timestamp": "2026-01-15T12:34:56.000Z",
    "image": {
      "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAAB...",
      "mimeType": "image/png",
      "dataUrl": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg..."
    }
  }
}
```


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


```json
{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Input action queue is full"
}
```


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


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



### SDK Usage

```ts
const result = await client.display.input.act({
  action: "mouse/click",
  params: { x: 540, y: 312, button: 1 },
  screenshot: true,
});
```

---

### `POST /api/v1/display/input/batch`

Executes a sequence of actions in order. Up to 50 actions per request.

### 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 |
|------|------|----------|-------------|
| `actions` | array | Yes | List of actions to execute. `1`–`50` items |

Each action item has the following structure:

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `action` | string | Yes | Action path (e.g. `mouse/click`, `keyboard/type`) |
| `params` | object | No | Action-specific parameters |

### Response



```json
{
  "success": true,
  "completed": [
    { "index": 0, "action": "mouse/move", "success": true },
    { "index": 1, "action": "mouse/click", "success": true },
    { "index": 2, "action": "keyboard/type", "success": true }
  ],
  "failed": {
    "index": 3,
    "action": "keyboard/key",
    "error": "Unknown keysym: Foo"
  },
  "skipped": [4, 5]
}
```


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


```json
{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Input action queue is full"
}
```


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


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



### SDK Usage

```ts
const result = await client.display.input.batch({
  actions: [
    { action: "mouse/move", params: { x: 100, y: 100 } },
    { action: "mouse/click", params: { button: 1 } },
    { action: "keyboard/type", params: { text: "hello" } },
  ],
});
```

---

### `POST /api/v1/display/input/click-at`

Moves the cursor to a coordinate and clicks.

### 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 | Default | Description |
|------|------|----------|---------|-------------|
| `x` | integer | Yes | — | Target X coordinate |
| `y` | integer | Yes | — | Target Y coordinate |
| `button` | integer | No | `1` | Mouse button (`1`=left, `2`=middle, `3`=right, `4`–`7`=extra). Range: `1`–`7` |

### Response



```json
{
  "success": true,
  "action": "click",
  "details": {
    "x": 540,
    "y": 312,
    "button": 1
  }
}
```


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


```json
{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Input action queue is full"
}
```


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


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



### SDK Usage

```ts
await client.display.input.clickAt({ x: 540, y: 312, button: 1 });
```

---

### `POST /api/v1/display/input/drag`

Drags the cursor from a start position to an end position.

### 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 | Default | Description |
|------|------|----------|---------|-------------|
| `startX` | integer | Yes | — | Start X coordinate |
| `startY` | integer | Yes | — | Start Y coordinate |
| `endX` | integer | Yes | — | End X coordinate |
| `endY` | integer | Yes | — | End Y coordinate |
| `button` | integer | No | `1` | Mouse button (`1`=left, `2`=middle, `3`=right, `4`–`7`=extra). Range: `1`–`7` |
| `steps` | integer | No | — | Number of intermediate mouse positions for smooth drag. Range: `1`–`1000` |

### Response



```json
{
  "success": true,
  "action": "drag",
  "details": {
    "startX": 100,
    "startY": 200,
    "endX": 800,
    "endY": 600,
    "button": 1,
    "steps": 20
  }
}
```


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


```json
{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Input action queue is full"
}
```


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


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



### SDK Usage

```ts
await client.display.input.drag({
  startX: 100,
  startY: 200,
  endX: 800,
  endY: 600,
  steps: 20,
});
```

---

### `POST /api/v1/display/input/select`

Selects a range by clicking at a start position and shift-clicking at an end position.

### 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 |
|------|------|----------|-------------|
| `x` | integer | Yes | Start X coordinate |
| `y` | integer | Yes | Start Y coordinate |
| `endX` | integer | Yes | End X coordinate |
| `endY` | integer | Yes | End Y coordinate |

### Response



```json
{
  "success": true,
  "action": "select",
  "details": {
    "x": 120,
    "y": 240,
    "endX": 480,
    "endY": 360
  }
}
```


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


```json
{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Input action queue is full"
}
```


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


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



### SDK Usage

```ts
await client.display.input.select({ x: 120, y: 240, endX: 480, endY: 360 });
```

---

### `POST /api/v1/display/input/type-at`

Moves the cursor to a coordinate, clicks, and types text in one operation.

### 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 |
|------|------|----------|-------------|
| `x` | integer | Yes | Target X coordinate |
| `y` | integer | Yes | Target Y coordinate |
| `text` | string | Yes | Text to type. Max length: `10000` |
| `delay` | integer | No | Inter-keystroke delay in milliseconds. Range: `0`–`1000` |

### Response



```json
{
  "success": true,
  "action": "type-at",
  "details": {
    "x": 540,
    "y": 312,
    "text": "user@example.com",
    "delay": 0
  }
}
```


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


```json
{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Input action queue is full"
}
```


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


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



### SDK Usage

```ts
await client.display.input.typeAt({ x: 540, y: 312, text: "user@example.com" });
```

---

### `POST /api/v1/display/input/wait`

Waits for a specified duration, with an optional screenshot on completion.

### 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 | Default | Description |
|------|------|----------|---------|-------------|
| `ms` | integer | Yes | — | Wait duration in milliseconds. Range: `50`–`30000` |
| `screenshot` | boolean | No | `false` | Capture screenshot after wait |

### Response



```json
{
  "success": true,
  "action": "wait",
  "details": {
    "ms": 500
  },
  "screenshot": {
    "timestamp": "2026-01-15T12:34:56.000Z",
    "image": {
      "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAAB...",
      "mimeType": "image/png",
      "dataUrl": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg..."
    }
  }
}
```


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


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


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



### SDK Usage

```ts
await client.display.input.wait({ ms: 500, screenshot: false });
```

---

### `POST /api/v1/display/input/reset`

Emergency release of all held inputs (mouse buttons and modifier keys).

### Parameters

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

This endpoint takes no body.

### Response



```json
{
  "success": true,
  "action": "reset",
  "details": {
    "released": ["mouse:1", "Shift_L", "ctrl"]
  }
}
```


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


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


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



### SDK Usage

```ts
await client.display.input.reset();
```

---

## Keyboard Actions

Send key presses, key combinations, and typed text.

### `POST /api/v1/display/keyboard/key`

Presses one or more key combinations (e.g. `['ctrl+c', 'Return']`).

### 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 |
|------|------|----------|-------------|
| `keys` | array | Yes | Key combinations (e.g. `['ctrl+c', 'Return']`). `1`–`20` items, each max length `100` |
| `window` | integer \| string | No | Target window ID |
| `delay` | integer | No | Delay between key presses in milliseconds. Range: `0`–`5000` |
| `clearModifiers` | boolean | No | Clear modifier keys before pressing |

### Response



```json
{
  "success": true,
  "action": "key",
  "details": {
    "keys": ["ctrl+c"],
    "window": 1234567
  }
}
```


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


```json
{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Input action queue is full"
}
```


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


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



### SDK Usage

```ts
await client.display.input.keyboardKey({ keys: ["ctrl+c"] });
```

---

### `POST /api/v1/display/keyboard/key-down`

Holds a key down (without releasing it).

### 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 |
|------|------|----------|-------------|
| `key` | string | Yes | Key name (X11 keysym, e.g. `Shift_L`, `ctrl`). Max length: `100` |
| `window` | integer \| string | No | Target window ID |
| `holdMs` | integer | No | Auto-release after this many milliseconds. Range: `100`–`60000` |

### Response



```json
{
  "success": true,
  "action": "key-down",
  "details": {
    "key": "Shift_L",
    "holdMs": 1500
  }
}
```


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


```json
{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Input action queue is full"
}
```


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


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



### SDK Usage

```ts
await client.display.input.keyboardKeyDown({ key: "Shift_L", holdMs: 1500 });
```

---

### `POST /api/v1/display/keyboard/key-up`

Releases a previously held key.

### 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 |
|------|------|----------|-------------|
| `key` | string | Yes | Key name (X11 keysym, e.g. `Shift_L`). Max length: `100` |
| `window` | integer \| string | No | Target window ID |

### Response



```json
{
  "success": true,
  "action": "key-up",
  "details": {
    "key": "Shift_L"
  }
}
```


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


```json
{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Input action queue is full"
}
```


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


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



### SDK Usage

```ts
await client.display.input.keyboardKeyUp({ key: "Shift_L" });
```

---

### `POST /api/v1/display/keyboard/type`

Types a string of text at the current cursor position.

### 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 | Text to type. Max length: `10000` |
| `window` | integer \| string | No | Target window ID |
| `delay` | integer | No | Inter-keystroke delay in milliseconds. Range: `0`–`1000` |
| `clearModifiers` | boolean | No | Clear modifier keys before typing |

### Response



```json
{
  "success": true,
  "action": "type",
  "details": {
    "text": "Hello, world!",
    "window": 1234567
  }
}
```


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


```json
{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Input action queue is full"
}
```


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


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



### SDK Usage

```ts
await client.display.input.keyboardType({ text: "Hello, world!" });
```

---

## Mouse Actions

Move the cursor, click, hold, release, and scroll.

### `POST /api/v1/display/mouse/click`

Clicks a mouse button. Supports repeated clicks with a delay between them.

### 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 | Default | Description |
|------|------|----------|---------|-------------|
| `button` | integer | No | `1` | Mouse button (`1`=left, `2`=middle, `3`=right, `4`–`7`=extra). Range: `1`–`7` |
| `repeat` | integer | No | `1` | Number of times to repeat the click. Range: `1`–`100` |
| `delay` | integer | No | — | Delay between repeats in milliseconds. Range: `0`–`5000` |
| `window` | integer \| string | No | — | Target window ID (decimal or hex `0x...`) |

### Response



```json
{
  "success": true,
  "action": "click",
  "details": {
    "button": 1,
    "repeat": 1
  }
}
```


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


```json
{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Input action queue is full"
}
```


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


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



### SDK Usage

```ts
await client.display.input.mouseClick({ button: 1, repeat: 2, delay: 50 });
```

---

### `POST /api/v1/display/mouse/double-click`

Double-clicks a mouse button.

### 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 | Default | Description |
|------|------|----------|---------|-------------|
| `button` | integer | No | `1` | Mouse button (`1`=left, `2`=middle, `3`=right, `4`–`7`=extra). Range: `1`–`7` |
| `window` | integer \| string | No | — | Target window ID |

### Response



```json
{
  "success": true,
  "action": "double-click",
  "details": {
    "button": 1
  }
}
```


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


```json
{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Input action queue is full"
}
```


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


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



### SDK Usage

```ts
await client.display.input.mouseDoubleClick({ button: 1 });
```

---

### `POST /api/v1/display/mouse/down`

Presses and holds a mouse button.

### 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 | Default | Description |
|------|------|----------|---------|-------------|
| `button` | integer | No | `1` | Mouse button (`1`=left, `2`=middle, `3`=right, `4`–`7`=extra). Range: `1`–`7` |
| `window` | integer \| string | No | — | Target window ID |
| `holdMs` | integer | No | — | Auto-release after this many milliseconds. Range: `100`–`60000` |

### Response



```json
{
  "success": true,
  "action": "mouse-down",
  "details": {
    "button": 1,
    "holdMs": 1000
  }
}
```


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


```json
{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Input action queue is full"
}
```


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


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



### SDK Usage

```ts
await client.display.input.mouseDown({ button: 1, holdMs: 1000 });
```

---

### `POST /api/v1/display/mouse/up`

Releases a previously held mouse button.

### 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 | Default | Description |
|------|------|----------|---------|-------------|
| `button` | integer | No | `1` | Mouse button (`1`=left, `2`=middle, `3`=right, `4`–`7`=extra). Range: `1`–`7` |
| `window` | integer \| string | No | — | Target window ID |

### Response



```json
{
  "success": true,
  "action": "mouse-up",
  "details": {
    "button": 1
  }
}
```


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


```json
{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Input action queue is full"
}
```


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


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



### SDK Usage

```ts
await client.display.input.mouseUp({ button: 1 });
```

---

### `POST /api/v1/display/mouse/move`

Moves the cursor to an absolute position on 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` |

### Request Body

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `x` | integer | Yes | Target X coordinate. Range: `-65535`–`65535` |
| `y` | integer | Yes | Target Y coordinate. Range: `-65535`–`65535` |
| `window` | integer \| string | No | Target window ID |
| `screen` | integer | No | Target screen index. Range: `0`–`15` |
| `sync` | boolean | No | Wait for the move to complete before returning |

### Response



```json
{
  "success": true,
  "action": "mouse-move",
  "details": {
    "x": 540,
    "y": 312,
    "screen": 0
  }
}
```


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


```json
{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Input action queue is full"
}
```


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


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



### SDK Usage

```ts
await client.display.input.mouseMove({ x: 540, y: 312, screen: 0 });
```

---

### `POST /api/v1/display/mouse/move-relative`

Moves the cursor by a relative offset from its current position.

### 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 |
|------|------|----------|-------------|
| `x` | integer | Yes | Horizontal offset in pixels |
| `y` | integer | Yes | Vertical offset in pixels |
| `sync` | boolean | No | Wait for the move to complete before returning |

### Response



```json
{
  "success": true,
  "action": "mouse-move-relative",
  "details": {
    "x": 25,
    "y": -10
  }
}
```


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


```json
{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Input action queue is full"
}
```


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


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



### SDK Usage

```ts
await client.display.input.mouseMoveRelative({ x: 25, y: -10 });
```

---

### `POST /api/v1/display/mouse/scroll`

Scrolls in one of four directions.

### 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 | Default | Description |
|------|------|----------|---------|-------------|
| `direction` | string | Yes | — | Scroll direction. One of: `up`, `down`, `left`, `right` |
| `clicks` | integer | No | `5` | Number of scroll clicks. Range: `1`–`100` |

### Response



```json
{
  "success": true,
  "action": "scroll",
  "details": {
    "direction": "down",
    "clicks": 5
  }
}
```


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


```json
{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Input action queue is full"
}
```


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


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



### SDK Usage

```ts
await client.display.input.mouseScroll({ direction: "down", clicks: 5 });
```

---

## Window Management

Focus, move, resize, close, and search for windows on the display.

### `POST /api/v1/display/window/close`

Closes a window by ID.

### 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 |
|------|------|----------|-------------|
| `windowId` | integer \| string | Yes | Window ID (decimal or hex `0x...`) |

### Response



```json
{
  "success": true,
  "action": "window-close",
  "details": {
    "windowId": 1234567
  }
}
```


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


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


```json
{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Input action queue is full"
}
```


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


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



### SDK Usage

```ts
await client.display.input.windowClose({ windowId: 1234567 });
```

---

### `POST /api/v1/display/window/focus`

Activates (focuses) a window by ID.

### 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 |
|------|------|----------|-------------|
| `windowId` | integer \| string | Yes | Window ID (decimal or hex `0x...`) |

### Response



```json
{
  "success": true,
  "action": "window-focus",
  "details": {
    "windowId": 1234567
  }
}
```


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


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


```json
{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Input action queue is full"
}
```


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


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



### SDK Usage

```ts
await client.display.input.windowFocus({ windowId: 1234567 });
```

---

### `POST /api/v1/display/window/minimize`

Minimizes a window by ID.

### 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 |
|------|------|----------|-------------|
| `windowId` | integer \| string | Yes | Window ID (decimal or hex `0x...`) |

### Response



```json
{
  "success": true,
  "action": "window-minimize",
  "details": {
    "windowId": 1234567
  }
}
```


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


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


```json
{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Input action queue is full"
}
```


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


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



### SDK Usage

```ts
await client.display.input.windowMinimize({ windowId: 1234567 });
```

---

### `POST /api/v1/display/window/move`

Moves a window to a new position. Supports absolute and relative moves.

### 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 |
|------|------|----------|-------------|
| `windowId` | integer \| string | Yes | Window ID (decimal or hex `0x...`) |
| `x` | integer | Yes | Target X coordinate |
| `y` | integer | Yes | Target Y coordinate |
| `sync` | boolean | No | Wait for the move to complete before returning |
| `relative` | boolean | No | Treat coordinates as relative to the current position |

### Response



```json
{
  "success": true,
  "action": "window-move",
  "details": {
    "windowId": 1234567,
    "x": 100,
    "y": 50,
    "relative": false
  }
}
```


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


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


```json
{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Input action queue is full"
}
```


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


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



### SDK Usage

```ts
await client.display.input.windowMove({ windowId: 1234567, x: 100, y: 50 });
```

---

### `POST /api/v1/display/window/raise`

Raises a window to the top of the stacking order.

### 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 |
|------|------|----------|-------------|
| `windowId` | integer \| string | Yes | Window ID (decimal or hex `0x...`) |

### Response



```json
{
  "success": true,
  "action": "window-raise",
  "details": {
    "windowId": 1234567
  }
}
```


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


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


```json
{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Input action queue is full"
}
```


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


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



### SDK Usage

```ts
await client.display.input.windowRaise({ windowId: 1234567 });
```

---

### `POST /api/v1/display/window/resize`

Resizes a window to a new width and height.

### 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 |
|------|------|----------|-------------|
| `windowId` | integer \| string | Yes | Window ID (decimal or hex `0x...`) |
| `width` | integer | Yes | New window width. Minimum: `0` |
| `height` | integer | Yes | New window height. Minimum: `0` |
| `sync` | boolean | No | Wait for the resize to complete before returning |
| `useHints` | boolean | No | Send resize as a size-hint instead of forcing a new size |

### Response



```json
{
  "success": true,
  "action": "window-resize",
  "details": {
    "windowId": 1234567,
    "width": 1280,
    "height": 720
  }
}
```


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


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


```json
{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Input action queue is full"
}
```


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


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



### SDK Usage

```ts
await client.display.input.windowResize({ windowId: 1234567, width: 1280, height: 720 });
```

---

### `POST /api/v1/display/window/search`

Searches for windows matching a regex pattern across name, class, and classname fields.

### 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 |
|------|------|----------|-------------|
| `pattern` | string | Yes | Search pattern (regex). Max length: `200` |
| `name` | boolean | No | Search by window name/title |
| `class` | boolean | No | Search by window class |
| `classname` | boolean | No | Search by window classname |
| `onlyVisible` | boolean | No | Only return visible windows |

### Response



```json
{
  "success": true,
  "windows": [1234567, 1234568, 7654321]
}
```


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


```json
{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Input action queue is full"
}
```


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


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



### SDK Usage

```ts
const matches = await client.display.input.windowSearch({
  pattern: "Visual Studio",
  name: true,
  onlyVisible: true,
});
```