Sign in

v12

latestOpenAPI 3.1.0raw.githubusercontent.com2026-08-014994227.2 KB
phones

Allocate a phone

Allocates a 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.

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' | 'iphone' required

Category of device to allocate.

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

OK

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