Devices
The devices bound to your account, their push tokens and the aggregated dispatch inbox.
There is no explicit registration call: a device is created the first time its x-codai-device UUID appears on a sessions request. These endpoints manage what exists and let a device pull everything queued for it in one call.
Authorization
bearerAuth A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by /v1/realtime.
In: header
Header Parameters
Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.
length <= 128Response Body
application/json
application/json
application/json
curl -X GET "https://example.com/v1/devices"{ "devices": [ { "id": "2b6d8c1e-4f3a-4e9b-9c0d-7a1e5f6b8c2d", "name": "Pixel 9 Pro", "platform": "android", "capabilities": [ "terminal", "fs", "voice" ], "has_push_token": true, "lastSeenAt": "2026-09-23T08:41:12.000Z", "createdAt": "2026-09-01T10:00:00.000Z" } ]}Authorization
bearerAuth A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by /v1/realtime.
In: header
Path Parameters
Device UUID (the value you send as x-codai-device).
uuidHeader Parameters
Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.
length <= 128Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
At least one of the two fields is required.
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X PATCH "https://example.com/v1/devices/497f6eca-6276-4993-bfeb-53cbbbba6f08" \ -H "Content-Type: application/json" \ -d '{}'{ "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string", "platform": "android", "capabilities": [ "string" ], "has_push_token": true, "lastSeenAt": "2019-08-24T14:15:22Z"}Authorization
bearerAuth A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by /v1/realtime.
In: header
Path Parameters
Device UUID.
uuidHeader Parameters
Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.
length <= 128Response Body
application/json
application/json
application/json
application/json
application/json
curl -X DELETE "https://example.com/v1/devices/497f6eca-6276-4993-bfeb-53cbbbba6f08"{ "deleted": true, "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"}Authorization
bearerAuth A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by /v1/realtime.
In: header
Query Parameters
Max controls returned in total. Default 200, max 500.
0 <= value <= 500200Header Parameters
Stable device UUID. Registers the device on first use (name/platform from x-codai-device-name / x-codai-device-platform) and selects the shared-sessions protocol.
uuidHuman-readable device name used when the device is first registered (truncated to 120 chars).
length <= 120Platform recorded on first registration; unknown values become agent.
Value in
- "android"
- "ios"
- "web"
- "desktop"
- "cli"
- "agent"
Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.
length <= 128Response Body
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/v1/devices/me/dispatch" \ -H "x-codai-device: 497f6eca-6276-4993-bfeb-53cbbbba6f08"{ "device_id": "3bafab7b-4400-4bcf-8e6e-09f954699940", "sessions": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "session_key": "string", "title": "string", "controls": [ { "id": "string", "kind": "send", "text": "string", "turn_id": "string", "ask_id": "string", "from_device_id": "10624cda-85b4-412c-80da-8ce165bfd5b0", "target_device_id": "12785743-1d27-41cd-88a7-0ac66360e3d6", "seq": 0, "applied": true, "created_at": "2019-08-24T14:15:22Z" } ] } ]}