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.

GitHub OpenAPI

Operations 9

GET /v1/sessions/shared-with-me Sessions other people shared with you #
GET /v1/sessions/{id}/shares List the shares of a session #
POST /v1/sessions/{id}/shares Share a session with a user, an org or a link #
DELETE /v1/sessions/{id}/shares/{shareId} Revoke a share #
POST /v1/orgs Create an org #
GET /v1/orgs List the orgs you belong to #
GET /v1/orgs/{id}/members List an org's members #
POST /v1/orgs/{id}/members Add or re-role a member #
DELETE /v1/orgs/{id}/members/{userId} Remove a member #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • 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.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/codai-ro:codai-ro-orgs-sharing-api"
All apis
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.

Get an API 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 Specification

codai-ro-orgs-sharing-api-openapi.yml Raw ↑
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