Displays: Input Actions

Download Page (.md)

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.

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

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

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

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

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

SDK Usage

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

{
  "success": true,
  "x": 540,
  "y": 312,
  "screen": 0,
  "window": 1234567
}

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

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

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

SDK Usage

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

{
  "success": true,
  "windowId": 1234567
}

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

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

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

SDK Usage

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

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

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

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

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

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

SDK Usage

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

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

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

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

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

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

SDK Usage

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

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

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

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

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

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

SDK Usage

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

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

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

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

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

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

SDK Usage

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

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

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

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

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

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

SDK Usage

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

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

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

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

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

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

SDK Usage

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

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

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

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

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

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

SDK Usage

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

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

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

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

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

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

SDK Usage

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

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

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

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

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

SDK Usage

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

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

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

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

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

SDK Usage

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

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

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

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

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

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

SDK Usage

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

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

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

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

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

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

SDK Usage

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

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

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

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

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

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

SDK Usage

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

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

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

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

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

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

SDK Usage

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

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

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

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

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

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

SDK Usage

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

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

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

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

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

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

SDK Usage

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

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

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

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

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

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

SDK Usage

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

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

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

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

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

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

SDK Usage

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

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

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

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

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

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

SDK Usage

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

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

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

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

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

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

SDK Usage

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

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

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

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

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

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

SDK Usage

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

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

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

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

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

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

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

SDK Usage

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

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

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

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

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

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

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

SDK Usage

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

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

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

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

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

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

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

SDK Usage

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

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

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

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

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

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

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

SDK Usage

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

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

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

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

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

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

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

SDK Usage

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

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

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

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

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

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

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

SDK Usage

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

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

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

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

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

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

SDK Usage

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