FleetDeckDocs

API reference / Jobs

Schedule one agent task

scheduledAt must be a future ISO 8601 instant with a timezone offset, before key expiry when the key has one.

POST/api/v1/jobs

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/jobs' \
  --header "Authorization: Bearer $FLEETDECK_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "deviceId": "device_123",
  "name": "Inspect phone",
  "prompt": "Take a screenshot and describe the current screen. Do not change app state.",
  "scheduledAt": "2030-01-01T11:00:00+01:00",
  "timezone": "Europe/Bratislava",
  "deadlineSeconds": 900
}'

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

Response examples
200 · success
{
  "id": "job_123",
  "deviceId": "device_123",
  "name": "Inspect phone",
  "scheduledAt": "2030-01-01T10:00:00.000Z",
  "timezone": "Europe/Bratislava",
  "status": "queued",
  "startedAt": null,
  "finishedAt": null,
  "cancelRequested": false,
  "summary": null
}

Request body application/json

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._:-]+$
namestringrequired

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

min 1 charactersmax 120 characters
Example: "Inspect phone"
promptstringrequired

Task instructions passed to the external agent adapter. A worker must be running to execute them.

min 1 charactersmax 16,000 characters
Example: "Take a screenshot and describe the current screen. Do not change app state."
scheduledAtstringrequired

Future instant with UTC offset, strictly before key expiry when set. No-expiry keys have no key-expiry cutoff; jobs still use finite leases and deadlines. Example dates must be replaced with your actual future schedule.

date-time
Example: "2030-01-01T11:00:00+01:00"
timezonestringrequired

Valid IANA timezone. Metadata only; scheduledAt is the actual execution instant.

min 1 charactersmax 100 characters
Example: "Europe/Bratislava"
deadlineSecondsintegeroptional

Maximum job runtime in seconds; the worker stops the child at the finite deadline.

min 60max 3,600default 900
Example: 900

Unknown fields are rejected.

Behavior and limits

scheduledAt must be a future ISO 8601 instant with a timezone offset, before key expiry when the key has one. timezone is a valid IANA zone retained as intent; it does not recalculate that instant. Choose an actual future time instead of copying the illustrative date; expiring keys must remain valid at that time. A no-expiry key has no key-expiry scheduling cutoff, but each job still has a finite deadline and renewable lease. name 1..120 and prompt 1..16000 trimmed characters; deadlineSeconds 60..3600, default 900. This POST has no idempotency key. Keep an external worker running with this same key; FleetDeck does not host the model or wake a laptop.

Response 200

JobRecord · application/json

idstringalways present

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

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

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._:-]+$
namestringalways present

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

Example: "Inspect phone"
scheduledAtstringalways present

Future execution instant with an explicit UTC offset. Replace example timestamps with your intended schedule.

date-time
Example: "2030-01-01T10:00:00.000Z"
timezonestringalways present

IANA timezone metadata. scheduledAt remains the authoritative execution instant.

Example: "Europe/Bratislava"
statusstringalways present

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

Allowed:"queued""running""completed""failed""cancelled""missed""interrupted"
startedAtstring | nullalways present

UTC instant execution began, or null if it has not begun.

date-time
finishedAtstring | nullalways present

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

date-time
cancelRequestedbooleanalways present

Whether cancellation has been requested. Physical effects already delivered are not undone.

Example: false
summarystring | nullalways present

Worker's completion summary. It describes the process outcome, not independently verified app success.

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_TIMESchedule is in the past or at/after a configured key expiry.

Recovery: Choose a future instant with the correct UTC offset, before key expiry if set. A no-expiry key has no key-expiry cutoff; job deadlines and leases still apply.

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.