FleetDeckDocs

API reference / Touch automations

Create a touch schedule

Schedules a saved sequence.

POST/api/v1/devices/{deviceId}/touch-schedules

Authorization

Bearer tokenjobs:write + devices:control

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/devices/device_123/touch-schedules' \
  --header "Authorization: Bearer $FLEETDECK_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Morning check-in",
  "sequenceId": "seq_123",
  "cron": "0 9 * * 1-5",
  "timezone": "Europe/Bratislava",
  "confirmed": true
}'

Replace example IDs with returned values. Read credentials from your private environment.

Response examples
200 · success
{
  "id": "schedule_123",
  "name": "Morning check-in",
  "sequenceId": "seq_123",
  "cron": "0 9 * * 1-5",
  "timezone": "Europe/Bratislava",
  "runAt": null,
  "failureEmail": null,
  "enabled": true,
  "nextRunAt": "2030-01-01T10:00:00.000Z",
  "createdAt": "2030-01-01T10:00:00.000Z",
  "warning": null
}

Path parameters

deviceIdstringrequired

Exact device ID from List devices. The current key must grant access to this phone.

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

Request body application/json

namestringrequired

Name of the resource or operation. For commands with an enum, choose one of the listed values.

min 1 charactersmax 120 characters
Example: "Morning check-in"
sequenceIdstringrequired
min 1 charactersmax 128 characters
Example: "seq_123"
Validation pattern^[A-Za-z0-9._:-]+$
librarybooleanoptional
cronstringoptional
min 1 charactersmax 128 characters
Example: "0 9 * * 1-5"
runAtstringoptional
date-time
timezonestringrequired

IANA timezone metadata. scheduledAt remains the authoritative execution instant.

min 1 charactersmax 100 characters
Example: "Europe/Bratislava"
confirmedbooleanrequired
Allowed:true
failureEmailstring | nulloptional
max 254 charactersemail

Unknown fields are rejected.

Behavior and limits

Schedules a saved sequence. Supply exactly one of cron (five numeric fields: minute hour day month weekday, evaluated in timezone) or runAt (one ISO instant with offset, 30 seconds to one year ahead). timezone is an IANA zone; never guess it. confirmed must be true, asserting the phone’s layout matches the recorded sequence. failureEmail, if set, must belong to a workspace member. Maximum 100 schedules per device. The schedule is user-owned and keeps running after this key is revoked or expires; delete it explicitly. warning describes overlap with another schedule, if any.

Response 200

TouchScheduleRecord · application/json

idstringalways present

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

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

Name of the resource or operation. For commands with an enum, choose one of the listed values.

Example: "Morning check-in"
sequenceIdstringalways present
Example: "seq_123"
cronstringalways present

Five-field cron, or empty for a one-time run

Example: "0 9 * * 1-5"
timezonestringalways present

IANA timezone metadata. scheduledAt remains the authoritative execution instant.

Example: "Europe/Bratislava"
runAtstring | nullalways present
date-time
failureEmailstring | nullalways present
enabledbooleanalways present
Example: true
nextRunAtstringalways present
date-time
Example: "2030-01-01T10:00:00.000Z"
createdAtstringalways present

UTC instant when the record was created.

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

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