v1

latestOpenAPI 3.1.0MIT2026-08-0481194343.8 KB
machines

Submit a screenshot observation

DEVICE TOKEN ONLY. Upload one monotonically sequenced, one-frame PNG/JPEG. The encoded payload is limited to 10,485,760 base64 characters (after an optional exact PNG/JPEG data-URI prefix), and decoded dimensions to 320x240 through 3840x2160. The server verifies format, dimensions, and the optional submitted-byte SHA-256, then strips metadata and re-encodes; the response SHA-256 covers those normalized bytes and may differ. Identical sequence replays are safe; reusing a sequence with different bytes is 409. Live transport frames are encrypted, logically expire after 15 minutes, and are excluded from SSE, webhooks, ordinary logs, and ordinary durable run history. Separately, if a live BYOK Task, Workflow, or schedule uses a frame for a visual decision, the fail-closed pre-provider audit retains an exact model-input copy under the account-lifetime screenshot rules.

post/v1/machines/{machine_id}/observations

Request body

sequenceinteger required
media_type'image/png' | 'image/jpeg' required
sha256string nullable

Optional SHA-256 of the submitted decoded image bytes, before metadata stripping and server normalization.

widthinteger nullable
heightinteger nullable

width and height must be supplied together when either is present.

Response

Verified observation, including its canonical frame_id and decoded dimensions.

machine_idstring required
frame_idstring uuid required
sequenceinteger required
sha256string required

SHA-256 of the server-normalized PNG/JPEG bytes. Metadata removal and re-encoding mean this may differ from the request sha256.

widthinteger required
heightinteger required
received_atstring date-time required
fencing_tokeninteger required
request_idstring required