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.
/api/v1/jobsAuthorization
jobs:write + 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/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
{
"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
deviceIdstringrequiredExact device ID from List devices. The current key must grant access to this phone.
"device_123"Validation pattern
^[A-Za-z0-9._:-]+$namestringrequiredName of the resource or operation. For commands with an enum, choose one of the listed values.
"Inspect phone"promptstringrequiredTask instructions passed to the external agent adapter. A worker must be running to execute them.
"Take a screenshot and describe the current screen. Do not change app state."scheduledAtstringrequiredFuture 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.
"2030-01-01T11:00:00+01:00"timezonestringrequiredValid IANA timezone. Metadata only; scheduledAt is the actual execution instant.
"Europe/Bratislava"deadlineSecondsintegeroptionalMaximum job runtime in seconds; the worker stops the child at the finite deadline.
900900Unknown 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 presentUnique identifier of this resource. Use the returned value in subsequent requests.
"job_123"Validation pattern
^[A-Za-z0-9._:-]+$deviceIdstringalways presentExact device ID from List devices. The current key must grant access to this phone.
"device_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.
"Inspect phone"scheduledAtstringalways presentFuture execution instant with an explicit UTC offset. Replace example timestamps with your intended schedule.
"2030-01-01T10:00:00.000Z"timezonestringalways presentIANA timezone metadata. scheduledAt remains the authoritative execution instant.
"Europe/Bratislava"statusstringalways presentCurrent state. A completed action means the driver finished; verify the intended screen or app effect separately.
"queued""running""completed""failed""cancelled""missed""interrupted"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.
cancelRequestedbooleanalways presentWhether cancellation has been requested. Physical effects already delivered are not undone.
falsesummarystring | nullalways presentWorker'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.
