codai Sessions API

Shared-sessions protocol v2: one conversation shared live between several devices (desktop, phone, CLI, agents). A session has an append-only event log with a server-assigned dense `seq`, persisted controls (`send`, `answer`, `approve`, …), a single executor lease (TTL 30 s, heartbeat every 10 s) and a presence set. Every operation here needs a codai API key **and** the `x-codai-device` header — a client-chosen UUID that is registered on first use (`x-codai-device-name` / `x-codai-device-platform` optional; an `x-codai-push-token` header upserts the FCM token used by Dispatch). `GET /v1/sessions` and `GET /v1/sessions/{id}` fall through to the legacy read-only memory API when the header is absent, unless `?v=2` is set. `{id}` accepts the server UUID **or** the client `session_key`. Roles: `owner` (the creator) ≥ `editor` ≥ `viewer`; shares are managed under `/v1/sessions/{id}/shares`. Link-share callers present the token via `x-codai-share-token` or `?share=`. Realtime frames are also available over WebSocket at `wss://ai.codai.ro/v1/sessions/{id}/ws?after=` (not modelled here). Same `Authorization: Bearer` header auth (raw keys in `?key=` are rejected with close code 4401); the device id may ride in `?device=`. Upstream frames: `{t: control}`, `{t: events}`, `{t: presence, driving}`; downstream frames mirror the SSE events plus `ack` and `error`. WS `error` frames DO carry `details` (`holder_device_id`, `expected_last_seq`/`last_seq`) — over HTTP only the message does.

GitHub OpenAPI

Operations 15

POST /v1/sessions Create a session (idempotent on session_key) #
GET /v1/sessions List your sessions and sessions shared with you #
GET /v1/sessions/{id} Session detail with members, lease and presence #
PATCH /v1/sessions/{id} Rename or archive a session (owner) #
DELETE /v1/sessions/{id} Delete a session and everything under it (owner) #
GET /v1/sessions/{id}/events Page through the event log after a seq cursor #
POST /v1/sessions/{id}/events Append events (executor only) #
GET /v1/sessions/{id}/controls Drain the control queue of a session #
POST /v1/sessions/{id}/control Send a control to the executor (editor+) #
POST /v1/sessions/{id}/control/{cid}/applied Mark a control as applied (executor only) #
POST /v1/sessions/{id}/dispatch Queue a `send` (or an `open` handoff) for one device and wake it over FCM #
POST /v1/sessions/{id}/lease Claim the executor lease (owner, CAS) #
PUT /v1/sessions/{id}/lease Heartbeat the executor lease (owner) #
DELETE /v1/sessions/{id}/lease Release the executor lease (owner) #
GET /v1/sessions/{id}/stream Live SSE stream of events, controls, lease and presence #

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-sessions-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-sessions-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: Codai Ro Sessions API
  version: '1'
  description: 'Operations tagged Sessions 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:


# --- truncated at 32 KB (58 KB total) ---
# Full source: https://artifacts.apis.io/codai-ro/openapi/codai-ro-sessions-api-openapi.yml