Displays: Input Actions

Use these endpoints to drive low-level interaction with a running display container: dispatch synthetic mouse and keyboard events, manage windows, read on-screen geometry, and capture screenshots. Every endpoint targets the container’s display service and supports the optional displayId query parameter to override the hostname instance segment.

The base URL for all examples below is https://{projectId}-{containerId}-display-1.{server}.containers.hoody.com.

State queries

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

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

curl -X GET "https://67e89abc123def456789abcd-890abcdef12345678901cdef-display-1.node-us.containers.hoody.com/api/v1/display/input/display-geometry" \
  -H "Authorization: Bearer $HOODY_TOKEN"

import { HoodyClient } from 'hoody-sdk';

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

await client.display.input.geometry();

{
  "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": "Input action failed"
}

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

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

Returns the current cursor position and the window beneath 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

curl -X GET "https://67e89abc123def456789abcd-890abcdef12345678901cdef-display-1.node-us.containers.hoody.com/api/v1/display/mouse/location" \
  -H "Authorization: Bearer $HOODY_TOKEN"

import { HoodyClient } from 'hoody-sdk';

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

await client.display.input.mouseLocation();

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

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

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

Returns the position and size of 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
`windowId`	path	string	Yes	Window ID (decimal or hex)

curl -X GET "https://67e89abc123def456789abcd-890abcdef12345678901cdef-display-1.node-us.containers.hoody.com/api/v1/display/window/12345/geometry" \
  -H "Authorization: Bearer $HOODY_TOKEN"

import { HoodyClient } from 'hoody-sdk';

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

await client.display.input.windowGeometry("12345");

{
  "success": true,
  "windowId": 12345,
  "x": 100,
  "y": 100,
  "width": 800,
  "height": 600
}

{
  "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": "Input action failed"
}

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

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

Returns the title of 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
`windowId`	path	string	Yes	Window ID (decimal or hex)

curl -X GET "https://67e89abc123def456789abcd-890abcdef12345678901cdef-display-1.node-us.containers.hoody.com/api/v1/display/window/12345/name" \
  -H "Authorization: Bearer $HOODY_TOKEN"

import { HoodyClient } from 'hoody-sdk';

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

await client.display.input.windowName("12345");

{
  "success": true,
  "windowId": 12345,
  "name": "Untitled - gedit"
}

{
  "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": "Input action failed"
}

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

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

Returns the ID of the currently focused window.

Parameters

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

curl -X GET "https://67e89abc123def456789abcd-890abcdef12345678901cdef-display-1.node-us.containers.hoody.com/api/v1/display/window/active" \
  -H "Authorization: Bearer $HOODY_TOKEN"

import { HoodyClient } from 'hoody-sdk';

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

await client.display.input.windowActive();

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

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

General input actions

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

Executes a single named action with an optional screenshot capture.

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

curl -X POST "https://67e89abc123def456789abcd-890abcdef12345678901cdef-display-1.node-us.containers.hoody.com/api/v1/display/input/act" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action":"mouse/click","params":{"button":1},"screenshot":true}'

import { HoodyClient } from 'hoody-sdk';

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

await client.display.input.act({
  action: "mouse/click",
  params: { button: 1 },
  screenshot: true
});

{
  "success": true,
  "action": {
    "success": true,
    "action": "mouse/click",
    "details": {}
  },
  "screenshot": {
    "timestamp": "2024-01-15T12:34:56.789Z",
    "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": "Action queue is full"
}

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

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

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

Executes a sequence of actions atomically and returns per-action results.

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	Ordered list of actions to execute (1-50 items). Each item has `action` (string, required) and `params` (object, optional).

curl -X POST "https://67e89abc123def456789abcd-890abcdef12345678901cdef-display-1.node-us.containers.hoody.com/api/v1/display/input/batch" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"actions":[{"action":"mouse/move","params":{"x":100,"y":100}},{"action":"mouse/click","params":{"button":1}}]}'

import { HoodyClient } from 'hoody-sdk';

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

await client.display.input.batch({
  actions: [
    { action: "mouse/move", params: { x: 100, y: 100 } },
    { action: "mouse/click", params: { button: 1 } }
  ]
});

{
  "success": true,
  "completed": [
    { "index": 0, "action": "mouse/move", "success": true },
    { "index": 1, "action": "mouse/click", "success": true }
  ],
  "failed": null,
  "skipped": []
}

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

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

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

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

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

Moves the cursor to a position 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	Description
`x`	integer	Yes	Target X coordinate
`y`	integer	Yes	Target Y coordinate
`button`	integer	No	Mouse button (1=left, 2=middle, 3=right, 4-7=extra). Default: `1`

curl -X POST "https://67e89abc123def456789abcd-890abcdef12345678901cdef-display-1.node-us.containers.hoody.com/api/v1/display/input/click-at" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"x":250,"y":140,"button":1}'

import { HoodyClient } from 'hoody-sdk';

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

await client.display.input.clickAt({
  x: 250,
  y: 140,
  button: 1
});

{
  "success": true,
  "action": "click-at",
  "details": {}
}

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

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

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

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

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

Drags from a start point to an end point.

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
`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	Mouse button (1=left, 2=middle, 3=right, 4-7=extra). Default: `1`
`steps`	integer	No	Number of intermediate mouse positions for smooth drag (1-1000)

curl -X POST "https://67e89abc123def456789abcd-890abcdef12345678901cdef-display-1.node-us.containers.hoody.com/api/v1/display/input/drag" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"startX":100,"startY":100,"endX":500,"endY":500,"steps":20}'

import { HoodyClient } from 'hoody-sdk';

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

await client.display.input.drag({
  startX: 100,
  startY: 100,
  endX: 500,
  endY: 500,
  steps: 20
});

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

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

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

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

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

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

Emergency release of all held inputs (mouse buttons and 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

curl -X POST "https://67e89abc123def456789abcd-890abcdef12345678901cdef-display-1.node-us.containers.hoody.com/api/v1/display/input/reset" \
  -H "Authorization: Bearer $HOODY_TOKEN"

import { HoodyClient } from 'hoody-sdk';

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

await client.display.input.reset();

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

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

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

Selects a range by clicking the start point and shift-clicking the end point.

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

curl -X POST "https://67e89abc123def456789abcd-890abcdef12345678901cdef-display-1.node-us.containers.hoody.com/api/v1/display/input/select" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"x":120,"y":80,"endX":420,"endY":280}'

import { HoodyClient } from 'hoody-sdk';

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

await client.display.input.select({
  x: 120,
  y: 80,
  endX: 420,
  endY: 280
});

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

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

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

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

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

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

Moves to a position, clicks to focus, and types text — all in one call.

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 10000 chars)
`delay`	integer	No	Inter-keystroke delay in milliseconds (0-1000)

curl -X POST "https://67e89abc123def456789abcd-890abcdef12345678901cdef-display-1.node-us.containers.hoody.com/api/v1/display/input/type-at" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"x":300,"y":200,"text":"hello world","delay":10}'

import { HoodyClient } from 'hoody-sdk';

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

await client.display.input.typeAt({
  x: 300,
  y: 200,
  text: "hello world",
  delay: 10
});

{
  "success": true,
  "action": "type-at",
  "details": {}
}

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

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

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

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

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

Waits for a specified duration and optionally captures a 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	Description
`ms`	integer	Yes	Wait duration in milliseconds (50-30000)
`screenshot`	boolean	No	Capture screenshot after wait. Default: `false`

curl -X POST "https://67e89abc123def456789abcd-890abcdef12345678901cdef-display-1.node-us.containers.hoody.com/api/v1/display/input/wait" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ms":500,"screenshot":true}'

import { HoodyClient } from 'hoody-sdk';

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

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

{
  "success": true,
  "action": "wait",
  "details": {
    "ms": 500
  },
  "screenshot": {
    "timestamp": "2024-01-15T12:34:56.789Z",
    "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"
}

Keyboard

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

Presses one or more key combinations. Each element of keys is pressed in sequence.

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, max 100 chars each
`window`	integer \| string	No	Target window ID (decimal or hex)
`delay`	integer	No	Delay in milliseconds (0-5000)
`clearModifiers`	boolean	No	Clear modifier keys before pressing

curl -X POST "https://67e89abc123def456789abcd-890abcdef12345678901cdef-display-1.node-us.containers.hoody.com/api/v1/display/keyboard/key" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"keys":["ctrl+a","Delete"],"clearModifiers":true}'

import { HoodyClient } from 'hoody-sdk';

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

await client.display.input.keyboardKey({
  keys: ["ctrl+a", "Delete"],
  clearModifiers: true
});

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

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

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

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

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

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

Holds a single key down. Pair with key-up to release.

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 100 chars
`window`	integer \| string	No	Target window ID
`holdMs`	integer	No	Auto-release after this many milliseconds (100-60000)

curl -X POST "https://67e89abc123def456789abcd-890abcdef12345678901cdef-display-1.node-us.containers.hoody.com/api/v1/display/keyboard/key-down" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"key":"Shift_L","holdMs":2000}'

import { HoodyClient } from 'hoody-sdk';

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

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

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

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

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

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

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

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

Releases a key previously held with key-down.

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); max 100 chars
`window`	integer \| string	No	Target window ID

curl -X POST "https://67e89abc123def456789abcd-890abcdef12345678901cdef-display-1.node-us.containers.hoody.com/api/v1/display/keyboard/key-up" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"key":"Shift_L"}'

import { HoodyClient } from 'hoody-sdk';

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

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

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

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

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

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

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

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

Types a string of text into the focused window.

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 10000 chars)
`window`	integer \| string	No	Target window ID
`delay`	integer	No	Inter-keystroke delay in milliseconds (0-1000)
`clearModifiers`	boolean	No	Clear modifier keys before typing

curl -X POST "https://67e89abc123def456789abcd-890abcdef12345678901cdef-display-1.node-us.containers.hoody.com/api/v1/display/keyboard/type" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text":"The quick brown fox.","delay":5}'

import { HoodyClient } from 'hoody-sdk';

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

await client.display.input.keyboardType({
  text: "The quick brown fox.",
  delay: 5
});

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

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

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

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

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

Mouse

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

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

curl -X POST "https://67e89abc123def456789abcd-890abcdef12345678901cdef-display-1.node-us.containers.hoody.com/api/v1/display/mouse/click" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"button":1,"repeat":1}'

import { HoodyClient } from 'hoody-sdk';

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

await client.display.input.mouseClick({
  button: 1,
  repeat: 1
});

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

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

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

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

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

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

Double-clicks the mouse button 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
`button`	integer	No	Mouse button (1=left, 2=middle, 3=right, 4-7=extra). Default: `1`
`window`	integer \| string	No	Target window ID

curl -X POST "https://67e89abc123def456789abcd-890abcdef12345678901cdef-display-1.node-us.containers.hoody.com/api/v1/display/mouse/double-click" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"button":1}'

import { HoodyClient } from 'hoody-sdk';

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

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

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

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

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

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

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

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

Presses and holds a mouse button. Pair with mouse/up to release, or set holdMs to auto-release.

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

curl -X POST "https://67e89abc123def456789abcd-890abcdef12345678901cdef-display-1.node-us.containers.hoody.com/api/v1/display/mouse/down" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"button":1,"holdMs":1500}'

import { HoodyClient } from 'hoody-sdk';

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

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

{
  "success": true,
  "action": "mouse-down",
  "details": {}
}

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

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

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

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

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

Moves the cursor to an absolute screen coordinate.

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 (-65535 to 65535)
`y`	integer	Yes	Target Y coordinate (-65535 to 65535)
`window`	integer \| string	No	Target window ID
`screen`	integer	No	Target screen index (0-15)
`sync`	boolean	No	Wait for the move to settle before returning

curl -X POST "https://67e89abc123def456789abcd-890abcdef12345678901cdef-display-1.node-us.containers.hoody.com/api/v1/display/mouse/move" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"x":640,"y":360,"screen":0}'

import { HoodyClient } from 'hoody-sdk';

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

await client.display.input.mouseMove({
  x: 640,
  y: 360,
  screen: 0
});

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

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

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

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

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

`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
`y`	integer	Yes	Vertical offset
`sync`	boolean	No	Wait for the move to settle before returning

curl -X POST "https://67e89abc123def456789abcd-890abcdef12345678901cdef-display-1.node-us.containers.hoody.com/api/v1/display/mouse/move-relative" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"x":50,"y":-20}'

import { HoodyClient } from 'hoody-sdk';

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

await client.display.input.mouseMoveRelative({
  x: 50,
  y: -20
});

{
  "success": true,
  "action": "move-relative",
  "details": {}
}

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

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

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

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

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

curl -X POST "https://67e89abc123def456789abcd-890abcdef12345678901cdef-display-1.node-us.containers.hoody.com/api/v1/display/mouse/scroll" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"direction":"down","clicks":5}'

import { HoodyClient } from 'hoody-sdk';

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

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

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

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

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

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

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

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

Releases a mouse button previously held with mouse/down.

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

curl -X POST "https://67e89abc123def456789abcd-890abcdef12345678901cdef-display-1.node-us.containers.hoody.com/api/v1/display/mouse/up" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"button":1}'

import { HoodyClient } from 'hoody-sdk';

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

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

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

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

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

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

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

Window management

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

curl -X POST "https://67e89abc123def456789abcd-890abcdef12345678901cdef-display-1.node-us.containers.hoody.com/api/v1/display/window/close" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"windowId":12345}'

import { HoodyClient } from 'hoody-sdk';

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

await client.display.input.windowClose({
  windowId: 12345
});

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

{
  "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": "Action queue is full"
}

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

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

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

Focuses (activates) 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...`)

curl -X POST "https://67e89abc123def456789abcd-890abcdef12345678901cdef-display-1.node-us.containers.hoody.com/api/v1/display/window/focus" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"windowId":12345}'

import { HoodyClient } from 'hoody-sdk';

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

await client.display.input.windowFocus({
  windowId: 12345
});

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

{
  "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": "Action queue is full"
}

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

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

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

curl -X POST "https://67e89abc123def456789abcd-890abcdef12345678901cdef-display-1.node-us.containers.hoody.com/api/v1/display/window/minimize" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"windowId":12345}'

import { HoodyClient } from 'hoody-sdk';

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

await client.display.input.windowMinimize({
  windowId: 12345
});

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

{
  "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": "Action queue is full"
}

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

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

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

Moves a window to a new position. Use relative: true to offset from the 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
`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 settle before returning
`relative`	boolean	No	Treat `x`/`y` as offsets from the current position

curl -X POST "https://67e89abc123def456789abcd-890abcdef12345678901cdef-display-1.node-us.containers.hoody.com/api/v1/display/window/move" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"windowId":12345,"x":50,"y":50}'

import { HoodyClient } from 'hoody-sdk';

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

await client.display.input.windowMove({
  windowId: 12345,
  x: 50,
  y: 50
});

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

{
  "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": "Action queue is full"
}

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

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

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

curl -X POST "https://67e89abc123def456789abcd-890abcdef12345678901cdef-display-1.node-us.containers.hoody.com/api/v1/display/window/raise" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"windowId":12345}'

import { HoodyClient } from 'hoody-sdk';

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

await client.display.input.windowRaise({
  windowId: 12345
});

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

{
  "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": "Action queue is full"
}

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

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

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

Resizes a window.

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 width (min 0)
`height`	integer	Yes	New height (min 0)
`sync`	boolean	No	Wait for the resize to settle before returning
`useHints`	boolean	No	Use WM size hints instead of forcing the window manager to resize

curl -X POST "https://67e89abc123def456789abcd-890abcdef12345678901cdef-display-1.node-us.containers.hoody.com/api/v1/display/window/resize" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"windowId":12345,"width":1024,"height":768}'

import { HoodyClient } from 'hoody-sdk';

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

await client.display.input.windowResize({
  windowId: 12345,
  width: 1024,
  height: 768
});

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

{
  "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": "Action queue is full"
}

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

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

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

Searches for windows whose name, class, or classname matches a regex pattern.

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 200 chars
`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

curl -X POST "https://67e89abc123def456789abcd-890abcdef12345678901cdef-display-1.node-us.containers.hoody.com/api/v1/display/window/search" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"pattern":"^Terminal","name":true,"onlyVisible":true}'

import { HoodyClient } from 'hoody-sdk';

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

await client.display.input.windowSearch({
  pattern: "^Terminal",
  name: true,
  onlyVisible: true
});

{
  "success": true,
  "windows": [12345, 67890]
}

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

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

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

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