API reference / Workers and bridges
Renew job authorization
Use the parent key and original workerId.
/api/v1/worker/jobs/{jobId}/heartbeatAuthorization
worker:run; owning key and workerIdSend 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/worker/jobs/job_123/heartbeat' \
--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
{
"cancel": false
}Path parameters
jobIdstringrequiredJob ID returned by Schedule a job or List jobs, owned by the current key.
"job_123"Validation pattern
^[A-Za-z0-9._:-]+$Request body application/json
workerIdstringrequiredStable identifier for this worker process. Reuse it for claim, heartbeat and completion calls.
"worker-01"Validation pattern
^[A-Za-z0-9._:-]+$Unknown fields are rejected.
Behavior and limits
Use the parent key and original workerId. Returns cancel:true for absent/expired leases, cancellation or a passed deadline. Stop the process when true or when renewal fails. Otherwise extends the lease and child-token expiry by 15 seconds, capped at the job deadline and parent expiry when set. It also extends still-active, unclosed sessions owned by that child key to the same finite expiry. It never revives an expired or released session. No-expiry parent keys still produce short-lived child credentials and finite job leases. The supplied CLI heartbeats every 4 seconds with each HTTP call bounded to 5 seconds.
Only unclosed child sessions whose expiry is still in the future are renewed. Released or expired sessions require a new acquire call.
Response 200
JobHeartbeat · application/json
cancelbooleanalways presentWhen true, stop the child agent and report cancellation; do not continue under an expired lease.
falseErrors
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.
