FleetDeckDocs

API reference / Sessions and actions

Submit one command

Send {requestId,command}.

POST/api/v1/sessions/{sessionId}/actions

Authorization

Bearer tokenCommand-specific device scope; same session key

Send Authorization: Bearer <FLEETDECK_API_KEY> with the scope above. The key must also grant access to the target device. Authentication guide ↗

Request example
Request · cURL
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
200 · success
{
  "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

sessionIdstringrequired

Session ID returned by Acquire a session. Use the key that owns that session.

min 1 charactersmax 128 characters
Example: "session_123"
Validation pattern^[A-Za-z0-9._:-]+$

Request body application/json

requestIdstringrequired

Your stable action identifier, unique within the session. Reusing it with the same command retrieves the existing action; changing the command causes IDEMPOTENCY_CONFLICT.

min 1 charactersmax 128 characters
Example: "tap-001"
Validation pattern^[A-Za-z0-9._:-]+$
commandobjectrequired

One strict action payload, selected by its type. Unknown fields are rejected.

View variants

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 present

Unique identifier of this resource. Use the returned value in subsequent requests.

min 1 charactersmax 128 characters
Example: "action_123"
Validation pattern^[A-Za-z0-9._:-]+$
requestIdstringalways present

Your stable action identifier, unique within the session. Reusing it with the same command retrieves the existing action; changing the command causes IDEMPOTENCY_CONFLICT.

min 1 charactersmax 128 characters
Example: "tap-001"
Validation pattern^[A-Za-z0-9._:-]+$
statusstringalways present

Current state. A completed action means the driver finished; verify the intended screen or app effect separately.

Allowed:"queued""running""completed""failed""unknown""cancelled"
kindstringalways present

Action type that produced this record.

Allowed:"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 present

UTC instant when the record was created.

date-time
Example: "2030-01-01T10:00:00.000Z"
finishedAtstring | nullalways present

UTC instant execution ended, or null while no terminal outcome is recorded.

date-time
Example: "2030-01-01T10:00:00.000Z"
resultany JSON | nullalways present

Driver-defined JSON or null. Known shapes are documented in ActionResult; native tool output may differ.

View child fields
statusstringoptional

Current state. A completed action means the driver finished; verify the intended screen or app effect separately.

Allowed:"submitted""applied""staged""imported"
verifiedbooleanoptional

Media import acknowledgement is not publication verification. Other input normally returns false.

Example: false
instructionstringoptional

Driver guidance for the next observation or recovery step.

Example: "Take a fresh screenshot to verify the intended effect before the next decision"
contentobject[]optional

Content blocks returned by the driver. Screenshot image blocks contain base64 image bytes.

View child fields
typestringalways present

Discriminator that selects the action or content shape.

Allowed:"image"
mimeTypestringalways present

MIME type of the returned image.

Allowed:"image/jpeg""image/png"
datastringalways present

Base64 image bytes, without a data URL prefix.

widthintegeroptional

Captured image width in pixels.

heightintegeroptional

Captured image height in pixels.

capturedAtstringoptional

UTC capture timestamp supplied by the relay.

date-time
coordinateSpacestringoptional

Coordinate convention for common FleetDeck actions. Normalized x/y values are relative to the current screen.

xmlstringoptional

ADB UI hierarchy XML; bounds use screen pixels.

treeany JSONoptional

WDA accessibility tree; shape varies by version.

screenobjectoptional

ADB {w,h} pixels; WDA {width,height} logical points.

packagesstring[]optional

Android package-name strings returned by ADB app inventory.

appsany JSON[]optional

Phone-agent-defined app entries. Entry fields depend on the agent version.

valuestringoptional

Plaintext clipboard value.

codestringoptional

Execution error code, distinct from an HTTP error.

errorstringoptional

Human-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.