codai docs
API referenceGateway

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.

Agents list your devices through the MCP server tool devices_list (read-only; only has_push_token, never the raw push token).

GET
/v1/devices

Authorization

bearerAuth
headerAuthorizationBearer <codai_…>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by the media surfaces matching their scope (/v1/realtime, /v1/audio/*, /v1/embeddings).

Header Parameters

x-request-id?string

Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.

Lengthlength <= 128

Response Body

The caller's devices ordered by lastSeenAt descending.

application/json
  1. response
devices*array<>
Example Request
curl -X GET 'https://ai.codai.ro/v1/devices'
Example Response
{  "devices": [    {      "id": "2b6d8c1e-4f3a-4e9b-9c0d-7a1e5f6b8c2d",      "name": "Pixel 9 Pro",      "platform": "android",      "capabilities": [        "terminal",        "fs",        "voice"      ],      "has_push_token": true,      "app_version": "desktop/0.7.0",      "lastSeenAt": "2026-09-23T08:41:12.000Z",      "createdAt": "2026-09-01T10:00:00.000Z",      "online": true    }  ]}
PATCH
/v1/devices/{id}

Authorization

bearerAuth
headerAuthorizationBearer <codai_…>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by the media surfaces matching their scope (/v1/realtime, /v1/audio/*, /v1/embeddings).

Path Parameters

id*string

Device UUID (the value you send as x-codai-device).

Formatuuid

Header Parameters

x-request-id?string

Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.

Lengthlength <= 128

Request Body

application/json
  1. body

At least one of the two fields is required.

push_token?|

FCM registration token (opaque ASCII, trimmed). null clears it.

Length8 <= length <= 4096
capabilities?array<>

Replaces the whole capability list.

Itemsitems <= 64

Response Body

The updated device.

application/json
  1. response
id*string
Formatuuid
name*string
platform*DevicePlatform

Client platform; anything else sent in x-codai-device-platform is stored as agent.

Value in"android""ios""web""desktop""cli""agent"
capabilities*array<string>
has_push_token*boolean
lastSeenAt*string
Formatdate-time
Example Request
curl -X PATCH 'https://ai.codai.ro/v1/devices/497f6eca-6276-4993-bfeb-53cbbbba6f08' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "name": "string",  "platform": "android",  "capabilities": [    "string"  ],  "has_push_token": true,  "lastSeenAt": "2019-08-24T14:15:22Z"}
DELETE
/v1/devices/{id}

Authorization

bearerAuth
headerAuthorizationBearer <codai_…>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by the media surfaces matching their scope (/v1/realtime, /v1/audio/*, /v1/embeddings).

Path Parameters

id*string

Device UUID.

Formatuuid

Header Parameters

x-request-id?string

Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.

Lengthlength <= 128

Response Body

Deleted.

application/json
  1. response
deleted*true
Value intrue
id*string
Formatuuid
Example Request
curl -X DELETE 'https://ai.codai.ro/v1/devices/497f6eca-6276-4993-bfeb-53cbbbba6f08'
Example Response
{  "deleted": true,  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"}
GET
/v1/devices/me/dispatch

Authorization

bearerAuth
headerAuthorizationBearer <codai_…>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by the media surfaces matching their scope (/v1/realtime, /v1/audio/*, /v1/embeddings).

Query Parameters

limit?integer

Max controls returned in total. Default 200, max 500.

Range0 <= value <= 500
Default200

Header Parameters

x-codai-device*string

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.

Formatuuid
x-codai-device-name?string

Human-readable device name used when the device is first registered (truncated to 120 chars).

Lengthlength <= 120
x-codai-device-platform?string

Platform recorded on first registration; unknown values become agent.

Value in"android""ios""web""desktop""cli""agent"
x-request-id?string

Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.

Lengthlength <= 128

Response Body

Pending controls grouped by session (empty sessions when none).

application/json
  1. response
device_id*string

The calling device.

Formatuuid
sessions*array<>
Example Request
curl -X GET 'https://ai.codai.ro/v1/devices/me/dispatch' \  -H 'x-codai-device: 497f6eca-6276-4993-bfeb-53cbbbba6f08'
Example Response
{  "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",          "mode": "open",          "seq": 0,          "applied": true,          "created_at": "2019-08-24T14:15:22Z"        }      ]    }  ]}

Last updated:

Sessions

Shared-sessions protocol v2: event log, controls, executor lease, dispatch and the live SSE stream.

Vault

Zero-knowledge credentials vault: encrypted sync, agent broker, approvals and device keys.