Sessions

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

Every call carries x-codai-device (a stable UUID) — that header is what selects protocol v2 and registers the device. One executor holds the lease; viewers and editors send controls; everyone reads the same event log. The protocol itself is specified in the sessions section.

POST

/v1/sessions

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

Request Body

application/json

body

session_key?string

Client-chosen stable key; a random UUID when omitted. A server UUID of an existing readable session resolves to that session.

Length1 <= length <= 256

title?string

Lengthlength <= 500

e2e?boolean

Mark payloads as end-to-end encrypted.

Defaultfalse

stub?boolean

Create a title-only stub (no events yet); viewers request the transcript with a hydrate control.

Defaultfalse

Response Body

A session with this session_key (or server id) already exists; returned unchanged.

application/json

response

A shared session as returned by create/patch and embedded in list/detail.

id*string

Server-assigned id.

Formatuuid

session_key*string

Client-chosen stable key, unique per owner.

owner_user_id*string

Formatuuid

title*string

Lengthlength <= 500

created_at*string

Formatdate-time

last_event_at*string

Bumped on every stored event.

Formatdate-time

last_seq*integer

Highest event seq; 0 for an empty session.

Range0 <= value

executor_device_id*string

Mirror of the lease holder; may be stale until the next lease write.

Formatuuid

lease_expires_at*string

Formatdate-time

e2e*boolean

Payloads are end-to-end encrypted client-side.

archived*boolean

stub*boolean

Title-only mirror without events yet; cleared by the first appended event batch.

Example Request

curl -X POST 'https://ai.codai.ro/v1/sessions' \
  -H 'x-codai-device: 497f6eca-6276-4993-bfeb-53cbbbba6f08' \
  -H 'Content-Type: application/json' \
  -d '{}'

Example Request

curl -X POST 'https://ai.codai.ro/v1/sessions' \  -H 'x-codai-device: 497f6eca-6276-4993-bfeb-53cbbbba6f08' \  -H 'Content-Type: application/json' \  -d '{}'

Example ResponseSchema

{
  "id": "3f7a4c1e-9b2d-4e8f-a1b6-5c0d7e2f9a34",
  "session_key": "desktop-2026-09-23-main",
  "owner_user_id": "65139110-7c3c-4777-b692-80c218be3b9d",
  "title": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "last_event_at": "2019-08-24T14:15:22Z",
  "last_seq": 0,
  "executor_device_id": "4a403d11-3f52-4f9c-8024-3e4b6ac6da4c",
  "lease_expires_at": "2019-08-24T14:15:22Z",
  "e2e": true,
  "archived": true,
  "stub": true
}

{  "id": "3f7a4c1e-9b2d-4e8f-a1b6-5c0d7e2f9a34",  "session_key": "desktop-2026-09-23-main",  "owner_user_id": "65139110-7c3c-4777-b692-80c218be3b9d",  "title": "string",  "created_at": "2019-08-24T14:15:22Z",  "last_event_at": "2019-08-24T14:15:22Z",  "last_seq": 0,  "executor_device_id": "4a403d11-3f52-4f9c-8024-3e4b6ac6da4c",  "lease_expires_at": "2019-08-24T14:15:22Z",  "e2e": true,  "archived": true,  "stub": true}

GET

/v1/sessions

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 rows per list (own and shared are capped separately). Default 50, max 200.

Range0 <= value <= 200

Default50

archived?string

Include archived sessions when 1 or true.

Value in"0""1""true""false"

v?"2"

Force protocol v2 without the device header. Only 2 is meaningful.

Value in"2"

Header Parameters

Response Body

Own sessions first, then shared ones, each ordered by last_event_at descending.

application/json

response

sessions*array<>

Example Request

curl -X GET 'https://ai.codai.ro/v1/sessions' \
  -H 'x-codai-device: 497f6eca-6276-4993-bfeb-53cbbbba6f08'

Example Request

curl -X GET 'https://ai.codai.ro/v1/sessions' \  -H 'x-codai-device: 497f6eca-6276-4993-bfeb-53cbbbba6f08'

Example ResponseSchema

{
  "sessions": [
    {
      "id": "3f7a4c1e-9b2d-4e8f-a1b6-5c0d7e2f9a34",
      "session_key": "desktop-2026-09-23-main",
      "owner_user_id": "65139110-7c3c-4777-b692-80c218be3b9d",
      "title": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "last_event_at": "2019-08-24T14:15:22Z",
      "last_seq": 0,
      "executor_device_id": "4a403d11-3f52-4f9c-8024-3e4b6ac6da4c",
      "lease_expires_at": "2019-08-24T14:15:22Z",
      "e2e": true,
      "archived": true,
      "stub": true,
      "role": "viewer",
      "presence_count": 0
    }
  ]
}

{  "sessions": [    {      "id": "3f7a4c1e-9b2d-4e8f-a1b6-5c0d7e2f9a34",      "session_key": "desktop-2026-09-23-main",      "owner_user_id": "65139110-7c3c-4777-b692-80c218be3b9d",      "title": "string",      "created_at": "2019-08-24T14:15:22Z",      "last_event_at": "2019-08-24T14:15:22Z",      "last_seq": 0,      "executor_device_id": "4a403d11-3f52-4f9c-8024-3e4b6ac6da4c",      "lease_expires_at": "2019-08-24T14:15:22Z",      "e2e": true,      "archived": true,      "stub": true,      "role": "viewer",      "presence_count": 0    }  ]}

GET

/v1/sessions/{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

Server UUID of the session OR its client session_key. Own sessions win on session_key collisions.

Lengthlength <= 256

Query Parameters

v?"2"

Force protocol v2 without the device header. Only 2 is meaningful.

Value in"2"

Header Parameters

Response Body

Session detail.

application/json

response

A shared session as returned by create/patch and embedded in list/detail.

id*string

Server-assigned id.

Formatuuid

session_key*string

Client-chosen stable key, unique per owner.

owner_user_id*string

Formatuuid

title*string

Lengthlength <= 500

created_at*string

Formatdate-time

last_event_at*string

Bumped on every stored event.

Formatdate-time

last_seq*integer

Highest event seq; 0 for an empty session.

Range0 <= value

executor_device_id*string

Mirror of the lease holder; may be stale until the next lease write.

Formatuuid

lease_expires_at*string

Formatdate-time

e2e*boolean

Payloads are end-to-end encrypted client-side.

archived*boolean

stub*boolean

Title-only mirror without events yet; cleared by the first appended event batch.

role*SessionRole

Role of a principal on a session; owner ≥ editor ≥ viewer.

Value in"viewer""editor""owner"

members*array<>

lease*|null

presence*array<>

Example Request

curl -X GET 'https://ai.codai.ro/v1/sessions/3f7a4c1e-9b2d-4e8f-a1b6-5c0d7e2f9a34' \
  -H 'x-codai-device: 497f6eca-6276-4993-bfeb-53cbbbba6f08'

Example Request

curl -X GET 'https://ai.codai.ro/v1/sessions/3f7a4c1e-9b2d-4e8f-a1b6-5c0d7e2f9a34' \  -H 'x-codai-device: 497f6eca-6276-4993-bfeb-53cbbbba6f08'

Example ResponseSchema

{
  "id": "3f7a4c1e-9b2d-4e8f-a1b6-5c0d7e2f9a34",
  "session_key": "desktop-2026-09-23-main",
  "owner_user_id": "65139110-7c3c-4777-b692-80c218be3b9d",
  "title": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "last_event_at": "2019-08-24T14:15:22Z",
  "last_seq": 0,
  "executor_device_id": "4a403d11-3f52-4f9c-8024-3e4b6ac6da4c",
  "lease_expires_at": "2019-08-24T14:15:22Z",
  "e2e": true,
  "archived": true,
  "stub": true,
  "role": "viewer",
  "members": [
    {
      "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
      "role": "viewer",
      "remote": true,
      "devices": [
        {
          "device_id": "3bafab7b-4400-4bcf-8e6e-09f954699940",
          "name": "string",
          "platform": "android",
          "last_seen_at": "2019-08-24T14:15:22Z",
          "remote": true
        }
      ]
    }
  ],
  "lease": {
    "device_id": "3bafab7b-4400-4bcf-8e6e-09f954699940",
    "expires_at": "2019-08-24T14:15:22Z"
  },
  "presence": [
    {
      "device_id": "3bafab7b-4400-4bcf-8e6e-09f954699940",
      "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
      "role": "viewer",
      "executor": true,
      "last_seen": 1758614400000,
      "driving": true,
      "remote": true
    }
  ]
}

{  "id": "3f7a4c1e-9b2d-4e8f-a1b6-5c0d7e2f9a34",  "session_key": "desktop-2026-09-23-main",  "owner_user_id": "65139110-7c3c-4777-b692-80c218be3b9d",  "title": "string",  "created_at": "2019-08-24T14:15:22Z",  "last_event_at": "2019-08-24T14:15:22Z",  "last_seq": 0,  "executor_device_id": "4a403d11-3f52-4f9c-8024-3e4b6ac6da4c",  "lease_expires_at": "2019-08-24T14:15:22Z",  "e2e": true,  "archived": true,  "stub": true,  "role": "viewer",  "members": [    {      "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",      "role": "viewer",      "remote": true,      "devices": [        {          "device_id": "3bafab7b-4400-4bcf-8e6e-09f954699940",          "name": "string",          "platform": "android",          "last_seen_at": "2019-08-24T14:15:22Z",          "remote": true        }      ]    }  ],  "lease": {    "device_id": "3bafab7b-4400-4bcf-8e6e-09f954699940",    "expires_at": "2019-08-24T14:15:22Z"  },  "presence": [    {      "device_id": "3bafab7b-4400-4bcf-8e6e-09f954699940",      "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",      "role": "viewer",      "executor": true,      "last_seen": 1758614400000,      "driving": true,      "remote": true    }  ]}

PATCH

/v1/sessions/{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

Server UUID of the session OR its client session_key. Own sessions win on session_key collisions.

Lengthlength <= 256

Header Parameters

Request Body

application/json

body

At least one of title / archived is required.

title?string

New title, or null to clear it.

Lengthlength <= 500

archived?boolean

Response Body

The updated session.

application/json

response

A shared session as returned by create/patch and embedded in list/detail.

id*string

Server-assigned id.

Formatuuid

session_key*string

Client-chosen stable key, unique per owner.

owner_user_id*string

Formatuuid

title*string

Lengthlength <= 500

created_at*string

Formatdate-time

last_event_at*string

Bumped on every stored event.

Formatdate-time

last_seq*integer

Highest event seq; 0 for an empty session.

Range0 <= value

executor_device_id*string

Mirror of the lease holder; may be stale until the next lease write.

Formatuuid

lease_expires_at*string

Formatdate-time

e2e*boolean

Payloads are end-to-end encrypted client-side.

archived*boolean

stub*boolean

Title-only mirror without events yet; cleared by the first appended event batch.

Example Request

curl -X PATCH 'https://ai.codai.ro/v1/sessions/3f7a4c1e-9b2d-4e8f-a1b6-5c0d7e2f9a34' \
  -H 'x-codai-device: 497f6eca-6276-4993-bfeb-53cbbbba6f08' \
  -H 'Content-Type: application/json' \
  -d '{}'

Example Request

curl -X PATCH 'https://ai.codai.ro/v1/sessions/3f7a4c1e-9b2d-4e8f-a1b6-5c0d7e2f9a34' \  -H 'x-codai-device: 497f6eca-6276-4993-bfeb-53cbbbba6f08' \  -H 'Content-Type: application/json' \  -d '{}'

Example ResponseSchema

{
  "id": "3f7a4c1e-9b2d-4e8f-a1b6-5c0d7e2f9a34",
  "session_key": "desktop-2026-09-23-main",
  "owner_user_id": "65139110-7c3c-4777-b692-80c218be3b9d",
  "title": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "last_event_at": "2019-08-24T14:15:22Z",
  "last_seq": 0,
  "executor_device_id": "4a403d11-3f52-4f9c-8024-3e4b6ac6da4c",
  "lease_expires_at": "2019-08-24T14:15:22Z",
  "e2e": true,
  "archived": true,
  "stub": true
}

{  "id": "3f7a4c1e-9b2d-4e8f-a1b6-5c0d7e2f9a34",  "session_key": "desktop-2026-09-23-main",  "owner_user_id": "65139110-7c3c-4777-b692-80c218be3b9d",  "title": "string",  "created_at": "2019-08-24T14:15:22Z",  "last_event_at": "2019-08-24T14:15:22Z",  "last_seq": 0,  "executor_device_id": "4a403d11-3f52-4f9c-8024-3e4b6ac6da4c",  "lease_expires_at": "2019-08-24T14:15:22Z",  "e2e": true,  "archived": true,  "stub": true}

DELETE

/v1/sessions/{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

Server UUID of the session OR its client session_key. Own sessions win on session_key collisions.

Lengthlength <= 256

Header Parameters

Response Body

Deleted.

application/json

response

deleted*true

Value intrue

id*string

Server id of the deleted session.

Formatuuid

Example Request

curl -X DELETE 'https://ai.codai.ro/v1/sessions/3f7a4c1e-9b2d-4e8f-a1b6-5c0d7e2f9a34' \
  -H 'x-codai-device: 497f6eca-6276-4993-bfeb-53cbbbba6f08'

Example Request

curl -X DELETE 'https://ai.codai.ro/v1/sessions/3f7a4c1e-9b2d-4e8f-a1b6-5c0d7e2f9a34' \  -H 'x-codai-device: 497f6eca-6276-4993-bfeb-53cbbbba6f08'

Example ResponseSchema

{
  "deleted": true,
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

{  "deleted": true,  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"}

GET

/v1/sessions/{id}/events

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

Server UUID of the session OR its client session_key. Own sessions win on session_key collisions.

Lengthlength <= 256

Query Parameters

after?integer

Return events with seq strictly greater than this value. Default 0.

Range0 <= value

Default0

limit?integer

Page size. Default 200, max 1000.

Range0 <= value <= 1000

Default200

Header Parameters

Response Body

One page of events.

application/json

response

last_seq*integer

Highest seq in the session at read time.

events*array<>

Example Request

curl -X GET 'https://ai.codai.ro/v1/sessions/3f7a4c1e-9b2d-4e8f-a1b6-5c0d7e2f9a34/events' \
  -H 'x-codai-device: 497f6eca-6276-4993-bfeb-53cbbbba6f08'

Example Request

curl -X GET 'https://ai.codai.ro/v1/sessions/3f7a4c1e-9b2d-4e8f-a1b6-5c0d7e2f9a34/events' \  -H 'x-codai-device: 497f6eca-6276-4993-bfeb-53cbbbba6f08'

Example ResponseSchema

{
  "last_seq": 42,
  "events": [
    {
      "seq": 1,
      "kind": "user_message",
      "ts": 1758614400000,
      "sender_device_id": "bc45c0f5-ada8-4820-b7a5-8dc052568462",
      "turn_id": "string",
      "client_event_id": "string",
      "payload": {}
    }
  ]
}

{  "last_seq": 42,  "events": [    {      "seq": 1,      "kind": "user_message",      "ts": 1758614400000,      "sender_device_id": "bc45c0f5-ada8-4820-b7a5-8dc052568462",      "turn_id": "string",      "client_event_id": "string",      "payload": {}    }  ]}

POST

/v1/sessions/{id}/events

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

Server UUID of the session OR its client session_key. Own sessions win on session_key collisions.

Lengthlength <= 256

Header Parameters

Request Body

application/json

body

events*array<>

Items1 <= items <= 200

expected_last_seq?integer

Optimistic check; mismatch → 409 seq_conflict.

Range0 <= value

Response Body

Batch processed (fresh rows stored, duplicates mapped to their existing seq).

application/json

response

last_seq*integer

Session last_seq after the append.

accepted*integer

Number of freshly stored events (duplicates excluded).

events*array<>

One entry per element of the batch, in order.

Example Request

curl -X POST 'https://ai.codai.ro/v1/sessions/3f7a4c1e-9b2d-4e8f-a1b6-5c0d7e2f9a34/events' \
  -H 'x-codai-device: 497f6eca-6276-4993-bfeb-53cbbbba6f08' \
  -H 'Content-Type: application/json' \
  -d '{
  "events": [
    {
      "kind": "string"
    }
  ]
}'

Example Request

curl -X POST 'https://ai.codai.ro/v1/sessions/3f7a4c1e-9b2d-4e8f-a1b6-5c0d7e2f9a34/events' \  -H 'x-codai-device: 497f6eca-6276-4993-bfeb-53cbbbba6f08' \  -H 'Content-Type: application/json' \  -d '{  "events": [    {      "kind": "string"    }  ]}'

Example ResponseSchema

{
  "last_seq": 0,
  "accepted": 0,
  "events": [
    {
      "client_event_id": "string",
      "seq": 0
    }
  ]
}

{  "last_seq": 0,  "accepted": 0,  "events": [    {      "client_event_id": "string",      "seq": 0    }  ]}

GET

/v1/sessions/{id}/controls

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

Server UUID of the session OR its client session_key. Own sessions win on session_key collisions.

Lengthlength <= 256

Query Parameters

applied?string

Return applied (1/true) instead of pending controls. Default pending.

Value in"0""1""true""false"

target?string

me (the calling device) or a device UUID; only controls dispatched at that device are returned.

Header Parameters

Response Body

Controls matching the filters.

application/json

response

controls*array<>

Example Request

curl -X GET 'https://ai.codai.ro/v1/sessions/3f7a4c1e-9b2d-4e8f-a1b6-5c0d7e2f9a34/controls' \
  -H 'x-codai-device: 497f6eca-6276-4993-bfeb-53cbbbba6f08'

Example Request

curl -X GET 'https://ai.codai.ro/v1/sessions/3f7a4c1e-9b2d-4e8f-a1b6-5c0d7e2f9a34/controls' \  -H 'x-codai-device: 497f6eca-6276-4993-bfeb-53cbbbba6f08'

Example ResponseSchema

{
  "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"
    }
  ]
}

{  "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"    }  ]}

POST

/v1/sessions/{id}/control

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

Server UUID of the session OR its client session_key. Own sessions win on session_key collisions.

Lengthlength <= 256

Header Parameters

Request Body

application/json

body

id*string

Client idempotency key, unique per session.

Length1 <= length <= 128

kind*SessionControlKind

Kind of control a non-executor can send to the executor. hydrate asks the executor to upload the transcript of a stub session (session owner only, like send).

Value in"send""answer""approve""deny""cancel""steer""inject""pause""resume""hydrate"

text?string

Message text for send / answer / steer / inject.

Lengthlength <= 100000

turn_id?string

Lengthlength <= 128

ask_id?string

Id of the question being answered / approved / denied.

Lengthlength <= 128

Response Body

A control with this id already exists in the session; nothing was written.

application/json

response

accepted*true

Value intrue

seq*integer

Seq of the echoed control event.

duplicate*boolean

true when the control id already existed.

Example Request

curl -X POST 'https://ai.codai.ro/v1/sessions/3f7a4c1e-9b2d-4e8f-a1b6-5c0d7e2f9a34/control' \
  -H 'x-codai-device: 497f6eca-6276-4993-bfeb-53cbbbba6f08' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "ctl-01J8Z7Q2K9",
  "kind": "send"
}'

Example Request

curl -X POST 'https://ai.codai.ro/v1/sessions/3f7a4c1e-9b2d-4e8f-a1b6-5c0d7e2f9a34/control' \  -H 'x-codai-device: 497f6eca-6276-4993-bfeb-53cbbbba6f08' \  -H 'Content-Type: application/json' \  -d '{  "id": "ctl-01J8Z7Q2K9",  "kind": "send"}'

Example ResponseSchema

{
  "accepted": true,
  "seq": 0,
  "duplicate": true
}

{  "accepted": true,  "seq": 0,  "duplicate": true}

POST

/v1/sessions/{id}/control/{cid}/applied

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

Server UUID of the session OR its client session_key. Own sessions win on session_key collisions.

Lengthlength <= 256

cid*string

The client-chosen control id.

Lengthlength <= 128

Header Parameters

Response Body

Marked applied.

application/json

response

id*string

The control id.

applied*true

Value intrue

Example Request

curl -X POST 'https://ai.codai.ro/v1/sessions/3f7a4c1e-9b2d-4e8f-a1b6-5c0d7e2f9a34/control/string/applied' \
  -H 'x-codai-device: 497f6eca-6276-4993-bfeb-53cbbbba6f08'

Example Request

curl -X POST 'https://ai.codai.ro/v1/sessions/3f7a4c1e-9b2d-4e8f-a1b6-5c0d7e2f9a34/control/string/applied' \  -H 'x-codai-device: 497f6eca-6276-4993-bfeb-53cbbbba6f08'

Example ResponseSchema

{
  "id": "string",
  "applied": true
}

{  "id": "string",  "applied": true}

POST

/v1/sessions/{id}/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).

Path Parameters

id*string

Server UUID of the session OR its client session_key. Own sessions win on session_key collisions.

Lengthlength <= 256

Header Parameters

Request Body

application/json

body

device_id*string

Target device; must belong to the session owner.

Formatuuid

mode?string

send runs text as a new turn on the target; open only opens the session there (handoff — text/turn_id ignored, no user turn).

Default"send"

Value in"send""open"

text?string

Prompt for the target. Required unless mode is open (400 otherwise).

Length1 <= length <= 100000

turn_id?string

Ignored when mode is open.

Lengthlength <= 128

control_id?string

Client idempotency key; dispatch:<uuid> is generated when absent.

Length1 <= length <= 128

Response Body

A control with this control_id already exists; nothing queued, no push sent.

application/json

response

control_id*string

seq*integer

target_device_id*string

Formatuuid

mode*string

The effective dispatch mode (send when the request omitted it).

Value in"send""open"

queued*true

Value intrue

pushed*boolean

true only when FCM accepted the wake message.

duplicate*boolean

push_reason?string

Why no push was delivered — no_push_token, no_token, auth_failed, network_error, unregistered (token cleared) or http_<status>. Absent on success.

Example Request

curl -X POST 'https://ai.codai.ro/v1/sessions/3f7a4c1e-9b2d-4e8f-a1b6-5c0d7e2f9a34/dispatch' \
  -H 'x-codai-device: 497f6eca-6276-4993-bfeb-53cbbbba6f08' \
  -H 'Content-Type: application/json' \
  -d '{
  "device_id": "3bafab7b-4400-4bcf-8e6e-09f954699940"
}'

Example Request

curl -X POST 'https://ai.codai.ro/v1/sessions/3f7a4c1e-9b2d-4e8f-a1b6-5c0d7e2f9a34/dispatch' \  -H 'x-codai-device: 497f6eca-6276-4993-bfeb-53cbbbba6f08' \  -H 'Content-Type: application/json' \  -d '{  "device_id": "3bafab7b-4400-4bcf-8e6e-09f954699940"}'

Example ResponseSchema

{
  "control_id": "dispatch:8c2e5f1a-7b3d-4c9e-a0f1-2d3e4f5a6b7c",
  "seq": 0,
  "target_device_id": "12785743-1d27-41cd-88a7-0ac66360e3d6",
  "mode": "send",
  "queued": true,
  "pushed": true,
  "duplicate": true,
  "push_reason": "no_push_token"
}

{  "control_id": "dispatch:8c2e5f1a-7b3d-4c9e-a0f1-2d3e4f5a6b7c",  "seq": 0,  "target_device_id": "12785743-1d27-41cd-88a7-0ac66360e3d6",  "mode": "send",  "queued": true,  "pushed": true,  "duplicate": true,  "push_reason": "no_push_token"}

POST

/v1/sessions/{id}/lease

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

Server UUID of the session OR its client session_key. Own sessions win on session_key collisions.

Lengthlength <= 256

Header Parameters

Request Body

application/json

body

device_id?string

Claim for this device instead of the one in x-codai-device (registered lazily under your account).

Formatuuid

force?boolean

Take over a live lease held by another device.

Defaultfalse

Response Body

Lease granted (or renewed for the same device).

application/json

response

session_id*string

Formatuuid

device_id*string

The lease holder.

Formatuuid

expires_at*string

Now + 30 s.

Formatdate-time

Example Request

curl -X POST 'https://ai.codai.ro/v1/sessions/3f7a4c1e-9b2d-4e8f-a1b6-5c0d7e2f9a34/lease' \
  -H 'x-codai-device: 497f6eca-6276-4993-bfeb-53cbbbba6f08' \
  -H 'Content-Type: application/json' \
  -d '{}'

Example Request

curl -X POST 'https://ai.codai.ro/v1/sessions/3f7a4c1e-9b2d-4e8f-a1b6-5c0d7e2f9a34/lease' \  -H 'x-codai-device: 497f6eca-6276-4993-bfeb-53cbbbba6f08' \  -H 'Content-Type: application/json' \  -d '{}'

Example ResponseSchema

{
  "session_id": "1ffd059c-17ea-40a8-8aef-70fd0307db82",
  "device_id": "3bafab7b-4400-4bcf-8e6e-09f954699940",
  "expires_at": "2019-08-24T14:15:22Z"
}

{  "session_id": "1ffd059c-17ea-40a8-8aef-70fd0307db82",  "device_id": "3bafab7b-4400-4bcf-8e6e-09f954699940",  "expires_at": "2019-08-24T14:15:22Z"}

PUT

/v1/sessions/{id}/lease

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

Server UUID of the session OR its client session_key. Own sessions win on session_key collisions.

Lengthlength <= 256

Header Parameters

Response Body

Lease renewed.

application/json

response

session_id*string

Formatuuid

device_id*string

The lease holder.

Formatuuid

expires_at*string

Now + 30 s.

Formatdate-time

Example Request

curl -X PUT 'https://ai.codai.ro/v1/sessions/3f7a4c1e-9b2d-4e8f-a1b6-5c0d7e2f9a34/lease' \
  -H 'x-codai-device: 497f6eca-6276-4993-bfeb-53cbbbba6f08'

Example Request

curl -X PUT 'https://ai.codai.ro/v1/sessions/3f7a4c1e-9b2d-4e8f-a1b6-5c0d7e2f9a34/lease' \  -H 'x-codai-device: 497f6eca-6276-4993-bfeb-53cbbbba6f08'

Example ResponseSchema

{
  "session_id": "1ffd059c-17ea-40a8-8aef-70fd0307db82",
  "device_id": "3bafab7b-4400-4bcf-8e6e-09f954699940",
  "expires_at": "2019-08-24T14:15:22Z"
}

{  "session_id": "1ffd059c-17ea-40a8-8aef-70fd0307db82",  "device_id": "3bafab7b-4400-4bcf-8e6e-09f954699940",  "expires_at": "2019-08-24T14:15:22Z"}

DELETE

/v1/sessions/{id}/lease

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

Server UUID of the session OR its client session_key. Own sessions win on session_key collisions.

Lengthlength <= 256

Header Parameters

Response Body

Release outcome.

application/json

response

session_id*string

Formatuuid

released*boolean

false when this device was not the holder.

Example Request

curl -X DELETE 'https://ai.codai.ro/v1/sessions/3f7a4c1e-9b2d-4e8f-a1b6-5c0d7e2f9a34/lease' \
  -H 'x-codai-device: 497f6eca-6276-4993-bfeb-53cbbbba6f08'

Example Request

curl -X DELETE 'https://ai.codai.ro/v1/sessions/3f7a4c1e-9b2d-4e8f-a1b6-5c0d7e2f9a34/lease' \  -H 'x-codai-device: 497f6eca-6276-4993-bfeb-53cbbbba6f08'

Example ResponseSchema

{
  "session_id": "1ffd059c-17ea-40a8-8aef-70fd0307db82",
  "released": true
}

{  "session_id": "1ffd059c-17ea-40a8-8aef-70fd0307db82",  "released": true}

GET

/v1/sessions/{id}/stream

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

Server UUID of the session OR its client session_key. Own sessions win on session_key collisions.

Lengthlength <= 256

Query Parameters

after?integer

Replay events with seq strictly greater than this before going live. Default 0 (full replay, capped at 1000).

Range0 <= value

Default0

Header Parameters

Response Body

Server-sent events; stays open up to 30 minutes.

response?stringtext/event-stream

Example Request

curl -X GET 'https://ai.codai.ro/v1/sessions/3f7a4c1e-9b2d-4e8f-a1b6-5c0d7e2f9a34/stream' \
  -H 'x-codai-device: 497f6eca-6276-4993-bfeb-53cbbbba6f08'

Example Request

curl -X GET 'https://ai.codai.ro/v1/sessions/3f7a4c1e-9b2d-4e8f-a1b6-5c0d7e2f9a34/stream' \  -H 'x-codai-device: 497f6eca-6276-4993-bfeb-53cbbbba6f08'

Example ResponseSchema

"string"

"string"

Sessions

AuthorizationCopy Anchor Link

Header ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

AuthorizationCopy Anchor Link

Query ParametersCopy Anchor Link

Header ParametersCopy Anchor Link

Response BodyCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Query ParametersCopy Anchor Link

Header ParametersCopy Anchor Link

Response BodyCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Header ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Header ParametersCopy Anchor Link

Response BodyCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Query ParametersCopy Anchor Link

Header ParametersCopy Anchor Link

Response BodyCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Header ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Query ParametersCopy Anchor Link

Header ParametersCopy Anchor Link

Response BodyCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Header ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Header ParametersCopy Anchor Link

Response BodyCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Header ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Header ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Header ParametersCopy Anchor Link

Response BodyCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Header ParametersCopy Anchor Link

Response BodyCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Query ParametersCopy Anchor Link

Header ParametersCopy Anchor Link

Response BodyCopy Anchor Link

Authorization

Header Parameters

Request Body

Response Body

Authorization

Query Parameters

Header Parameters

Response Body

Authorization

Path Parameters

Query Parameters

Header Parameters

Response Body

Authorization

Path Parameters

Header Parameters

Request Body

Response Body

Authorization

Path Parameters

Header Parameters

Response Body

Authorization

Path Parameters

Query Parameters

Header Parameters

Response Body

Authorization

Path Parameters

Header Parameters

Request Body

Response Body

Authorization

Path Parameters

Query Parameters

Header Parameters

Response Body

Authorization

Path Parameters

Header Parameters

Request Body

Response Body

Authorization

Path Parameters

Header Parameters

Response Body

Authorization

Path Parameters

Header Parameters

Request Body

Response Body

Authorization

Path Parameters

Header Parameters

Request Body

Response Body

Authorization

Path Parameters

Header Parameters

Response Body

Authorization

Path Parameters

Header Parameters

Response Body

Authorization

Path Parameters

Query Parameters

Header Parameters

Response Body