API reference / Sessions and actions
Renew a session
Sets expiration to now + 120 seconds, capped at key expiry when set, regardless of the initial TTL.
/api/v1/sessions/{sessionId}/heartbeatAuthorization
Same key that acquired the sessionSend 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/sessions/session_123/heartbeat' \
--header "Authorization: Bearer $FLEETDECK_API_KEY"Replace example IDs with returned values. Read credentials from your private environment.
Response examples
{
"id": "session_123",
"expiresAt": "2030-01-01T10:00:00.000Z"
}Path parameters
sessionIdstringrequiredSession ID returned by Acquire a session. Use the key that owns that session.
"session_123"Validation pattern
^[A-Za-z0-9._:-]+$Request body
This endpoint does not require a request body.
Behavior and limits
Sets expiration to now + 120 seconds, capped at key expiry when set, regardless of the initial TTL. Follow the returned expiresAt; job children need frequent session renewal as their worker renews the child token. Renew before expiry; an expired session cannot be revived. No request body.
Response 200
SessionHeartbeat · application/json
idstringalways presentUnique identifier of this resource. Use the returned value in subsequent requests.
"session_123"Validation pattern
^[A-Za-z0-9._:-]+$expiresAtstringalways presentUTC instant when this lease or credential expires. Read each renewal response for the current deadline.
"2030-01-01T10:00:00.000Z"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 ↗409SESSION_EXPIREDSession expired, was closed or belongs to another key.
Recovery: Read the original action if needed, acquire a new session and inspect before new input. Heartbeat before the returned expiresAt; temporary child keys can have much shorter sessions than 120 seconds.
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.
