API reference / Sessions and actions
Submit one command
Send {requestId,command}.
/api/v1/sessions/{sessionId}/actionsAuthorization
Command-specific device scope; same session keySend Authorization: Bearer <FLEETDECK_API_KEY> with the scope above. The key must also grant access to the target device. Authentication guide ↗
Request example
curl --request POST \
--url 'https://fleetdeck.co/api/v1/sessions/session_123/actions' \
--header "Authorization: Bearer $FLEETDECK_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"requestId": "tap-001",
"command": {
"type": "tap",
"x": 0.5,
"y": 0.6
}
}'Replace example IDs with returned values. Read credentials from your private environment.
Response examples
{
"id": "action_123",
"requestId": "tap-001",
"status": "completed",
"kind": "tap",
"createdAt": "2030-01-01T10:00:00.000Z",
"finishedAt": "2030-01-01T10:00:00.000Z",
"result": {
"status": "submitted",
"verified": false,
"instruction": "Take a fresh screenshot to verify the intended effect before the next decision"
}
}Path parameters
sessionIdstringrequiredSession ID returned by Acquire a session. Use the key that owns that session.
"session_123"Validation pattern
^[A-Za-z0-9._:-]+$Request body application/json
requestIdstringrequiredYour stable action identifier, unique within the session. Reusing it with the same command retrieves the existing action; changing the command causes IDEMPOTENCY_CONFLICT.
"tap-001"Validation pattern
^[A-Za-z0-9._:-]+$commandobjectrequiredOne strict action payload, selected by its type. Unknown fields are rejected.
View variants
Choose one action type. Each payload has its own required fields.
Unknown fields are rejected.
Behavior and limits
Send {requestId,command}. requestId identifies one intended action within this session. Identical retries return the existing action; changed input with the same ID conflicts. At most one queued/running action per session. Relay work generally finishes during the request; native bridge work returns queued and must be polled. HTTP 200 can contain failed or unknown status. See command payloads and recovery below.
Response 200
ActionRecord · application/json
idstringalways presentUnique identifier of this resource. Use the returned value in subsequent requests.
"action_123"Validation pattern
^[A-Za-z0-9._:-]+$requestIdstringalways presentYour stable action identifier, unique within the session. Reusing it with the same command retrieves the existing action; changing the command causes IDEMPOTENCY_CONFLICT.
"tap-001"Validation pattern
^[A-Za-z0-9._:-]+$statusstringalways presentCurrent state. A completed action means the driver finished; verify the intended screen or app effect separately.
"queued""running""completed""failed""unknown""cancelled"kindstringalways presentAction type that produced this record.
"screenshot""inspect""apps""tap""double_tap""long_press""swipe""text""key""button""open_url""launch_app""kill_app""clipboard_get""set_clipboard""push_media""media_chunk""native_tool"createdAtstringalways presentUTC instant when the record was created.
"2030-01-01T10:00:00.000Z"finishedAtstring | nullalways presentUTC instant execution ended, or null while no terminal outcome is recorded.
"2030-01-01T10:00:00.000Z"resultany JSON | nullalways presentDriver-defined JSON or null. Known shapes are documented in ActionResult; native tool output may differ.
View child fields
statusstringoptionalCurrent state. A completed action means the driver finished; verify the intended screen or app effect separately.
"submitted""applied""staged""imported"verifiedbooleanoptionalMedia import acknowledgement is not publication verification. Other input normally returns false.
falseinstructionstringoptionalDriver guidance for the next observation or recovery step.
"Take a fresh screenshot to verify the intended effect before the next decision"contentobject[]optionalContent blocks returned by the driver. Screenshot image blocks contain base64 image bytes.
View child fields
typestringalways presentDiscriminator that selects the action or content shape.
"image"mimeTypestringalways presentMIME type of the returned image.
"image/jpeg""image/png"datastringalways presentBase64 image bytes, without a data URL prefix.
widthintegeroptionalCaptured image width in pixels.
heightintegeroptionalCaptured image height in pixels.
capturedAtstringoptionalUTC capture timestamp supplied by the relay.
coordinateSpacestringoptionalCoordinate convention for common FleetDeck actions. Normalized x/y values are relative to the current screen.
xmlstringoptionalADB UI hierarchy XML; bounds use screen pixels.
treeany JSONoptionalWDA accessibility tree; shape varies by version.
screenobjectoptionalADB {w,h} pixels; WDA {width,height} logical points.
packagesstring[]optionalAndroid package-name strings returned by ADB app inventory.
appsany JSON[]optionalPhone-agent-defined app entries. Entry fields depend on the agent version.
valuestringoptionalPlaintext clipboard value.
codestringoptionalExecution error code, distinct from an HTTP error.
errorstringoptionalHuman-readable failure explanation. Use code for programmatic handling.
HTTP 200 confirms that the action record was returned. Check status and result for execution failures.
Errors
Expand a code for its recovery steps. Responses use error and code; validation errors also include issues.
401UNAUTHORIZEDMissing, malformed, expired or revoked credential; user verification/password state can also deny access.
Recovery: Use Authorization: Bearer with a valid scoped key. For dashboard routes, sign in. Job children require an active parent job and timely renewal.
Full error reference ↗403FORBIDDENRequired scope, device grant, account membership or worker identity is missing.
Recovery: Check the endpoint’s scopes, exact device, owning key and workerId. A different key cannot access the original key’s sessions or jobs.
Full error reference ↗404NOT_FOUNDUnknown route or resource unavailable to this caller.
Recovery: Check method/path and use returned IDs from this account/key. Do not guess IDs.
Full error reference ↗402PLAN_REQUIREDDevice account has no active entitlement.
Recovery: Restore an active device entitlement in the workspace before controlling it.
Full error reference ↗409SESSION_EXPIREDSession expired, was closed or belongs to another key.
Recovery: Read the original action if needed, acquire a new session and inspect before new input. Heartbeat before the returned expiresAt; temporary child keys can have much shorter sessions than 120 seconds.
Full error reference ↗409IDEMPOTENCY_CONFLICTrequestId already identifies a different command.
Recovery: Retrieve that original action. Reuse its exact command only for lookup/retry; use a new ID only for a newly intended action.
Full error reference ↗409ACTION_BUSYThis session has queued or running work.
Recovery: Poll the existing action to a terminal state before issuing another.
Full error reference ↗429RATE_LIMITAt most 120 new actions per session in a rolling minute.
Recovery: Pause until the window clears. Poll existing actions instead of resubmitting new work. No Retry-After header is currently supplied.
Full error reference ↗400INVALID_JSONMissing or malformed JSON.
Recovery: Use valid JSON. Body-less routes should omit the body; required routes need their documented object.
Full error reference ↗415CONTENT_TYPEA supplied JSON body lacks application/json content type.
Recovery: Set Content-Type: application/json; charset parameters are accepted.
Full error reference ↗413TOO_LARGERequest body exceeds its byte limit.
Recovery: Keep /api/v1 bodies at or below 3,000,000 bytes and key creation at or below 16,384. Use media_chunk for large files.
Full error reference ↗422VALIDATIONA field, type, bound or unknown property failed validation.
Recovery: Read issues[].path and issues[].message. Match the endpoint schema; strict objects reject extra fields.
Full error reference ↗500INTERNALUnexpected service error.
Recovery: Save nonsecret request context and time for support. Query action status before repeating a mutation; never assume it did not execute.
Full error reference ↗Execution errors inside HTTP 200
These codes live in result when the driver fails or cannot confirm delivery. Read action.status first.
Action result (driver 422)UNSUPPORTEDTool or parameter is unavailable on this transport, OS or phone-agent version.
Recovery: Recheck capabilities and driver limitations. Connect a suitable private native bridge or update the phone agent; verify actual hardware support.
Full error reference ↗Native driver 422UNSUPPORTED_TEXTADB input cannot encode the requested text.
Recovery: Use ASCII without literal %s, or a compatible relay/IME/native extension. The bridge stores UNSUPPORTED_TEXT as failed with its code; inspect the action result.
Full error reference ↗Action result (driver 422)MEDIA_IMPORT_FAILEDPhone rejected Photos/gallery import.
Recovery: Check complete file bytes, MIME, supported agent version and Photos/gallery permission. Inspect the gallery before retrying.
Full error reference ↗Action result (driver 502/503/504)DEVICE_UNAVAILABLEPhone or relay could not provide the requested operation.
Recovery: Check online state, capture/USB trust and relay connectivity. Wake/unlock locally if required; inspect state before repeating input.
Full error reference ↗Action result (driver 502/504)DELIVERY_UNKNOWNDelivery may have happened but its outcome is unconfirmed.
Recovery: Read the original action, then capture/inspect the phone. Do not blindly replay taps, uploads or publication.
Full error reference ↗Action result (driver 503)CONFIGURATIONServer relay transport configuration is invalid.
Recovery: Have the operator repair the relay URL; changing phone credentials will not correct server configuration.
Full error reference ↗Native driver 502/504NATIVE_FAILEDNative ADB/MCP execution failed or exceeded its deadline.
Recovery: Check ADB trust/serial or the native MCP service and connection. Inspect first; the command may already have had effects. The bridge preserves this code in an unknown action result.
Full error reference ↗Native driver 502/504WDA_FAILEDWDA rejected or timed out on an operation.
Recovery: Check WDA signing, running session and connectivity. A later action can re-establish a lost WDA session; inspect before new input. The bridge preserves this code in an unknown action result.
Full error reference ↗Example error messages are illustrative. Match the code and HTTP status; do not depend on exact message wording.
