API reference / Touch automations
Run a saved sequence now
Queues the saved sequence on FleetDeck’s touch scheduler, which plays it within a few seconds with the same safety checks as scheduled runs (device access, entitlement, phone model, busy device).
/api/v1/devices/{deviceId}/sequence-runsAuthorization
devices:controlSend 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/devices/device_123/sequence-runs' \
--header "Authorization: Bearer $FLEETDECK_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"requestId": "run-inbox-001",
"sequenceId": "seq_123",
"library": false
}'Replace example IDs with returned values. Read credentials from your private environment.
Response examples
{
"requestId": "run-inbox-001",
"scheduleId": "schedule_456",
"sequenceId": "seq_123",
"existing": false,
"status": "queued",
"queuedAt": "2030-01-01T10:00:00.000Z",
"run": null
}Path parameters
deviceIdstringrequiredExact device ID from List devices. The current key must grant access to this phone.
"device_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.
"run-inbox-001"Validation pattern
^[A-Za-z0-9._:-]+$sequenceIdstringrequired"seq_123"Validation pattern
^[A-Za-z0-9._:-]+$librarybooleanoptionalfalsefalseUnknown fields are rejected.
Behavior and limits
Queues the saved sequence on FleetDeck’s touch scheduler, which plays it within a few seconds with the same safety checks as scheduled runs (device access, entitlement, phone model, busy device). requestId is required: repeating the same requestId returns the same run and its current status instead of starting another; a different sequenceId with that requestId is IDEMPOTENCY_CONFLICT. The phone must be online, the scheduler online, and the phone free: release your own automation session first. Poll this endpoint with the same body, or List touch runs filtered by scheduleId, for the outcome. completed means the steps were sent, not that the app reached a given state.
Response 200
SequenceRun · application/json
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.
"run-inbox-001"Validation pattern
^[A-Za-z0-9._:-]+$scheduleIdstringalways present"schedule_456"Validation pattern
^[A-Za-z0-9._:-]+$sequenceIdstringalways present"seq_123"existingbooleanalways presenttrue when this requestId was already used and the original run is returned
falsestatusstringalways presentCurrent state. A completed action means the driver finished; verify the intended screen or app effect separately.
"queued""running""completed""failed""cancelled""skipped""interrupted"queuedAtstring | nullalways present"2030-01-01T10:00:00.000Z"runobject | nullalways presentView child fields
idstringalways presentUnique identifier of this resource. Use the returned value in subsequent requests.
Validation pattern
^[A-Za-z0-9._:-]+$scheduleIdstringalways presentValidation pattern
^[A-Za-z0-9._:-]+$statusstringalways presentCurrent state. A completed action means the driver finished; verify the intended screen or app effect separately.
"running""completed""failed""cancelled""skipped""interrupted"scheduledAtstringalways presentFuture execution instant with an explicit UTC offset. Replace example timestamps with your intended schedule.
startedAtstring | nullalways presentUTC instant execution began, or null if it has not begun.
finishedAtstring | nullalways presentUTC instant execution ended, or null while no terminal outcome is recorded.
errorstring | nullalways presentHuman-readable failure explanation. Use code for programmatic handling.
notificationSentAtstring | nullalways presentnotificationAttemptsintegeralways presentdurationMsinteger | nullalways presentErrors
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 ↗409DEVICE_BUSYAnother automation session, touch run or in-flight action owns the phone.
Recovery: Wait for its release/expiry and any running lease. Coordinate operators; do not create parallel controls.
Full error reference ↗409DEVICE_OFFLINEThe phone is not connected, so a sequence cannot start.
Recovery: Bring the phone online (agent app running, network up), then retry with the same requestId.
Full error reference ↗503SCHEDULER_OFFLINEFleetDeck’s touch scheduler has not checked in recently, so a sequence run would not start.
Recovery: Retry later with the same requestId.
Full error reference ↗409MODEL_MISMATCHThe saved sequence was recorded on a different phone model.
Recovery: Use a sequence recorded on this phone model; coordinates do not transfer between models.
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 ↗409LIMITMaximum 50 active keys per user or 100 queued jobs per key.
Recovery: Revoke unused keys or cancel unnecessary queued jobs before creating more.
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 ↗Example error messages are illustrative. Match the code and HTTP status; do not depend on exact message wording.
