Sesiuni

Protocolul de sesiuni partajate v2: jurnal de evenimente, controale, lease de executor, dispatch și stream-ul SSE live.

Fiecare apel poartă x-codai-device (un UUID stabil) — acel header e cel care selectează protocolul v2 și înregistrează dispozitivul. Un singur executor ține lease-ul; viewer-ii și editorii trimit controale; toți citesc același jurnal de evenimente. Protocolul în sine e specificat în secțiunea de sesiuni.

POST

/v1/sessions

Autorizare

bearerAuth

headerAutorizareBearer <codai_…>

O cheie API codai (prefix codai_). Tokenurile efemere de la POST /v1/tokens sunt acceptate doar de suprafețele media potrivite scope-ului lor (/v1/realtime, /v1/audio/*, /v1/embeddings).

Parametri header

Corpul cererii

application/json

body

session_key?string

Cheie stabilă aleasă de client; UUID aleator când lipsește. Un UUID de server al unei sesiuni existente pe care o poți citi se rezolvă la acea sesiune.

Lungime1 <= length <= 256

title?string

Lungimelength <= 500

e2e?boolean

Marchează payload-urile ca criptate end-to-end.

Implicitfalse

stub?boolean

Creează un stub doar cu titlu (încă fără evenimente); cei care o văd cer transcriptul cu un control hydrate.

Implicitfalse

Corpul răspunsului

Există deja o sesiune cu acest session_key (sau id de server); e întoarsă neschimbată.

application/json

response

O sesiune partajată, așa cum e întoarsă de create/patch și inclusă în listă/detalii.

id*string

Id atribuit de server.

Formatuuid

session_key*string

Cheie stabilă aleasă de client, unică per owner.

owner_user_id*string

Formatuuid

title*string

Lungimelength <= 500

created_at*string

Formatdate-time

last_event_at*string

Actualizat la fiecare eveniment stocat.

Formatdate-time

last_seq*integer

Cel mai mare seq de eveniment; 0 pentru o sesiune goală.

Interval0 <= value

executor_device_id*string

Oglinda deținătorului lease-ului; poate fi învechită până la următoarea scriere a lease-ului.

Formatuuid

lease_expires_at*string

Formatdate-time

e2e*boolean

Payload-urile sunt criptate end-to-end pe client.

archived*boolean

stub*boolean

Oglindă doar cu titlu, încă fără evenimente; se anulează la primul lot de evenimente adăugat.

Exemplu de cerere

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

Exemplu de cerere

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

Exemplu de răspunsSchemă

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

Autorizare

bearerAuth

headerAutorizareBearer <codai_…>

O cheie API codai (prefix codai_). Tokenurile efemere de la POST /v1/tokens sunt acceptate doar de suprafețele media potrivite scope-ului lor (/v1/realtime, /v1/audio/*, /v1/embeddings).

Parametri query

limit?integer

Număr maxim de rânduri per listă (proprii și partajate sunt limitate separat). Implicit 50, maxim 200.

Interval0 <= value <= 200

Implicit50

archived?string

Include sesiunile arhivate când e 1 sau true.

Valoare din"0""1""true""false"

v?"2"

Forțează protocolul v2 fără header-ul de dispozitiv. Doar 2 are sens.

Valoare din"2"

Parametri header

Corpul răspunsului

Sesiunile proprii mai întâi, apoi cele partajate, fiecare ordonate descrescător după last_event_at.

application/json

response

sessions*array<>

Exemplu de cerere

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

Exemplu de cerere

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

Exemplu de răspunsSchemă

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

Autorizare

bearerAuth

headerAutorizareBearer <codai_…>

O cheie API codai (prefix codai_). Tokenurile efemere de la POST /v1/tokens sunt acceptate doar de suprafețele media potrivite scope-ului lor (/v1/realtime, /v1/audio/*, /v1/embeddings).

Parametri de cale

id*string

UUID-ul de server al sesiunii SAU session_key-ul ei de client. La coliziuni de session_key, sesiunile proprii au prioritate.

Lungimelength <= 256

Parametri query

v?"2"

Forțează protocolul v2 fără header-ul de dispozitiv. Doar 2 are sens.

Valoare din"2"

Parametri header

Corpul răspunsului

Detaliile sesiunii.

application/json

response

O sesiune partajată, așa cum e întoarsă de create/patch și inclusă în listă/detalii.

id*string

Id atribuit de server.

Formatuuid

session_key*string

Cheie stabilă aleasă de client, unică per owner.

owner_user_id*string

Formatuuid

title*string

Lungimelength <= 500

created_at*string

Formatdate-time

last_event_at*string

Actualizat la fiecare eveniment stocat.

Formatdate-time

last_seq*integer

Cel mai mare seq de eveniment; 0 pentru o sesiune goală.

Interval0 <= value

executor_device_id*string

Oglinda deținătorului lease-ului; poate fi învechită până la următoarea scriere a lease-ului.

Formatuuid

lease_expires_at*string

Formatdate-time

e2e*boolean

Payload-urile sunt criptate end-to-end pe client.

archived*boolean

stub*boolean

Oglindă doar cu titlu, încă fără evenimente; se anulează la primul lot de evenimente adăugat.

role*SessionRole

Rolul unui principal pe o sesiune; owner ≥ editor ≥ viewer.

Valoare din"viewer""editor""owner"

members*array<>

lease*|null

presence*array<>

Exemplu de cerere

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

Exemplu de cerere

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

Exemplu de răspunsSchemă

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

Autorizare

bearerAuth

headerAutorizareBearer <codai_…>

O cheie API codai (prefix codai_). Tokenurile efemere de la POST /v1/tokens sunt acceptate doar de suprafețele media potrivite scope-ului lor (/v1/realtime, /v1/audio/*, /v1/embeddings).

Parametri de cale

id*string

UUID-ul de server al sesiunii SAU session_key-ul ei de client. La coliziuni de session_key, sesiunile proprii au prioritate.

Lungimelength <= 256

Parametri header

Corpul cererii

application/json

body

Cel puțin unul dintre title / archived e obligatoriu.

title?string

Titlul nou, sau null pentru a-l șterge.

Lungimelength <= 500

archived?boolean

Corpul răspunsului

Sesiunea actualizată.

application/json

response

O sesiune partajată, așa cum e întoarsă de create/patch și inclusă în listă/detalii.

id*string

Id atribuit de server.

Formatuuid

session_key*string

Cheie stabilă aleasă de client, unică per owner.

owner_user_id*string

Formatuuid

title*string

Lungimelength <= 500

created_at*string

Formatdate-time

last_event_at*string

Actualizat la fiecare eveniment stocat.

Formatdate-time

last_seq*integer

Cel mai mare seq de eveniment; 0 pentru o sesiune goală.

Interval0 <= value

executor_device_id*string

Oglinda deținătorului lease-ului; poate fi învechită până la următoarea scriere a lease-ului.

Formatuuid

lease_expires_at*string

Formatdate-time

e2e*boolean

Payload-urile sunt criptate end-to-end pe client.

archived*boolean

stub*boolean

Oglindă doar cu titlu, încă fără evenimente; se anulează la primul lot de evenimente adăugat.

Exemplu de cerere

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 '{}'

Exemplu de cerere

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 '{}'

Exemplu de răspunsSchemă

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

Autorizare

bearerAuth

headerAutorizareBearer <codai_…>

O cheie API codai (prefix codai_). Tokenurile efemere de la POST /v1/tokens sunt acceptate doar de suprafețele media potrivite scope-ului lor (/v1/realtime, /v1/audio/*, /v1/embeddings).

Parametri de cale

id*string

UUID-ul de server al sesiunii SAU session_key-ul ei de client. La coliziuni de session_key, sesiunile proprii au prioritate.

Lungimelength <= 256

Parametri header

Corpul răspunsului

Ștearsă.

application/json

response

deleted*true

Valoare dintrue

id*string

Id-ul de server al sesiunii șterse.

Formatuuid

Exemplu de cerere

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

Exemplu de cerere

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

Exemplu de răspunsSchemă

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

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

GET

/v1/sessions/{id}/events

Autorizare

bearerAuth

headerAutorizareBearer <codai_…>

O cheie API codai (prefix codai_). Tokenurile efemere de la POST /v1/tokens sunt acceptate doar de suprafețele media potrivite scope-ului lor (/v1/realtime, /v1/audio/*, /v1/embeddings).

Parametri de cale

id*string

UUID-ul de server al sesiunii SAU session_key-ul ei de client. La coliziuni de session_key, sesiunile proprii au prioritate.

Lungimelength <= 256

Parametri query

after?integer

Întoarce evenimentele cu seq strict mai mare decât această valoare. Implicit 0.

Interval0 <= value

Implicit0

limit?integer

Dimensiunea paginii. Implicit 200, maxim 1000.

Interval0 <= value <= 1000

Implicit200

Parametri header

Corpul răspunsului

O pagină de evenimente.

application/json

response

last_seq*integer

Cel mai mare seq din sesiune la momentul citirii.

events*array<>

Exemplu de cerere

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

Exemplu de cerere

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

Exemplu de răspunsSchemă

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

Autorizare

bearerAuth

headerAutorizareBearer <codai_…>

O cheie API codai (prefix codai_). Tokenurile efemere de la POST /v1/tokens sunt acceptate doar de suprafețele media potrivite scope-ului lor (/v1/realtime, /v1/audio/*, /v1/embeddings).

Parametri de cale

id*string

UUID-ul de server al sesiunii SAU session_key-ul ei de client. La coliziuni de session_key, sesiunile proprii au prioritate.

Lungimelength <= 256

Parametri header

Corpul cererii

application/json

body

events*array<>

Elemente1 <= items <= 200

expected_last_seq?integer

Verificare optimistă; nepotrivire → 409 seq_conflict.

Interval0 <= value

Corpul răspunsului

Lot procesat (rândurile noi stocate, duplicatele mapate la seq-ul existent).

application/json

response

last_seq*integer

last_seq-ul sesiunii după adăugare.

accepted*integer

Numărul de evenimente stocate acum (fără duplicate).

events*array<>

O intrare per element al lotului, în ordine.

Exemplu de cerere

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

Exemplu de cerere

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

Exemplu de răspunsSchemă

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

Autorizare

bearerAuth

headerAutorizareBearer <codai_…>

O cheie API codai (prefix codai_). Tokenurile efemere de la POST /v1/tokens sunt acceptate doar de suprafețele media potrivite scope-ului lor (/v1/realtime, /v1/audio/*, /v1/embeddings).

Parametri de cale

id*string

UUID-ul de server al sesiunii SAU session_key-ul ei de client. La coliziuni de session_key, sesiunile proprii au prioritate.

Lungimelength <= 256

Parametri query

applied?string

Întoarce controalele aplicate (1/true) în loc de cele în așteptare. Implicit cele în așteptare.

Valoare din"0""1""true""false"

target?string

me (dispozitivul apelant) sau un UUID de dispozitiv; se întorc doar controalele trimise către acel dispozitiv.

Parametri header

Corpul răspunsului

Controalele care corespund filtrelor.

application/json

response

controls*array<>

Exemplu de cerere

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

Exemplu de cerere

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

Exemplu de răspunsSchemă

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

Autorizare

bearerAuth

headerAutorizareBearer <codai_…>

O cheie API codai (prefix codai_). Tokenurile efemere de la POST /v1/tokens sunt acceptate doar de suprafețele media potrivite scope-ului lor (/v1/realtime, /v1/audio/*, /v1/embeddings).

Parametri de cale

id*string

UUID-ul de server al sesiunii SAU session_key-ul ei de client. La coliziuni de session_key, sesiunile proprii au prioritate.

Lungimelength <= 256

Parametri header

Corpul cererii

application/json

body

id*string

Cheie de idempotență a clientului, unică per sesiune.

Lungime1 <= length <= 128

kind*SessionControlKind

Tipul de control pe care un non-executor îl poate trimite executorului. hydrate cere executorului să încarce transcriptul unei sesiuni stub (doar owner-ul sesiunii, ca send).

Valoare din"send""answer""approve""deny""cancel""steer""inject""pause""resume""hydrate"

text?string

Textul mesajului pentru send / answer / steer / inject.

Lungimelength <= 100000

turn_id?string

Lungimelength <= 128

ask_id?string

Id-ul întrebării la care se răspunde / se aprobă / se refuză.

Lungimelength <= 128

Corpul răspunsului

Există deja un control cu acest id în sesiune; nu s-a scris nimic.

application/json

response

accepted*true

Valoare dintrue

seq*integer

Seq-ul evenimentului control reflectat.

duplicate*boolean

true când id-ul controlului exista deja.

Exemplu de cerere

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"
}'

Exemplu de cerere

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"}'

Exemplu de răspunsSchemă

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

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

POST

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

Autorizare

bearerAuth

headerAutorizareBearer <codai_…>

O cheie API codai (prefix codai_). Tokenurile efemere de la POST /v1/tokens sunt acceptate doar de suprafețele media potrivite scope-ului lor (/v1/realtime, /v1/audio/*, /v1/embeddings).

Parametri de cale

id*string

UUID-ul de server al sesiunii SAU session_key-ul ei de client. La coliziuni de session_key, sesiunile proprii au prioritate.

Lungimelength <= 256

cid*string

id-ul controlului, ales de client.

Lungimelength <= 128

Parametri header

Corpul răspunsului

Marcat ca aplicat.

application/json

response

id*string

Id-ul controlului.

applied*true

Valoare dintrue

Exemplu de cerere

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'

Exemplu de cerere

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'

Exemplu de răspunsSchemă

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

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

POST

/v1/sessions/{id}/dispatch

Autorizare

bearerAuth

headerAutorizareBearer <codai_…>

O cheie API codai (prefix codai_). Tokenurile efemere de la POST /v1/tokens sunt acceptate doar de suprafețele media potrivite scope-ului lor (/v1/realtime, /v1/audio/*, /v1/embeddings).

Parametri de cale

id*string

UUID-ul de server al sesiunii SAU session_key-ul ei de client. La coliziuni de session_key, sesiunile proprii au prioritate.

Lungimelength <= 256

Parametri header

Corpul cererii

application/json

body

device_id*string

Dispozitivul țintă; trebuie să aparțină owner-ului sesiunii.

Formatuuid

mode?string

send rulează text ca tură nouă pe țintă; open doar deschide sesiunea acolo (handoff — text/turn_id ignorate, nicio tură de utilizator).

Implicit"send"

Valoare din"send""open"

text?string

Prompt-ul pentru țintă. Obligatoriu, cu excepția mode = open (altfel 400).

Lungime1 <= length <= 100000

turn_id?string

Ignorat când mode e open.

Lungimelength <= 128

control_id?string

Cheie de idempotență a clientului; se generează dispatch:<uuid> când lipsește.

Lungime1 <= length <= 128

Corpul răspunsului

Există deja un control cu acest control_id; nimic pus în coadă, niciun push trimis.

application/json

response

control_id*string

seq*integer

target_device_id*string

Formatuuid

mode*string

Modul efectiv de dispatch (send când cererea l-a omis).

Valoare din"send""open"

queued*true

Valoare dintrue

pushed*boolean

true doar când FCM a acceptat mesajul de trezire.

duplicate*boolean

push_reason?string

De ce nu s-a livrat push — no_push_token, no_token, auth_failed, network_error, unregistered (token șters) sau http_<status>. Absent la succes.

Exemplu de cerere

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"
}'

Exemplu de cerere

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"}'

Exemplu de răspunsSchemă

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

Autorizare

bearerAuth

headerAutorizareBearer <codai_…>

O cheie API codai (prefix codai_). Tokenurile efemere de la POST /v1/tokens sunt acceptate doar de suprafețele media potrivite scope-ului lor (/v1/realtime, /v1/audio/*, /v1/embeddings).

Parametri de cale

id*string

UUID-ul de server al sesiunii SAU session_key-ul ei de client. La coliziuni de session_key, sesiunile proprii au prioritate.

Lungimelength <= 256

Parametri header

Corpul cererii

application/json

body

device_id?string

Revendică pentru acest dispozitiv în locul celui din x-codai-device (înregistrat lazy sub contul tău).

Formatuuid

force?boolean

Preia un lease live deținut de alt dispozitiv.

Implicitfalse

Corpul răspunsului

Lease acordat (sau reînnoit pentru același dispozitiv).

application/json

response

session_id*string

Formatuuid

device_id*string

Deținătorul lease-ului.

Formatuuid

expires_at*string

Acum + 30 s.

Formatdate-time

Exemplu de cerere

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 '{}'

Exemplu de cerere

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 '{}'

Exemplu de răspunsSchemă

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

Autorizare

bearerAuth

headerAutorizareBearer <codai_…>

O cheie API codai (prefix codai_). Tokenurile efemere de la POST /v1/tokens sunt acceptate doar de suprafețele media potrivite scope-ului lor (/v1/realtime, /v1/audio/*, /v1/embeddings).

Parametri de cale

id*string

UUID-ul de server al sesiunii SAU session_key-ul ei de client. La coliziuni de session_key, sesiunile proprii au prioritate.

Lungimelength <= 256

Parametri header

Corpul răspunsului

Lease reînnoit.

application/json

response

session_id*string

Formatuuid

device_id*string

Deținătorul lease-ului.

Formatuuid

expires_at*string

Acum + 30 s.

Formatdate-time

Exemplu de cerere

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

Exemplu de cerere

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

Exemplu de răspunsSchemă

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

Autorizare

bearerAuth

headerAutorizareBearer <codai_…>

O cheie API codai (prefix codai_). Tokenurile efemere de la POST /v1/tokens sunt acceptate doar de suprafețele media potrivite scope-ului lor (/v1/realtime, /v1/audio/*, /v1/embeddings).

Parametri de cale

id*string

UUID-ul de server al sesiunii SAU session_key-ul ei de client. La coliziuni de session_key, sesiunile proprii au prioritate.

Lungimelength <= 256

Parametri header

Corpul răspunsului

Rezultatul eliberării.

application/json

response

session_id*string

Formatuuid

released*boolean

false când acest dispozitiv nu era deținătorul.

Exemplu de cerere

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

Exemplu de cerere

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

Exemplu de răspunsSchemă

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

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

GET

/v1/sessions/{id}/stream

Autorizare

bearerAuth

headerAutorizareBearer <codai_…>

O cheie API codai (prefix codai_). Tokenurile efemere de la POST /v1/tokens sunt acceptate doar de suprafețele media potrivite scope-ului lor (/v1/realtime, /v1/audio/*, /v1/embeddings).

Parametri de cale

id*string

UUID-ul de server al sesiunii SAU session_key-ul ei de client. La coliziuni de session_key, sesiunile proprii au prioritate.

Lungimelength <= 256

Parametri query

after?integer

Redă evenimentele cu seq strict mai mare decât această valoare înainte de a trece live. Implicit 0 (redare completă, limitată la 1000).

Interval0 <= value

Implicit0

Parametri header

Corpul răspunsului

Server-sent events; rămâne deschis până la 30 de minute.

response?stringtext/event-stream

Exemplu de cerere

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

Exemplu de cerere

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

Exemplu de răspunsSchemă

"string"

"string"

Sesiuni

AutorizareCopiază linkul secțiunii

Parametri headerCopiază linkul secțiunii

Corpul cereriiCopiază linkul secțiunii

Corpul răspunsuluiCopiază linkul secțiunii

AutorizareCopiază linkul secțiunii

Parametri queryCopiază linkul secțiunii

Parametri headerCopiază linkul secțiunii

Corpul răspunsuluiCopiază linkul secțiunii

AutorizareCopiază linkul secțiunii

Parametri de caleCopiază linkul secțiunii

Parametri queryCopiază linkul secțiunii

Parametri headerCopiază linkul secțiunii

Corpul răspunsuluiCopiază linkul secțiunii

AutorizareCopiază linkul secțiunii

Parametri de caleCopiază linkul secțiunii

Parametri headerCopiază linkul secțiunii

Corpul cereriiCopiază linkul secțiunii

Corpul răspunsuluiCopiază linkul secțiunii

AutorizareCopiază linkul secțiunii

Parametri de caleCopiază linkul secțiunii

Parametri headerCopiază linkul secțiunii

Corpul răspunsuluiCopiază linkul secțiunii

AutorizareCopiază linkul secțiunii

Parametri de caleCopiază linkul secțiunii

Parametri queryCopiază linkul secțiunii

Parametri headerCopiază linkul secțiunii

Corpul răspunsuluiCopiază linkul secțiunii

AutorizareCopiază linkul secțiunii

Parametri de caleCopiază linkul secțiunii

Parametri headerCopiază linkul secțiunii

Corpul cereriiCopiază linkul secțiunii

Corpul răspunsuluiCopiază linkul secțiunii

AutorizareCopiază linkul secțiunii

Parametri de caleCopiază linkul secțiunii

Parametri queryCopiază linkul secțiunii

Parametri headerCopiază linkul secțiunii

Corpul răspunsuluiCopiază linkul secțiunii

AutorizareCopiază linkul secțiunii

Parametri de caleCopiază linkul secțiunii

Parametri headerCopiază linkul secțiunii

Corpul cereriiCopiază linkul secțiunii

Corpul răspunsuluiCopiază linkul secțiunii

AutorizareCopiază linkul secțiunii

Parametri de caleCopiază linkul secțiunii

Parametri headerCopiază linkul secțiunii

Corpul răspunsuluiCopiază linkul secțiunii

AutorizareCopiază linkul secțiunii

Parametri de caleCopiază linkul secțiunii

Parametri headerCopiază linkul secțiunii

Corpul cereriiCopiază linkul secțiunii

Corpul răspunsuluiCopiază linkul secțiunii

AutorizareCopiază linkul secțiunii

Parametri de caleCopiază linkul secțiunii

Parametri headerCopiază linkul secțiunii

Corpul cereriiCopiază linkul secțiunii

Corpul răspunsuluiCopiază linkul secțiunii

AutorizareCopiază linkul secțiunii

Parametri de caleCopiază linkul secțiunii

Parametri headerCopiază linkul secțiunii

Corpul răspunsuluiCopiază linkul secțiunii

AutorizareCopiază linkul secțiunii

Parametri de caleCopiază linkul secțiunii

Parametri headerCopiază linkul secțiunii

Corpul răspunsuluiCopiază linkul secțiunii

AutorizareCopiază linkul secțiunii

Parametri de caleCopiază linkul secțiunii

Parametri queryCopiază linkul secțiunii

Parametri headerCopiază linkul secțiunii

Corpul răspunsuluiCopiază linkul secțiunii

Autorizare

Parametri header

Corpul cererii

Corpul răspunsului

Autorizare

Parametri query

Parametri header

Corpul răspunsului

Autorizare

Parametri de cale

Parametri query

Parametri header

Corpul răspunsului

Autorizare

Parametri de cale

Parametri header

Corpul cererii

Corpul răspunsului

Autorizare

Parametri de cale

Parametri header

Corpul răspunsului

Autorizare

Parametri de cale

Parametri query

Parametri header

Corpul răspunsului

Autorizare

Parametri de cale

Parametri header

Corpul cererii

Corpul răspunsului

Autorizare

Parametri de cale

Parametri query

Parametri header

Corpul răspunsului

Autorizare

Parametri de cale

Parametri header

Corpul cererii

Corpul răspunsului

Autorizare

Parametri de cale

Parametri header

Corpul răspunsului

Autorizare

Parametri de cale

Parametri header

Corpul cererii

Corpul răspunsului

Autorizare

Parametri de cale

Parametri header

Corpul cererii

Corpul răspunsului

Autorizare

Parametri de cale

Parametri header

Corpul răspunsului

Autorizare

Parametri de cale

Parametri header

Corpul răspunsului

Autorizare

Parametri de cale

Parametri query

Parametri header

Corpul răspunsului