codai Orgs & Sharing API
Share a session with a user, an org or an expiring link, and manage the orgs (teams) you belong to. Every mutation writes an audit row. Link tokens are stored only as a SHA-256 hash; the plaintext is returned exactly once.
Share a session with a user, an org or an expiring link, and manage the orgs (teams) you belong to. Every mutation writes an audit row. Link tokens are stored only as a SHA-256 hash; the plaintext is returned exactly once.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/codai-ro:codai-ro-orgs-sharing-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Codai Ro Orgs & Sharing API
version: '1'
description: 'Operations tagged Orgs & Sharing across 2 of this provider''s published API definitions: codai-ro-gateway-openapi.json, codai-ro-gateway-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://ai.codai.ro
description: Production
security:
- bearerAuth: []
tags:
- name: Orgs & Sharing
description: 'Share a session with a user, an org or an expiring link, and manage the orgs (teams) you belong to. Every mutation
writes an audit row. Link tokens are stored only as a SHA-256 hash; the plaintext is returned exactly once.'
paths:
/v1/sessions/shared-with-me:
get:
operationId: listSessionsSharedWithMe
tags:
- Orgs & Sharing
summary: Sessions other people shared with you
description: 'Sessions you do not own but can access through a direct user share or through an org you are a member of.
Link shares are not attached to a user and are therefore excluded. Expired shares are skipped. When several
shares grant the same session, the highest role wins and its `share_id` is reported. Sorted by last activity,
capped at 200. Archived sessions are hidden unless `archived=1`.'
parameters:
- $ref: '#/components/parameters/RequestId'
- name: archived
in: query
required: false
description: Set to `1` or `true` to include archived sessions.
schema:
type: string
enum:
- '1'
- 'true'
responses:
'200':
description: Shared sessions with your effective role.
content:
application/json:
schema:
type: object
required:
- sessions
properties:
sessions:
type: array
items:
$ref: '#/components/schemas/OrgSharedSession'
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/PaymentRequired'
servers:
- url: https://ai.codai.ro
description: Production
/v1/sessions/{id}/shares:
get:
operationId: listSessionShares
tags:
- Orgs & Sharing
summary: List the shares of a session
description: 'Owner only. `id` may be the session UUID or your `session_key`. Returns every share (user, org and link),
oldest first. Link tokens are never returned again — `has_token` only tells you one exists. A session that
exists but where you are not owner → 403 `not_a_member`; unknown → 404.'
parameters:
- $ref: '#/components/parameters/RequestId'
- name: id
in: path
required: true
description: Session UUID or your `session_key` (the value used as `x-codai-session-id`). Own sessions win on `session_key` collisions.
schema:
type: string
maxLength: 128
examples:
- 6f1c2a4e-9d3b-4c7a-8e21-0b5f3d9a7c11
responses:
'200':
description: Shares of the session.
content:
application/json:
schema:
type: object
required:
- shares
properties:
shares:
type: array
items:
$ref: '#/components/schemas/OrgSessionShare'
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/PaymentRequired'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
post:
operationId: createSessionShare
tags:
- Orgs & Sharing
summary: Share a session with a user, an org or a link
description: 'Owner only. `principal_type: user` needs `principal_id` = the target user''s UUID (must exist; sharing with
yourself is a 400). `principal_type: org` needs `principal_id` = an org UUID you are a member of (403
otherwise). `principal_type: link` forbids `principal_id` and mints a random token, returned in `token` in
THIS response only — it is stored as a SHA-256 hash and never shown again. Recipients present the token via
the `x-codai-share-token` header or `?share=` query on session endpoints. `expires_at` must be in the future.
Writes a `share_add` audit row (with the caller''s `x-codai-device` when present).'
parameters:
- $ref: '#/components/parameters/RequestId'
- name: id
in: path
required: true
description: Session UUID or your `session_key` (the value used as `x-codai-session-id`). Own sessions win on `session_key` collisions.
schema:
type: string
maxLength: 128
examples:
- 6f1c2a4e-9d3b-4c7a-8e21-0b5f3d9a7c11
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/OrgCreateShareBody'
responses:
'201':
description: The created share; `token` is present only for link shares.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/OrgSessionShare'
- type: object
properties:
token:
type: string
description: Plaintext link token (base64url, 43 chars). Returned once; link shares only.
examples:
- Qm9keSBvZiB0aGUgdG9rZW4gaXMgcmFuZG9tIGJ5dGVz
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/PaymentRequired'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
description: 'The insert returned no row (`code: internal_error`).'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
servers:
- url: https://ai.codai.ro
description: Production
/v1/sessions/{id}/shares/{shareId}:
delete:
operationId: deleteSessionShare
tags:
- Orgs & Sharing
summary: Revoke a share
description: 'Owner only. Removes the share; a link share''s token stops working immediately. Writes a `share_remove`
audit row. A malformed `shareId`, or one that belongs to another session, is reported as 404.'
parameters:
- $ref: '#/components/parameters/RequestId'
- name: id
in: path
required: true
description: Session UUID or your `session_key` (the value used as `x-codai-session-id`). Own sessions win on `session_key` collisions.
schema:
type: string
maxLength: 128
examples:
- 6f1c2a4e-9d3b-4c7a-8e21-0b5f3d9a7c11
- name: shareId
in: path
required: true
description: Share UUID.
schema:
type: string
format: uuid
responses:
'200':
description: Deleted.
content:
application/json:
schema:
type: object
required:
- deleted
- id
properties:
deleted:
type: boolean
enum:
- true
id:
type: string
format: uuid
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/PaymentRequired'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
servers:
- url: https://ai.codai.ro
description: Production
/v1/orgs:
post:
operationId: createOrg
tags:
- Orgs & Sharing
summary: Create an org
description: 'Creates an org owned by the caller and adds the caller as its `owner` member. Writes an `org:create` audit
row. The response is the org row (camelCase keys, as stored) plus your `role`.'
parameters:
- $ref: '#/components/parameters/RequestId'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- name
properties:
name:
type: string
minLength: 1
maxLength: 200
description: Display name; trimmed.
examples:
- Acme Robotics
responses:
'201':
description: The new org.
content:
application/json:
schema:
$ref: '#/components/schemas/OrgWithRole'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/PaymentRequired'
'500':
description: 'The insert returned no row (`code: internal_error`).'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
get:
operationId: listOrgs
tags:
- Orgs & Sharing
summary: List the orgs you belong to
description: Every org you are a member of, each with your `role` in it. Ordering is not guaranteed.
parameters:
- $ref: '#/components/parameters/RequestId'
responses:
'200':
description: Your orgs.
content:
application/json:
schema:
type: object
required:
- orgs
properties:
orgs:
type: array
items:
$ref: '#/components/schemas/OrgWithRole'
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/PaymentRequired'
servers:
- url: https://ai.codai.ro
description: Production
/v1/orgs/{id}/members:
get:
operationId: listOrgMembers
tags:
- Orgs & Sharing
summary: List an org's members
description: 'Any member (`owner`, `admin` or `member`) may list. Members are ordered by join date; each carries the
user''s email when the user row still exists. Non-members get 403; a malformed or unknown org id is 404.'
parameters:
- $ref: '#/components/parameters/RequestId'
- name: id
in: path
required: true
description: Org UUID.
schema:
type: string
format: uuid
responses:
'200':
description: Members of the org.
content:
application/json:
schema:
type: object
required:
- org_id
- members
properties:
org_id:
type: string
format: uuid
members:
type: array
items:
$ref: '#/components/schemas/OrgMember'
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/PaymentRequired'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
post:
operationId: addOrgMember
tags:
- Orgs & Sharing
summary: Add or re-role a member
description: '`owner` or `admin` only. Identify the user by exactly one of `user_id` or `email` (both or neither → 400;
unknown user → 404). If the user is already a member the role is updated (upsert). Granting `role: owner`
requires the caller to be the org owner. Writes an `org:member_add` audit row.'
parameters:
- $ref: '#/components/parameters/RequestId'
- name: id
in: path
required: true
description: Org UUID.
schema:
type: string
format: uuid
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/OrgAddMemberBody'
responses:
'201':
description: The membership as stored.
content:
application/json:
schema:
type: object
required:
- org_id
- user_id
- role
properties:
org_id:
type: string
format: uuid
user_id:
type: string
format: uuid
role:
$ref: '#/components/schemas/OrgRole'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/PaymentRequired'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
servers:
- url: https://ai.codai.ro
description: Production
/v1/orgs/{id}/members/{userId}:
delete:
operationId: removeOrgMember
tags:
- Orgs & Sharing
summary: Remove a member
description: '`owner` or `admin` only. The org owner (`ownerUserId`) can never be removed (403). A malformed `userId` or
one that is not a member → 404. Writes an `org:member_remove` audit row.'
parameters:
- $ref: '#/components/parameters/RequestId'
- name: id
in: path
required: true
description: Org UUID.
schema:
type: string
format: uuid
- name: userId
in: path
required: true
description: UUID of the member to remove.
schema:
type: string
format: uuid
responses:
'200':
description: Removed.
content:
application/json:
schema:
type: object
required:
- deleted
- org_id
- user_id
properties:
deleted:
type: boolean
enum:
- true
org_id:
type: string
format: uuid
user_id:
type: string
format: uuid
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/PaymentRequired'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
servers:
- url: https://ai.codai.ro
description: Production
components:
responses:
Unauthorized:
description: Missing, malformed, revoked or paused API key.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Forbidden:
description: The key is valid but not allowed to perform this action (model allow-list, role, ownership).
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
PaymentRequired:
description: The subscription behind this key is inactive.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFound:
description: No such resource, or it belongs to another account.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
BadRequest:
description: Malformed body or query; `details` holds the flattened field errors.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
schemas:
OrgRole:
type: string
description: Role inside an org.
enum:
- owner
- admin
- member
OrgSharedSession:
type: object
title: Shared session
description: A session object (same wire shape as `GET /v1/sessions/{id}`) plus your effective role and the share that grants it.
required:
- id
- session_key
- owner_user_id
- title
- created_at
- last_event_at
- last_seq
- executor_device_id
- lease_expires_at
- e2e
- archived
- role
- share_id
properties:
id:
type: string
format: uuid
session_key:
type: string
description: The owner's `x-codai-session-id` value.
owner_user_id:
type: string
format: uuid
title:
type:
- string
- 'null'
created_at:
type: string
format: date-time
last_event_at:
type: string
format: date-time
last_seq:
type: integer
description: Sequence number of the latest event.
executor_device_id:
type:
- string
- 'null'
format: uuid
lease_expires_at:
type:
- string
- 'null'
format: date-time
e2e:
type: boolean
archived:
type: boolean
role:
$ref: '#/components/schemas/OrgSessionRole'
share_id:
type: string
format: uuid
description: The share granting the highest role.
OrgMember:
type: object
title: Org member
required:
- user_id
- role
- created_at
- email
properties:
user_id:
type: string
format: uuid
role:
$ref: '#/components/schemas/OrgRole'
created_at:
type: string
format: date-time
description: When the membership was created.
email:
type:
- string
- 'null'
format: email
description: The member's email, or `null` if the user row is gone.
OrgAddMemberBody:
type: object
title: Add member body
description: Exactly one of `user_id` or `email` is required.
properties:
user_id:
type: string
format: uuid
email:
type: string
format: email
examples:
- ana@example.com
role:
allOf:
- $ref: '#/components/schemas/OrgRole'
default: member
description: Default `member`. `owner` can only be granted by the org owner.
OrgSessionShare:
type: object
title: Session share
required:
- id
- session_id
- principal_type
- principal_id
- role
- has_token
- expires_at
- created_by_user_id
- created_at
properties:
id:
type: string
format: uuid
session_id:
type: string
format: uuid
principal_type:
$ref: '#/components/schemas/OrgSharePrincipalType'
principal_id:
type:
- string
- 'null'
description: User UUID or org UUID; `null` for link shares.
role:
$ref: '#/components/schemas/OrgSessionRole'
has_token:
type: boolean
description: Link shares only — a token exists. The plaintext is never returned after creation.
expires_at:
type:
- string
- 'null'
format: date-time
created_by_user_id:
type: string
format: uuid
created_at:
type: string
format: date-time
Error:
type: object
required:
- error
properties:
error:
type: object
required:
- message
- type
- code
properties:
message:
type: string
description: Human-readable, provider names redacted.
type:
type: string
enum:
- invalid_request_error
- subscription_required
- rate_limit_error
- upstream_error
- server_error
code:
type: string
enum:
- bad_request
- invalid_api_key
- subscription_inactive
- forbidden
- not_found
- payload_too_large
- rate_limit_exceeded
- quota_exceeded
- upstream_error
- internal_error
- not_a_member
- lease_held
- seq_conflict
- host_offline
- host_timeout
- rules_refused
- search_unavailable
- task_not_confirmable
- slug_taken
- project_has_environments
- already_has_env
- not_enrollable
- not_byo
- invalid_transition
- already_member
- vm_per_dev_single_member
- last_owner
- insufficient_balance
- key_scope_forbidden
- assets_unavailable
- asset_not_found
- too_many_renders
- renders_unavailable
- timeline_too_long
- not_a_timeline
- invalid_cursor
- templates_unavailable
- url_blocked
- invalid_tokens
- unsupported_media
- kind_mismatch
- node_not_found
- invalid_pick
- duplicate_key
- unknown_var
- invalid_var_value
- unsupported_kind
- too_long
- stale
- not_supported_for_kind
- unsupported_format
- too_large
- not_implemented
- version_conflict
- settings_unavailable
- ai_label_required
- sandbox_concurrency_limit
- sandbox_busy
- sandbox_daily_limit
- invalid_ttl
- workspace_too_large
- sandbox_paused_limit
- sandbox_capacity
details:
description: Present on `bad_request` (flattened Zod field errors), `invalid_tokens` (`issues`) and `rules_refused` (`tool`, `rule_id`, `decision`). Other codes never forward details over HTTP.
type: object
additionalProperties: true
examples:
- error:
message: Invalid or missing API key.
type: invalid_request_error
code: invalid_api_key
OrgWithRole:
type: object
title: Org
description: The stored org row (camelCase, as persisted) plus the caller's role.
required:
- id
- name
- ownerUserId
- createdAt
- role
properties:
id:
type: string
format: uuid
examples:
- 7e2f9b4c-1a3d-4e5f-9b8c-2d4e6f8a0b1c
name:
type: string
examples:
- Acme Robotics
ownerUserId:
type: string
format: uuid
createdAt:
type: string
format: date-time
examples:
- '2026-09-23T08:41:12.000Z'
role:
$ref: '#/components/schemas/OrgRole'
OrgCreateShareBody:
type: object
title: Create share body
required:
- principal_type
properties:
principal_type:
$ref: '#/components/schemas/OrgSharePrincipalType'
principal_id:
type: string
minLength: 1
maxLength: 128
description: Required (user or org UUID) for `user` and `org`; forbidden for `link`.
examples:
- 9c4b1f2e-3d5a-4b6c-8e7f-1a2b3c4d5e6f
role:
allOf:
- $ref: '#/components/schemas/OrgSessionRole'
default: viewer
description: Role to grant. Default `viewer`.
expires_at:
type: string
format: date-time
description: ISO 8601 with offset; must be in the future. Omit for no expiry.
examples:
- '2026-10-01T00:00:00+03:00'
OrgSessionRole:
type: string
description: Role granted on a session.
enum:
- viewer
- editor
- owner
OrgSharePrincipalType:
type: string
description: Who a share is for.
enum:
- user
- org
- link
parameters:
RequestId:
name: x-request-id
in: header
required: false
description: Client correlation id; echoed back as `x-codai-trace-id` and persisted on the usage row.
schema:
type: string
maxLength: 128
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: codai_…
description: 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`).
x-refined-from:
- codai-ro-gateway-openapi.json
- codai-ro-gateway-openapi.yml