Reference

input

Actions. Locator and ref targets auto-wait on the runtime side. Index · shared schemas · errors.

Procedure	Summary	REST	MCP tool	Stability
`input.tap`	Tap an element or a point after auto-waiting	`POST`	`input_tap`	stable
`input.doubleTap`	Double-tap	`POST`	`input_doubleTap`	stable
`input.longPress`	Press and hold	`POST`	`input_longPress`	stable
`input.swipe`	Swipe on a target or the screen. `direction` is the finger's direction of travel.	`POST`	`input_swipe`	stable
`input.drag`	Drag from one target to another	`POST`	—	stable
`input.pinch`	Two-finger pinch; `scale` above 1 zooms in	`POST`	—	stable
`input.type`	Type text as key events into the target (tapped first) or the focused element	`POST`	`input_type`	stable
`input.fill`	Clear an editable element, then set its value	`POST`	`input_fill`	stable
`input.pressKey`	Press one key (W3C `KeyboardEvent.key` names)	`POST`	`input_pressKey`	stable
`input.pressButton`	Press a hardware button	`POST`	`input_pressButton`	stable
`input.scroll`	Scroll a container. `direction` is the content direction (`down` reveals content below). `until` scrolls until a locator is visible.	`POST`	`input_scroll`	stable
`input.setOrientation`	Rotate the device	`POST`	`input_setOrientation`	stable
`input.gesture`	Play a multi-finger gesture: each contact follows its timed points	`POST`	—	stable
`input.hideKeyboard`	Dismiss the software keyboard	`POST`	`input_hideKeyboard`	stable

`input.tap`

Tap an element or a point after auto-waiting


REST	`POST /v1/input/tap` (input as a JSON body)
RPC	`/rpc/v2/input/tap`
MCP	tool `input_tap`; hints: none
Auth	`devices:drive`
Tenancy	`project`
Requires	`input.touch` or `input.semantic`
Troupe Cloud	relayed through the host agent to the device host’s runtime
Stability	stable, since 1.0

Input:

TypeScript

{
  sessionId: SessionId
  target: Target
  position?: Point
  timeoutMs?: TimeoutMs  // default 5000
  force?: boolean  // default false
}

Output:

TypeScript

ActionResult

Errors: L.

Named types: ActionResult, Point, SessionId, Target, TimeoutMs.

`input.doubleTap`

Double-tap


REST	`POST /v1/input/double-tap` (input as a JSON body)
RPC	`/rpc/v2/input/doubleTap`
MCP	tool `input_doubleTap`; hints: none
Auth	`devices:drive`
Tenancy	`project`
Requires	`input.touch`
Troupe Cloud	relayed through the host agent to the device host’s runtime
Stability	stable, since 1.0

Input:

TypeScript

{
  sessionId: SessionId
  target: Target
  position?: Point
  timeoutMs?: TimeoutMs  // default 5000
  force?: boolean  // default false
}

Output:

TypeScript

ActionResult

Errors: L.

Named types: ActionResult, Point, SessionId, Target, TimeoutMs.

`input.longPress`

Press and hold


REST	`POST /v1/input/long-press` (input as a JSON body)
RPC	`/rpc/v2/input/longPress`
MCP	tool `input_longPress`; hints: none
Auth	`devices:drive`
Tenancy	`project`
Requires	`input.touch`
Troupe Cloud	relayed through the host agent to the device host’s runtime
Stability	stable, since 1.0

Input:

TypeScript

{
  sessionId: SessionId
  target: Target
  position?: Point
  timeoutMs?: TimeoutMs  // default 5000
  force?: boolean  // default false
  durationMs?: DurationMs  // default 800
}

Output:

TypeScript

ActionResult

Errors: L.

Named types: ActionResult, DurationMs, Point, SessionId, Target, TimeoutMs.

`input.swipe`

Swipe on a target or the screen. direction is the finger's direction of travel.


REST	`POST /v1/input/swipe` (input as a JSON body)
RPC	`/rpc/v2/input/swipe`
MCP	tool `input_swipe`; hints: none
Auth	`devices:drive`
Tenancy	`project`
Requires	`input.touch`
Troupe Cloud	relayed through the host agent to the device host’s runtime
Stability	stable, since 1.0

Input:

TypeScript

{
  sessionId: SessionId
  target?: Target
  direction: 'up' | 'down' | 'left' | 'right'
  distance?: number  // default 0.6; > 0 and ≤ 1
  durationMs?: DurationMs  // default 300
  timeoutMs?: TimeoutMs  // default 5000
}

Output:

TypeScript

ActionResult

Errors: L.

Named types: ActionResult, DurationMs, SessionId, Target, TimeoutMs.

`input.drag`

Drag from one target to another


REST	`POST /v1/input/drag` (input as a JSON body)
RPC	`/rpc/v2/input/drag`
MCP	not a tool (low value or high risk for agents); hints: none
Auth	`devices:drive`
Tenancy	`project`
Requires	`input.touch`
Troupe Cloud	relayed through the host agent to the device host’s runtime
Stability	stable, since 1.0

Input:

TypeScript

{
  sessionId: SessionId
  from: Target
  to: Target
  holdMs?: DurationMs  // default 0
  durationMs?: DurationMs  // default 500
  timeoutMs?: TimeoutMs  // default 5000
}

Output:

TypeScript

ActionResult

Errors: L.

Named types: ActionResult, DurationMs, SessionId, Target, TimeoutMs.

`input.pinch`

Two-finger pinch; scale above 1 zooms in


REST	`POST /v1/input/pinch` (input as a JSON body)
RPC	`/rpc/v2/input/pinch`
MCP	not a tool (low value or high risk for agents); hints: none
Auth	`devices:drive`
Tenancy	`project`
Requires	`input.touch`; `input.maxContacts` ≥ 2
Troupe Cloud	relayed through the host agent to the device host’s runtime
Stability	stable, since 1.0

Input:

TypeScript

{
  sessionId: SessionId
  target?: Target
  scale: number  // 0.1–10
  durationMs?: DurationMs  // default 400
}

Output:

TypeScript

ActionResult

Errors: L.

Named types: ActionResult, DurationMs, SessionId, Target.

`input.type`

Type text as key events into the target (tapped first) or the focused element


REST	`POST /v1/input/type` (input as a JSON body)
RPC	`/rpc/v2/input/type`
MCP	tool `input_type`; hints: none
Auth	`devices:drive`
Tenancy	`project`
Requires	`input.keyboard`
Troupe Cloud	relayed through the host agent to the device host’s runtime
Stability	stable, since 1.0

Input:

TypeScript

{
  sessionId: SessionId
  target?: Target
  text: string  // ≤ 4096 chars
  delayMs?: DurationMs
  timeoutMs?: TimeoutMs  // default 5000
}

Output:

TypeScript

ActionResult

Errors: L, SECRET_UNAVAILABLE.

Named types: ActionResult, DurationMs, SessionId, Target, TimeoutMs.

`input.fill`

Clear an editable element, then set its value


REST	`POST /v1/input/fill` (input as a JSON body)
RPC	`/rpc/v2/input/fill`
MCP	tool `input_fill`; hints: idempotent
Auth	`devices:drive`
Tenancy	`project`
Requires	`input.keyboard`
Troupe Cloud	relayed through the host agent to the device host’s runtime
Stability	stable, since 1.0

Input:

TypeScript

{
  sessionId: SessionId
  target: Target
  value: string  // ≤ 65536 chars
  timeoutMs?: TimeoutMs  // default 5000
}

Output:

TypeScript

ActionResult

Errors: L, SECRET_UNAVAILABLE.

Named types: ActionResult, SessionId, Target, TimeoutMs.

`input.pressKey`

Press one key (W3C KeyboardEvent.key names)


REST	`POST /v1/input/press-key` (input as a JSON body)
RPC	`/rpc/v2/input/pressKey`
MCP	tool `input_pressKey`; hints: none
Auth	`devices:drive`
Tenancy	`project`
Requires	`input.keyboard` = 'keys'
Troupe Cloud	relayed through the host agent to the device host’s runtime
Stability	stable, since 1.0

Input:

TypeScript

{
  sessionId: SessionId
  key: string  // 1–32 chars
  modifiers?: ('Alt' | 'Control' | 'Meta' | 'Shift')[]  // ≤ 4 items
}

Output:

TypeScript

ActionResult

Errors: D, TIMEOUT.

Named types: ActionResult, SessionId.

`input.pressButton`

Press a hardware button


REST	`POST /v1/input/press-button` (input as a JSON body)
RPC	`/rpc/v2/input/pressButton`
MCP	tool `input_pressButton`; hints: none
Auth	`devices:drive`
Tenancy	`project`
Requires	`input.buttons` contains the input's `button`
Troupe Cloud	relayed through the host agent to the device host’s runtime
Stability	stable, since 1.0

Input:

TypeScript

{ sessionId: SessionId; button: ButtonName; durationMs?: DurationMs }

Output:

TypeScript

ActionResult

Errors: D, TIMEOUT.

Named types: ActionResult, ButtonName, DurationMs, SessionId.

`input.scroll`

Scroll a container. direction is the content direction (down reveals content below). until scrolls until a locator is visible.


REST	`POST /v1/input/scroll` (input as a JSON body)
RPC	`/rpc/v2/input/scroll`
MCP	tool `input_scroll`; hints: none
Auth	`devices:drive`
Tenancy	`project`
Requires	`input.touch` or `input.semantic`
Troupe Cloud	relayed through the host agent to the device host’s runtime
Stability	stable, since 1.0

Input:

TypeScript

{
  sessionId: SessionId
  target?: Target
  direction: 'up' | 'down' | 'left' | 'right'
  distance?: number  // > 0 and ≤ 1
  until?: Locator
  maxScrolls?: integer  // default 10; 1–100
  timeoutMs?: TimeoutMs  // default 5000
}

Output:

TypeScript

{ scrolls: integer; found?: A11yNode }

Errors: L.

Named types: A11yNode, Locator, SessionId, Target, TimeoutMs.

`input.setOrientation`

Rotate the device


REST	`POST /v1/input/set-orientation` (input as a JSON body)
RPC	`/rpc/v2/input/setOrientation`
MCP	tool `input_setOrientation`; hints: idempotent
Auth	`devices:drive`
Tenancy	`project`
Requires	`input.rotate`
Troupe Cloud	relayed through the host agent to the device host’s runtime
Stability	stable, since 1.0

Input:

TypeScript

{ sessionId: SessionId; orientation: Orientation }

Output:

TypeScript

{ orientation: OrientationOut; width: number; height: number }

Errors: D, TIMEOUT.

Named types: Orientation, OrientationOut, SessionId.

`input.gesture`

Play a multi-finger gesture: each contact follows its timed points


REST	`POST /v1/input/gesture` (input as a JSON body)
RPC	`/rpc/v2/input/gesture`
MCP	not a tool (runner and inspector plumbing); hints: none
Auth	`devices:drive`
Tenancy	`project`
Requires	`input.touch`; `input.maxContacts` ≥ the length of the input's `contacts`
Troupe Cloud	relayed through the host agent to the device host’s runtime
Stability	stable, since 1.0

Input:

TypeScript

{
  sessionId: SessionId
  contacts: {
    id: integer  // 0–9
    points: {
      x: number
      y: number
      t: number  // ≥ 0
    }[]  // 1–1000 items
  }[]  // 1–10 items
}

Output:

TypeScript

{ durationMs: number }

Errors: D, TIMEOUT.

Named types: SessionId.

`input.hideKeyboard`

Dismiss the software keyboard


REST	`POST /v1/input/hide-keyboard` (input as a JSON body)
RPC	`/rpc/v2/input/hideKeyboard`
MCP	tool `input_hideKeyboard`; hints: idempotent
Auth	`devices:drive`
Tenancy	`project`
Requires	`input.hideKeyboard`
Troupe Cloud	relayed through the host agent to the device host’s runtime
Stability	stable, since 1.0

Input:

TypeScript

{ sessionId: SessionId }

Output:

TypeScript

{ wasVisible: boolean }

Errors: D, TIMEOUT.

Named types: SessionId.