Session start

POST /api/v1/external/realtime/session/start starts a realtime session from a session-config body and returns the LiveKit join credentials. The response contains everything the client needs to join the room; all further control traffic rides the wire protocol on the room's data channel.

The SDKs call this internally (agent.start()). Use the raw endpoint only for custom integrations.

Schema and try-it: this endpoint in the API explorer.

Authentication

Bearer token in the Authorization header — either of:

• a workspace API key carrying the realtime:start scope (server-side secret; the deprecated realtime:use umbrella implies it), or
• a minted end-user JWT (from POST /api/v1/external/auth/token), safe on end-user devices.

Authorization: Bearer cosmo_...

See API keys, Scopes, and End-user credentials.

Request

POST /api/v1/external/realtime/session/start
Content-Type: application/json
Authorization: Bearer cosmo_...

The body is the external protocol's session-config payload: an agent block (the persona) plus a session block (per-run options).

{
  "type": "session-config",
  "sdk": { "name": "cosmo-ai-sdk", "version": "X.Y.Z" },
  "agent": {
    "type": "inline",
    "instructions": "You are a concise support agent.",
    "voice": { "name": "Puck" },
    "tools": [{ "kind": "web_search" }]
  },
  "session": { "max_session_seconds": 1800 }
}

Top level

agent — catalog variant

Run a workspace catalog agent by machine handle; the stored config runs verbatim. Only per-run ride-alongs may accompany the launch — any other field is a schema error (extra="forbid"), not a runtime rejection.

agent — inline variant

Define the persona in the request. Catalog-only fields (name, inputs) are structurally absent here.

Tool specs

Each entry in tools is discriminated on kind:

A kind outside this table fails schema validation and is rejected as a validation_error, like any other malformed body. The retired kind: "server" is different: it still parses (the schema knows it), then rejects with invalid_tool_config — the same path as catalog.

Session params

Response

200 OK

{
  "livekit_url": "wss://lk.example.com",
  "token": "<livekit-access-token>",
  "room_name": "cosmo-9f3c1ad84be7205c6d18e4b2",
  "session_id": "8f7e6d5c-4b3a-2190-aaaa-bbbbccccdddd"
}

After joining the room, wait for the agent's readiness before the first send. It is announced two ways: a ready frame broadcast on the data channel, and the cosmo.ready participant attribute on the agent — room state, so a client that joins or subscribes late still reads it. Latch on whichever you see first. The attribute carries the same payload as the frame unless that payload is oversized, in which case it degrades to the session id and duration cap alone — so read rejected_tools and agent from the frame when you have it. See Lifecycle.

Errors

Every non-2xx response carries the same envelope:

{
  "error": {
    "type": "api_error",
    "code": "unknown_agent",
    "message": "No agent named 'support-agnt' in this workspace.",
    "errors": null
  }
}

Notable rejections:

Example — curl

curl -X POST https://platform.askcosmo.ai/api/v1/external/realtime/session/start \
  -H "Authorization: Bearer cosmo_..." \
  -H "Content-Type: application/json" \
  -d '{
    "agent": {
      "type": "catalog",
      "name": "support-agent",
      "inputs": { "caller_name": "Sam" }
    },
    "session": { "max_session_seconds": 1800 }
  }'

Sibling endpoints

All take the same Bearer auth; session start requires realtime:start, dial realtime:dial, session reads realtime:read, token minting and revocation user_tokens:mint, and verify no scope at all. The deprecated realtime:use umbrella implies all the realtime verbs — see Scopes.