API reference / Workers and bridges
Register a bridge and claim one action
Poll with a stable workerId and truthful capabilities.
/api/v1/worker/bridge/claimAuthorization
worker:run + device grantSend 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/bridge/claim' \
--header "Authorization: Bearer $FLEETDECK_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"workerId": "bridge-01",
"deviceId": "device_123",
"capabilities": {
"backend": "adb",
"tools": [
"screenshot",
"inspect",
"apps",
"tap",
"double_tap",
"long_press",
"swipe",
"text",
"key",
"button",
"open_url",
"launch_app",
"kill_app"
]
}
}'Replace example IDs with returned values. Read credentials from your private environment.
Response examples
{
"action": {
"id": "action_123",
"command": {
"type": "tap",
"x": 0.5,
"y": 0.6
},
"deadline": "2030-01-01T10:00:00.000Z"
}
}Request body application/json
workerIdstringrequiredStable identifier for this worker process. Reuse it for claim, heartbeat and completion calls.
"bridge-01"Validation pattern
^[A-Za-z0-9._:-]+$deviceIdstringrequiredExact device ID from List devices. The current key must grant access to this phone.
"device_123"Validation pattern
^[A-Za-z0-9._:-]+$capabilitiesobjectrequiredCurrently advertised commands, native extensions and limitations.
View child fields
backendstringrequiredActive driver route, or the native backend reported by a registering bridge.
"adb"toolsstring[]requiredCommand names supported by this device or advertised by this bridge.
nativeToolsany JSON[]optionalDiscovered native tool descriptors. Follow each inputSchema; native coordinates may use different units.
Unknown fields are rejected.
Unknown fields are rejected.
Behavior and limits
Poll with a stable workerId and truthful capabilities. backend is at most 40 characters, tools contains up to 128 strings (128 characters each); nativeTools contains up to 128 discovered descriptors. Registration stays fresh for 15 seconds. Another fresh bridge gets BRIDGE_BUSY. Returns action:null when idle or an action with a 25-second execution deadline and 30-second lease. Execute it at most once; there is no action-lease heartbeat.
Response 200
BridgeClaim · application/json
actionobject | nullalways presentClaimed action, or null when no eligible action is queued.
View child fields
idstringalways presentUnique identifier of this resource. Use the returned value in subsequent requests.
"action_123"Validation pattern
^[A-Za-z0-9._:-]+$commandobjectalways presentOne strict action payload, selected by its type. Unknown fields are rejected.
View variants
Choose one action type. Each payload has its own required fields.
deadlinestringalways presentExecution deadline for this claimed bridge action. No action heartbeat is available.
"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 ↗409BRIDGE_BUSYAnother authorized bridge was seen for this device within 15 seconds.
Recovery: Stop the duplicate bridge or wait until the previous registration is stale. Keep worker IDs stable.
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.
