v1

latestOpenAPI 3.1.0MIT2026-08-0481194343.8 KB
machines

Browser convenience sub-API

Convenience mapping to the strict browser_* action commands. A mutating operation on an external machine requires precondition_frame_id; read-only state/DOM/screenshot operations may omit it.

post/v1/machines/{machine_id}/browser/{op}

Headers

Idempotency-Keystring

Optional client-supplied key (≤128 chars, [A-Za-z0-9_-:]) for safe retries. Keys are global within one concrete API-key credential plus live/test mode; never reuse one on another endpoint. 'Same request' = a SHA-256 of an explicit operation discriminator plus the canonical (sorted-key) JSON body (session_id is folded in for /sessions/{id}/predict). LLM-capable operations also bind the non-secret effective provider, role models, and one-way provider-key fingerprint; plaintext provider keys never enter the hash or replay record. Replays the response for 24 h when operation, body, and effective execution identity match (X-Coasty-Idempotent-Replay: true and X-Credits-Charged: 0). Action screenshot pixels are response-only and deliberately omitted from replay storage; a replay retains frame_id but returns screenshot=null and observation_available=false. Inference replays also set body usage.credits_charged=0 and usage.billed=false; machine-snapshot bodies retain the original gross charge for auditability. A retry while the original is still running waits up to ~25 s then returns the result, otherwise 409 IDEMPOTENCY_IN_FLIGHT (retry with the SAME key). Returns 422 IDEMPOTENCY_KEY_REUSED if any bound input differs. Rotating the API key starts a new replay namespace. Collect a lost result via GET /v1/idempotency/{key} using the original credential.

Request body

parametersobject
timeout_msinteger nullable
precondition_frame_idstring uuid nullable

Required when this convenience operation mutates an external machine.

Response

Browser action result.

machine_idstring required
commandstring required
successboolean required
resultobject nullable
errorstring nullable
duration_msinteger required
screenshotstring nullable

Typed post-action screenshot when the transport returns one. External-machine mutations commit this observation atomically with their result. Data URI or raw base64; never duplicated inside result. Screenshot pixels are not persisted in idempotency replay records.

frame_idstring uuid nullable

Accepted post-action external observation identity. Use it as the next action's precondition_frame_id.

observation_availableboolean nullable

Whether screenshot pixels are present in this response. An idempotent replay may retain frame_id while returning screenshot=null and observation_available=false.

request_idstring required