# codai Sessions API

**Canonical:** https://apis.io/apis/codai-ro/codai-ro-sessions-api/  
**Provider:** codai — https://apis.io/providers/codai-ro/  
**Base URL:** https://ai.codai.ro  
**Documentation:** https://docs.codai.ro/docs/api

codai Sessions API is one of 35 APIs that [codai](https://apis.io/providers/codai-ro/) publishes on the [APIs.io](https://apis.io/) network, described by a machine-readable OpenAPI specification. This API exposes 4 JSON Schema definitions. Tagged areas include Sessions. The published artifact set on APIs.io includes an OpenAPI specification, API documentation, and 4 JSON Schemas.

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=<seq>` (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.

## Operations (15)

| Method | Path | Summary |
|---|---|---|
| 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 |

## Machine-readable artifacts (6)

- **OpenAPI** — https://artifacts.apis.io/codai-ro/openapi/codai-ro-sessions-api-openapi.yml
- **Documentation** — https://docs.codai.ro/docs/gateway
- **JSONSchema** — https://artifacts.apis.io/codai-ro/json-schema/codai-ro-session-schema.json
- **JSONSchema** — https://artifacts.apis.io/codai-ro/json-schema/codai-ro-session-control-schema.json
- **JSONSchema** — https://artifacts.apis.io/codai-ro/json-schema/codai-ro-session-event-schema.json
- **JSONSchema** — https://artifacts.apis.io/codai-ro/json-schema/codai-ro-session-dispatch-response-schema.json

## Other codai APIs (12)

- [codai Account API](https://apis.io/apis/codai-ro/codai-ro-account-api/)
- [codai Agents API](https://apis.io/apis/codai-ro/codai-ro-agents-api/)
- [codai Attestations API](https://apis.io/apis/codai-ro/codai-ro-attestations-api/)
- [codai Authorization API](https://apis.io/apis/codai-ro/codai-ro-authorization-api/)
- [codai Chat & Completions API](https://apis.io/apis/codai-ro/codai-ro-chat-completions-api/)
- [codai Connect API](https://apis.io/apis/codai-ro/codai-ro-connect-api/)
- [codai Devices API](https://apis.io/apis/codai-ro/codai-ro-devices-api/)
- [codai Discovery API](https://apis.io/apis/codai-ro/codai-ro-discovery-api/)
- [codai Embeddings & Audio API](https://apis.io/apis/codai-ro/codai-ro-embeddings-audio-api/)
- [codai Feed API](https://apis.io/apis/codai-ro/codai-ro-feed-api/)
- [codai Guest chat API](https://apis.io/apis/codai-ro/codai-ro-guest-chat-api/)
- [codai Health API](https://apis.io/apis/codai-ro/codai-ro-health-api/)

## Tags

Sessions

---

Profiled by [API Evangelist](https://apievangelist.com) and published on [APIs.io](https://apis.io/apis/codai-ro/codai-ro-sessions-api/). The API's provider profile, Kin Score and agent-readiness rating are at https://apis.io/providers/codai-ro/.
