v13

latestOpenAPI 3.1.0raw.githubusercontent.com2026-08-065499150.5 KB

phones

Allocate a phone

Allocates an Android phone and opens a session. Omit workflow_id for an interactive lease (drive the phone directly); set it to allocate for a workflow. Pass phone_id to pin a specific dedicated phone. If allocation setup fails the claim is rolled back, so you are never billed for a session that never starts.

post/phones/allocate

Request body

$schemastring uri

A URL to the JSON Schema for this object.

captureboolean

Capture media this session produces on the phone into the org's file library (default true). false disables capture for this session entirely.

namestring

Optional session label (letters, numbers, dots, hyphens, underscores; max 64). Unique among the org's active sessions - allocating with a name already in use returns a conflict.

phone_idstring

PhoneID pins allocation to a specific device (for dedicated devices).

phone_type'android' required

Category of device to allocate.

pool'shared' | 'dedicated'

Which pool to draw the phone from. Omit for shared. 'dedicated' claims any idle phone your organization rents; combine with phone_id to pin a specific one.

recordingboolean

Record this session's screen (default true). false suppresses the video recording and rolling thumbnail entirely - no screen content is ever written.

tagsobject

Optional key->value labels for organizing sessions (max 50 tags; keys up to 40 chars, values up to 128).

telemetryboolean

Persist this session's telemetry spans (default true). false skips the durable trace store; the live telemetry stream still works while the session runs.

workflow_idstring

Workflow requesting allocation; nil for an interactive lease.

Example request

{
  "$schema": "/api/v1/PhoneAllocateRequest.json"
}

Response

$schemastring uri

A URL to the JSON Schema for this object.

control_urlstring

WebSocket URL for driving the phone over the device control protocol.

live_view_urlstring

Hosted live-view page URL (live screen + interaction, iframe-embeddable). Contains a session-scoped capability token; treat as a secret. Dies with the session.

phone_idstring required

Allocated device's identifier.

regionstring

Physical region or location of the device.

session_idstring required

Device_allocations row id — the canonical session identifier (WS-ID2).

telemetry_urlstring

WebSocket URL for the session's live telemetry stream (trace spans + output logs, read-only). Dies with the session.

workflow_started_atstring date-time required

Timestamp when the session started.

Example response

{
  "$schema": "/api/v1/PhoneAllocateResponse.json"
}