Orgs & Sharing

Share a session with a user, an org or a link, and manage the orgs you belong to.

Shares grant viewer, editor or owner on one session; link shares return a token the recipient presents as x-codai-share-token or ?share=. Org objects are returned camelCase (ownerUserId, createdAt) while member lists are snake_case — mirrored here exactly as the gateway sends them. Background: sharing & orgs.

Agents read your orgs through the MCP server tools orgs_list and org_members_list (id; members only). Both are read-only: creating orgs and adding or removing members stay in the hub.

GET

/v1/sessions/shared-with-me

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

archived?string

Set to 1 or true to include archived sessions.

Value in"1""true"

Header Parameters

Response Body

Shared sessions with your effective role.

application/json

response

sessions*array<>

Example Request

curl -X GET 'https://ai.codai.ro/v1/sessions/shared-with-me'

Example Request

curl -X GET 'https://ai.codai.ro/v1/sessions/shared-with-me'

Example ResponseSchema

{
  "sessions": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "session_key": "string",
      "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,
      "role": "viewer",
      "share_id": "853fa54b-9753-4ffb-b7d0-6739f9ae0f8e"
    }
  ]
}

{  "sessions": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "session_key": "string",      "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,      "role": "viewer",      "share_id": "853fa54b-9753-4ffb-b7d0-6739f9ae0f8e"    }  ]}

GET

/v1/sessions/{id}/shares

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

Session UUID or your session_key (the value used as x-codai-session-id). Own sessions win on session_key collisions.

Lengthlength <= 128

Header Parameters

Response Body

Shares of the session.

application/json

response

shares*array<>

Example Request

curl -X GET 'https://ai.codai.ro/v1/sessions/6f1c2a4e-9d3b-4c7a-8e21-0b5f3d9a7c11/shares'

Example Request

curl -X GET 'https://ai.codai.ro/v1/sessions/6f1c2a4e-9d3b-4c7a-8e21-0b5f3d9a7c11/shares'

Example ResponseSchema

{
  "shares": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "session_id": "1ffd059c-17ea-40a8-8aef-70fd0307db82",
      "principal_type": "user",
      "principal_id": "string",
      "role": "viewer",
      "has_token": true,
      "expires_at": "2019-08-24T14:15:22Z",
      "created_by_user_id": "209f54c4-4c33-43bc-9c6a-ef4c65ad7473",
      "created_at": "2019-08-24T14:15:22Z"
    }
  ]
}

{  "shares": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "session_id": "1ffd059c-17ea-40a8-8aef-70fd0307db82",      "principal_type": "user",      "principal_id": "string",      "role": "viewer",      "has_token": true,      "expires_at": "2019-08-24T14:15:22Z",      "created_by_user_id": "209f54c4-4c33-43bc-9c6a-ef4c65ad7473",      "created_at": "2019-08-24T14:15:22Z"    }  ]}

POST

/v1/sessions/{id}/shares

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

Session UUID or your session_key (the value used as x-codai-session-id). Own sessions win on session_key collisions.

Lengthlength <= 128

Header Parameters

Request Body

application/json

body

principal_type*OrgSharePrincipalType

Who a share is for.

Value in"user""org""link"

principal_id?string

Required (user or org UUID) for user and org; forbidden for link.

Length1 <= length <= 128

role?string

Role to grant. Default viewer.

Default"viewer"

Value in"viewer""editor""owner"

expires_at?string

ISO 8601 with offset; must be in the future. Omit for no expiry.

Formatdate-time

Response Body

The created share; token is present only for link shares.

application/json

response

id*string

Formatuuid

session_id*string

Formatuuid

principal_type*OrgSharePrincipalType

Who a share is for.

Value in"user""org""link"

principal_id*|

User UUID or org UUID; null for link shares.

role*OrgSessionRole

Role granted on a session.

Value in"viewer""editor""owner"

has_token*boolean

Link shares only — a token exists. The plaintext is never returned after creation.

expires_at*|

Formatdate-time

created_by_user_id*string

Formatuuid

created_at*string

Formatdate-time

token?string

Plaintext link token (base64url, 43 chars). Returned once; link shares only.

Example Request

curl -X POST 'https://ai.codai.ro/v1/sessions/6f1c2a4e-9d3b-4c7a-8e21-0b5f3d9a7c11/shares' \
  -H 'Content-Type: application/json' \
  -d '{
  "principal_type": "user"
}'

Example Request

curl -X POST 'https://ai.codai.ro/v1/sessions/6f1c2a4e-9d3b-4c7a-8e21-0b5f3d9a7c11/shares' \  -H 'Content-Type: application/json' \  -d '{  "principal_type": "user"}'

Example ResponseSchema

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "session_id": "1ffd059c-17ea-40a8-8aef-70fd0307db82",
  "principal_type": "user",
  "principal_id": "string",
  "role": "viewer",
  "has_token": true,
  "expires_at": "2019-08-24T14:15:22Z",
  "created_by_user_id": "209f54c4-4c33-43bc-9c6a-ef4c65ad7473",
  "created_at": "2019-08-24T14:15:22Z",
  "token": "Qm9keSBvZiB0aGUgdG9rZW4gaXMgcmFuZG9tIGJ5dGVz"
}

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "session_id": "1ffd059c-17ea-40a8-8aef-70fd0307db82",  "principal_type": "user",  "principal_id": "string",  "role": "viewer",  "has_token": true,  "expires_at": "2019-08-24T14:15:22Z",  "created_by_user_id": "209f54c4-4c33-43bc-9c6a-ef4c65ad7473",  "created_at": "2019-08-24T14:15:22Z",  "token": "Qm9keSBvZiB0aGUgdG9rZW4gaXMgcmFuZG9tIGJ5dGVz"}

DELETE

/v1/sessions/{id}/shares/{shareId}

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

Session UUID or your session_key (the value used as x-codai-session-id). Own sessions win on session_key collisions.

Lengthlength <= 128

shareId*string

Share UUID.

Formatuuid

Header Parameters

Response Body

Deleted.

application/json

response

deleted*true

Value intrue

id*string

Formatuuid

Example Request

curl -X DELETE 'https://ai.codai.ro/v1/sessions/6f1c2a4e-9d3b-4c7a-8e21-0b5f3d9a7c11/shares/497f6eca-6276-4993-bfeb-53cbbbba6f08'

Example Request

curl -X DELETE 'https://ai.codai.ro/v1/sessions/6f1c2a4e-9d3b-4c7a-8e21-0b5f3d9a7c11/shares/497f6eca-6276-4993-bfeb-53cbbbba6f08'

Example ResponseSchema

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

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

POST

/v1/orgs

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

name*string

Display name; trimmed.

Length1 <= length <= 200

Response Body

The new org.

application/json

response

The stored org row (camelCase, as persisted) plus the caller's role.

id*string

Formatuuid

name*string

ownerUserId*string

Formatuuid

createdAt*string

Formatdate-time

role*OrgRole

Role inside an org.

Value in"owner""admin""member"

Example Request

curl -X POST 'https://ai.codai.ro/v1/orgs' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Acme Robotics"
}'

Example Request

curl -X POST 'https://ai.codai.ro/v1/orgs' \  -H 'Content-Type: application/json' \  -d '{  "name": "Acme Robotics"}'

Example ResponseSchema

{
  "id": "7e2f9b4c-1a3d-4e5f-9b8c-2d4e6f8a0b1c",
  "name": "Acme Robotics",
  "ownerUserId": "283eeac5-beea-465a-80a5-763009480d0f",
  "createdAt": "2026-09-23T08:41:12.000Z",
  "role": "owner"
}

{  "id": "7e2f9b4c-1a3d-4e5f-9b8c-2d4e6f8a0b1c",  "name": "Acme Robotics",  "ownerUserId": "283eeac5-beea-465a-80a5-763009480d0f",  "createdAt": "2026-09-23T08:41:12.000Z",  "role": "owner"}

GET

/v1/orgs

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

Response Body

Your orgs.

application/json

response

orgs*array<>

Example Request

curl -X GET 'https://ai.codai.ro/v1/orgs'

Example Request

curl -X GET 'https://ai.codai.ro/v1/orgs'

Example ResponseSchema

{
  "orgs": [
    {
      "id": "7e2f9b4c-1a3d-4e5f-9b8c-2d4e6f8a0b1c",
      "name": "Acme Robotics",
      "ownerUserId": "283eeac5-beea-465a-80a5-763009480d0f",
      "createdAt": "2026-09-23T08:41:12.000Z",
      "role": "owner"
    }
  ]
}

{  "orgs": [    {      "id": "7e2f9b4c-1a3d-4e5f-9b8c-2d4e6f8a0b1c",      "name": "Acme Robotics",      "ownerUserId": "283eeac5-beea-465a-80a5-763009480d0f",      "createdAt": "2026-09-23T08:41:12.000Z",      "role": "owner"    }  ]}

GET

/v1/orgs/{id}/members

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

Org UUID.

Formatuuid

Header Parameters

Response Body

Members of the org.

application/json

response

org_id*string

Formatuuid

members*array<>

Example Request

curl -X GET 'https://ai.codai.ro/v1/orgs/497f6eca-6276-4993-bfeb-53cbbbba6f08/members'

Example Request

curl -X GET 'https://ai.codai.ro/v1/orgs/497f6eca-6276-4993-bfeb-53cbbbba6f08/members'

Example ResponseSchema

{
  "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",
  "members": [
    {
      "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
      "role": "owner",
      "created_at": "2019-08-24T14:15:22Z",
      "email": "user@example.com"
    }
  ]
}

{  "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",  "members": [    {      "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",      "role": "owner",      "created_at": "2019-08-24T14:15:22Z",      "email": "user@example.com"    }  ]}

POST

/v1/orgs/{id}/members

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

Org UUID.

Formatuuid

Header Parameters

Request Body

application/json

body

Exactly one of user_id or email is required.

user_id?string

Formatuuid

email?string

Formatemail

role?string

Default member. owner can only be granted by the org owner.

Default"member"

Value in"owner""admin""member"

Response Body

The membership as stored.

application/json

response

org_id*string

Formatuuid

user_id*string

Formatuuid

role*OrgRole

Role inside an org.

Value in"owner""admin""member"

Example Request

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

Example Request

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

Example ResponseSchema

{
  "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",
  "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
  "role": "owner"
}

{  "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",  "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",  "role": "owner"}

DELETE

/v1/orgs/{id}/members/{userId}

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

Org UUID.

Formatuuid

userId*string

UUID of the member to remove.

Formatuuid

Header Parameters

Response Body

Removed.

application/json

response

deleted*true

Value intrue

org_id*string

Formatuuid

user_id*string

Formatuuid

Example Request

curl -X DELETE 'https://ai.codai.ro/v1/orgs/497f6eca-6276-4993-bfeb-53cbbbba6f08/members/497f6eca-6276-4993-bfeb-53cbbbba6f08'

Example Request

curl -X DELETE 'https://ai.codai.ro/v1/orgs/497f6eca-6276-4993-bfeb-53cbbbba6f08/members/497f6eca-6276-4993-bfeb-53cbbbba6f08'

Example ResponseSchema

{
  "deleted": true,
  "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",
  "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5"
}

{  "deleted": true,  "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",  "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5"}

Orgs & Sharing

AuthorizationCopy 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

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

Header ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

AuthorizationCopy 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

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

Authorization

Query Parameters

Header Parameters

Response Body

Authorization

Path Parameters

Header Parameters

Response Body

Authorization

Path Parameters

Header Parameters

Request Body

Response Body

Authorization

Path Parameters

Header Parameters

Response Body

Authorization

Header Parameters

Request Body

Response Body

Authorization

Header Parameters

Response Body

Authorization

Path Parameters

Header Parameters

Response Body

Authorization

Path Parameters

Header Parameters

Request Body

Response Body

Authorization

Path Parameters

Header Parameters

Response Body