Protocol reference

This is the normative surface of codai Shared Sessions v1.0.0 as served by https://ai.codai.ro. Field names are snake_case on the wire; timestamps named *_at are ISO-8601 strings; ts and last_seen are integer milliseconds since the Unix epoch. JSON Schemas for every object live in the protocol repository. Realtime frames are on the streaming page; shares and orgs have their own page.

Transport and headers

All routes are HTTPS under the gateway base URL and are JSON unless stated. Authentication is a Bearer API key; the principal is the user the key belongs to.

Authorization: Bearer codai_xxxxxxxx

Device headers

A device id already registered to another user is refused with 403 forbidden — Device id is registered to another account. — rather than reused.

Selecting v2 on overlapping paths

GET /v1/sessions and GET /v1/sessions/:id share their paths with a legacy read-only memory API. The shared-sessions handler is selected when the request carries x-codai-device or ?v=2. Always send x-codai-device; ?v=2 is for quick reads without a device.

Session references

Wherever a path contains :id you may pass either the server UUID id or your own session_key. When a session_key collides across users, your own session wins.

Objects

Session

{
  "id": "5b3e…-uuid",
  "session_key": "phone-7f1c…",
  "owner_user_id": "…-uuid",
  "title": "Book the dentist",
  "created_at": "2026-09-13T10:00:00.000Z",
  "last_event_at": "2026-09-13T10:04:12.512Z",
  "last_seq": 42,
  "executor_device_id": "…-uuid or null",
  "lease_expires_at": "2026-09-13T10:04:40.000Z or null",
  "e2e": false,
  "archived": false
}

session_key is client-chosen (the phone uses the same UUID it sends as x-codai-session-id for inference); id is server-assigned. List responses add role (yours) and presence_count; the detail response adds role, members[], lease and presence[]; shared-with-me adds role and share_id.

Device

{
  "id": "…-uuid",
  "name": "Pixel 9",
  "platform": "android",
  "capabilities": ["screen", "local_llm", "terminal", "contacts"],
  "has_push_token": true,
  "lastSeenAt": "2026-09-13T10:04:12.512Z",
  "createdAt": "2026-09-01T08:00:00.000Z"
}

capabilities is a free list of ≤ 64 strings of ≤ 64 chars. The push token is never returned — clients see has_push_token. The two camelCase timestamps on this object are part of v1 and will not be renamed.

Event

{
  "seq": 7,
  "kind": "tool_call",
  "ts": 1757757852512,
  "sender_device_id": "…-uuid",
  "turn_id": "t-…",
  "client_event_id": "c9f2…",
  "payload": { "name": "open_app", "args": { "package": "com.whatsapp" } }
}

• seq is server-assigned, dense per session, starting at 1. Clients never send it.
• kind: 1 – 64 chars, opaque to the server; unknown kinds are never rejected. The executor's trace vocabulary is turn_start, step_start, req_start, local_gen, tool_start, tool_call, tool_result, ask, ask_resolved, wait_user, deadline, error, usage, turn_end, plus assistant, user and the executor-emitted screen_wait.
• ts: client clock; defaults to server time when omitted.
• payload: any JSON object (default {}); { "hide": "<base64>" } in E2E mode.

Server-emitted kinds:

Control

{
  "id": "ctl-8d1a…",
  "kind": "steer",
  "text": "Use the second search result instead.",
  "turn_id": "t-…",
  "ask_id": null,
  "from_device_id": "…-uuid",
  "target_device_id": null,
  "seq": 8,
  "applied": false,
  "created_at": "2026-09-13T10:04:13.000Z"
}

kind ∈ send | answer | approve | deny | cancel | steer | inject. id is the client idempotency key (1 – 128 chars); text ≤ 100 000 chars. target_device_id is set only by dispatch and is null otherwise; a targeted control is meant for that one device and every other executor should skip it.

Lease

{ "session_id": "…-uuid", "device_id": "…-uuid", "expires_at": "2026-09-13T10:04:40.000Z" }

TTL 30 s; heartbeat every 10 s. Realtime lease frames use holder_device_id (nullable) instead of device_id.

Presence

{ "device_id": "…-uuid", "user_id": "…-uuid", "role": "editor", "executor": false, "driving": false, "last_seen": 1757757852512, "online": true, "remote": true }

Ephemeral, never persisted. remote is computed for the caller and appears only in GET /v1/sessions/:id; online appears only in presence frames (false on the leave frame).

Share and Org

See sharing and orgs. Share: { id, session_id, principal_type: user|org|link, principal_id, role: viewer|editor|owner, has_token, expires_at, created_by_user_id, created_at } (+ token once). Org: { id, name, ownerUserId, createdAt } — camelCase on the wire — with membership roles owner | admin | member.

Roles

1. owner when the session's owner_user_id is you.
2. Otherwise the maximum role over non-expired shares matching you directly, any org you belong to, or the link token you present.
3. Otherwise no role → 403 not_a_member. An unknown id is 404 not_found.

HTTP routes

Every mutation follows validate → authenticate → authorize → audit → execute. A failed validation is 400 bad_request with details describing the fields.

Sessions

members[] = { user_id, role, remote, devices: [{ device_id, name, platform, last_seen_at, remote }] }, one entry per member user (owner, direct user shares, members of org shares, and you if you came via a link).

Events

IncomingEvent = { kind, ts?, turn_id?, client_event_id?, payload? } — never seq. accepted counts newly stored events; duplicates (by client_event_id) are reported with their original seq.

Controls and dispatch

Lease

Devices

Lease semantics

• TTL 30 s, renewed by PUT …/lease every 10 s. expires_at is returned on claim and every heartbeat.
• Claim is compare-and-set. POST …/lease succeeds when the lease is free, expired, or already held by the calling device. If another device holds a live lease → 409 lease_held; the holder is named in message as (holder_device_id=…).
• Force. { "force": true } (owner) takes a live lease from another device. The server appends a lease_transferred event and audits it. The previous holder learns at its next heartbeat (409 lease_held, Lease lost to another device.) and must stop executing, become a viewer, and show who is driving.
• Heartbeat on an expired lease is 409 lease_held with Lease expired. and no holder.
• Release is idempotent: released: false when you did not hold it.
• Every claim/heartbeat/release publishes a lease frame and mirrors executor_device_id / lease_expires_at onto the session.
• Appending events or marking a control applied without the live lease → 409 lease_held.

Idempotency

Optimistic append. expected_last_seq on an events body makes the append conditional: if the session's last_seq differs → 409 seq_conflict and nothing is written. Seq allocation happens in one transaction — last_seq is bumped by the count of fresh events and they are inserted as base+1 … base+n, so seq is dense and gap-free.

Dispatch

Start a task on a named device from any editor+ client. Only the owner's devices can hold the lease, so device_id must belong to the owner — anything else is 404 not_found (Target device not found for this session.). Pick the id from GET /v1/sessions/:id → members[].devices.

On POST …/dispatch the server persists a send control whose echoed event carries payload.control.target_device_id, audits it, and — if the target has a push token — sends an FCM HTTP v1 data-only, high-priority message { "type": "dispatch", "session_id", "control_id" }. Push is fail-open: a failure never fails the request; the control is durable either way. pushed: false with push_reason ∈ no_push_token | no_token | auth_failed | network_error | unregistered | http_<status> means queued, not delivered yet — not an error. On unregistered the server clears the device's push token.

Wake flow on the device: push → headless executor starts → GET /v1/devices/me/dispatch (or GET …/controls?applied=false&target=me, before holding the lease) → POST …/lease (force: true if policy allows) → execute the drained send → POST …/control/:cid/applied → normal loop. Dispatch never touches the lease.

Errors

{ "error": { "message": "Another device holds a live executor lease. (holder_device_id=1c2f…)", "type": "invalid_request_error", "code": "lease_held" } }

details is included for bad_request (field-level validation output). For lease_held and seq_conflict the useful value is embedded in message; re-GET the session for the current last_seq.

WebSocket errors on up-messages use { v: 1, t: "error", ref?, error: {…} } and do include details.

Limits

No per-route rate limit is specific to this surface; the gateway's general API-key limits apply.

Versioning

Frames carry v: 1. Additive fields are non-breaking; a new event kind is non-breaking (viewers ignore unknown kinds). Nothing listed here is removed or renamed within v1; deprecations are announced in the protocol repository's CHANGELOG.md before behaviour changes.

Conformance checklist