FleetDeckDocs

API reference / Workers and bridges

Claim a due task

Returns job:null when no eligible task exists or the worker/device is busy.

POST/api/v1/worker/jobs/claim

Authorization

Bearer tokenworker:run; same key that created the job

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/worker/jobs/claim' \
  --header "Authorization: Bearer $FLEETDECK_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "workerId": "worker-01"
}'

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

Response examples
200 · success
{
  "job": {
    "id": "job_123",
    "deviceId": "device_123",
    "prompt": "Take a screenshot and describe the current screen.",
    "deadlineSeconds": 900,
    "scheduledAt": "2030-01-01T10:00:00.000Z",
    "token": "<ephemeral child token; never log>"
  }
}

Request body application/json

workerIdstringrequired

Stable identifier for this worker process. Reuse it for claim, heartbeat and completion calls.

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

Unknown fields are rejected.

Behavior and limits

Returns job:null when no eligible task exists or the worker/device is busy. A job more than 30 seconds late becomes missed when the worker next polls and is not replayed. A claimed job receives a 15-second lease and device-bound child token with only the parent’s device scopes. Treat token as a secret. Start the agent once and heartbeat using the parent key.

Response 200

JobClaim · application/json

jobobject | nullalways present

Claimed job with a private child credential, or null when no job can be claimed.

View child fields
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._:-]+$
promptstringalways present

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

Example: "Take a screenshot and describe the current screen."
deadlineSecondsintegeralways present

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

Example: 900
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"
tokenstringalways present

Secret ephemeral device-bound token. Pass privately to the child agent. Never log or persist in public evidence.

Example: "<ephemeral child token; never log>"

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