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.

Authorization

bearerAuth

AuthorizationBearer <token>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by /v1/realtime.

In: header

Query Parameters

archived?string

Set to 1 or true to include archived sessions.

Value in

"1"
"true"

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

`application/json`

curl -X GET "https://example.com/v1/sessions/shared-with-me"

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

Authorization

bearerAuth

AuthorizationBearer <token>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by /v1/realtime.

In: header

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

x-request-id?string

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

Lengthlength <= 128

Response Body

`application/json`

curl -X GET "https://example.com/v1/sessions/6f1c2a4e-9d3b-4c7a-8e21-0b5f3d9a7c11/shares"

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

Authorization

bearerAuth

AuthorizationBearer <token>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by /v1/realtime.

In: header

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

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

TypeScript Definitions

Use the request body type in TypeScript.

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

`application/json`

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

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

Authorization

bearerAuth

AuthorizationBearer <token>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by /v1/realtime.

In: header

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

x-request-id?string

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

Lengthlength <= 128

Response Body

`application/json`

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

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

Authorization

bearerAuth

AuthorizationBearer <token>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by /v1/realtime.

In: header

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

TypeScript Definitions

Use the request body type in TypeScript.

name*string

Display name; trimmed.

Length1 <= length <= 200

Response Body

`application/json`

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

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

Authorization

bearerAuth

AuthorizationBearer <token>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by /v1/realtime.

In: header

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

`application/json`

curl -X GET "https://example.com/v1/orgs"

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

Authorization

bearerAuth

AuthorizationBearer <token>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by /v1/realtime.

In: header

Path Parameters

id*string

Org 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

`application/json`

curl -X GET "https://example.com/v1/orgs/497f6eca-6276-4993-bfeb-53cbbbba6f08/members"

{  "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": "[email protected]"    }  ]}

Authorization

bearerAuth

AuthorizationBearer <token>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by /v1/realtime.

In: header

Path Parameters

id*string

Org 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

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

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

`application/json`

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

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

Authorization

bearerAuth

AuthorizationBearer <token>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by /v1/realtime.

In: header

Path Parameters

id*string

Org UUID.

Formatuuid

userId*string

UUID of the member to remove.

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

`application/json`

curl -X DELETE "https://example.com/v1/orgs/497f6eca-6276-4993-bfeb-53cbbbba6f08/members/497f6eca-6276-4993-bfeb-53cbbbba6f08"

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

200application/json

401application/json

402application/json

200application/json

401application/json

402application/json

403application/json

404application/json

201application/json

400application/json

401application/json

402application/json

403application/json

404application/json

500application/json

200application/json

401application/json

402application/json

403application/json

404application/json

201application/json

400application/json

401application/json

402application/json

500application/json

200application/json

401application/json

402application/json

200application/json

401application/json

402application/json

403application/json

404application/json

201application/json

400application/json

401application/json

402application/json

403application/json

404application/json

200application/json

401application/json

402application/json

403application/json

404application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`