API reference / Touch automations
Pause, resume or move a touch schedule
enabled:false pauses and asks a running occurrence to stop; enabled:true resumes.
/api/v1/devices/{deviceId}/touch-schedules/{scheduleId}Authorization
jobs:write (+ devices:control to resume or move)Send 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/touch-schedules/scheduleId' \
--header "Authorization: Bearer $FLEETDECK_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"enabled": false
}'Replace example IDs with returned values. Read credentials from your private environment.
Response examples
{
"id": "schedule_123",
"name": "Morning check-in",
"sequenceId": "seq_123",
"cron": "0 9 * * 1-5",
"timezone": "Europe/Bratislava",
"runAt": null,
"failureEmail": null,
"enabled": false,
"nextRunAt": "2030-01-01T10:00:00.000Z",
"createdAt": "2030-01-01T10:00:00.000Z",
"warning": 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._:-]+$scheduleIdstringrequiredExact identifier returned by this API, owned by the applicable key/account.
"schedule_123"Validation pattern
^[A-Za-z0-9._:-]+$Request body application/json
enabledbooleanoptionalfalserunAtstringoptionalconfirmedbooleanoptionaltruefailureEmailstring | nulloptionalUnknown fields are rejected.
Behavior and limits
enabled:false pauses and asks a running occurrence to stop; enabled:true resumes. runAt (with confirmed:true) moves a one-time run that has not run yet. failureEmail may be changed or set to null. All fields are optional.
Response 200
TouchScheduleRecord · application/json
idstringalways presentUnique identifier of this resource. Use the returned value in subsequent requests.
"schedule_123"Validation pattern
^[A-Za-z0-9._:-]+$namestringalways presentName of the resource or operation. For commands with an enum, choose one of the listed values.
"Morning check-in"sequenceIdstringalways present"seq_123"cronstringalways presentFive-field cron, or empty for a one-time run
"0 9 * * 1-5"timezonestringalways presentIANA timezone metadata. scheduledAt remains the authoritative execution instant.
"Europe/Bratislava"runAtstring | nullalways presentfailureEmailstring | nullalways presentenabledbooleanalways presentfalsenextRunAtstringalways present"2030-01-01T10:00:00.000Z"createdAtstringalways presentUTC instant when the record was created.
"2030-01-01T10:00:00.000Z"warningstring | 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 ↗400INVALID_SCHEDULEThe schedule time, cron, timezone, failure email or saved sequence was rejected by the touch scheduler (a foreign failure email returns HTTP 422 with this code).
Recovery: Use five numeric cron fields or a runAt 30 seconds to one year ahead, a valid IANA timezone, a workspace member email and a sequence saved on this phone.
Full error reference ↗409SCHEDULE_CONFLICTThe touch scheduler refused the change in the schedule’s current state (for example resuming is needed first, or the occurrence already ran).
Recovery: Read the message, list the schedules again and apply the change that matches the current state.
Full error reference ↗503UNAVAILABLETouch schedules are not configured on this server.
Recovery: Use the hosted FleetDeck API or configure the touch scheduler service.
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.
