Create AND start a session

Canonical V0 endpoint (Decision D2). Creates and starts the session in a single call. The request body MUST include provider_type plus a matching provider_config carrying per-session ephemeral provider credentials.

Per-session ephemeral credentials are held in Gateway process memory ONLY for the session lifetime and are zeroed on session end. They are NEVER persisted to the database, KV, R2, DO storage, files, env vars, logs, PostHog, request IDs, or error messages.

Use Idempotency-Key to dedupe retry-safe session creation. provider_connection_id is REJECTED at the schema level (V0 does not accept managed provider connections).

POST/v1/sessions

Authorization

AuthorizationBearer token · headerrequired

`Authorization: Bearer <api_key>`

x-api-keyAPI key · headerrequired

`x-api-key: <api_key>`

Request body

requiredapplication/json

V0 session creation request.

avatar_configobject

Optional avatar/background pre-selection. If omitted the server applies its catalog default.

Show properties

avatar_idstring

min length 1

bg_idstring

min length 1

provider_configobjectrequired

Per-session ephemeral provider credentials. Only the key matching `provider_type` may be populated; setting multiple keys is a 400. All values are held in process memory only for the session lifetime and are zeroed on session end. Never persisted to the database, KV, R2, DO storage, files, env vars, logs, PostHog, request IDs, or error messages.

Show properties

Any of:

object

openai_realtimeobjectrequired

Show properties

client_secretstringrequired

Ephemeral OpenAI Realtime client secret minted by the customer backend (e.g. `ek_...`). Held in memory only for the session lifetime.

min length 1

object

cartesiaobjectrequired

Show properties

access_tokenstringrequired

Short-lived Cartesia access token minted by the customer backend with an `agent` grant. Held in memory only.

min length 1

agent_idstringrequired

Cartesia agent identifier paired with the `access_token`.

min length 1

object

external_engineobjectrequired

Show properties

auth_headersobjectrequired

Per-session authentication header dictionary sent on every engine request. Held in Gateway process memory ONLY for the session lifetime; never persisted.

urlstring<uri>required

External engine endpoint URL (`wss://`). Must implement the AVTR V0 External Conversation Engine Protocol (see docs/EXTERNAL_ENGINE_PROTOCOL.md).

matches ^wss:\/\/

user_sample_rateinteger

Declared sample rate (Hz) for PCM16LE audio frames the Gateway sends to the engine. Defaults to 24000.

object

elevenlabsobjectrequired

Show properties

agent_idstringrequired

ElevenLabs Conversational AI agent identifier. For public agents, this is placed in the WebSocket URL query string (no secret). For private agents, pair with `signed_url`.

min length 1

api_keystring

Server-side ElevenLabs API key. Used by the customer backend to mint a signed URL for private agents. For public agents, this is not needed. Held in Gateway process memory ONLY for the session lifetime; never persisted, never placed in the WebSocket URL or logs.

min length 1

signed_urlstring<uri>

Pre-minted signed URL for private agents (already contains the conversation_signature token, valid 15 min). Must be a wss:// URL on an ElevenLabs ConvAI host (api.elevenlabs.io or api.{us,eu.residency,in.residency,sg.residency}.elevenlabs.io) with the /v1/convai/conversation path. When provided, the Gateway uses this URL directly instead of building one from `agent_id`. Held in memory only.

provider_typestringrequired

The conversation engine for this session. Exactly one value must be set, and the matching key inside `provider_config` must be populated. Setting a different provider's key is a 400. - `openai_realtime` — OpenAI Realtime API (ephemeral `client_secret` flow). - `cartesia` — Cartesia Line agent WebSocket (short-lived `access_token` + `agent_id`). - `external_engine` — customer-provided `wss://` endpoint (strict V0 External Conversation Engine Protocol). - `elevenlabs` — ElevenLabs Conversational AI agent WebSocket (`agent_id`; optional server-side `api_key` for signed URL minting).

Allowed:openai_realtimecartesiaexternal_engineelevenlabs

transportstring

Transport preference for this session. `auto` — server picks (prefers SFU when configured, falls back to fMP4). `webrtc_sfu` — Cloudflare Realtime SFU (WebRTC); fails closed if the SFU prerequisites are missing, does NOT fall back to fMP4. `websocket_fmp4` — fMP4 over WebSocket (compatibility transport).

default: "auto"

Allowed:autowebrtc_sfuwebsocket_fmp4

webhook_urlstring<uri>

HTTPS webhook URL for session lifecycle callbacks. Optional; when set, AVTR POSTs session lifecycle events to this URL.

matches ^https:\/\/

Responses

200Session created and started.

client_tokenstringrequired

Short-lived (5-minute) HMAC-signed client token authorizing media-plane connections. Returned EXACTLY ONCE at session creation; use `POST /v1/sessions/{session_id}/client-token` to refresh. NEVER appears in GET responses.

min length 1

expires_atinteger<int64>required

Unix epoch milliseconds when the `client_token` expires.

min 0

session_idstringrequired

Session identifier (always prefixed with `session:`).

min length 1 · matches ^session:[A-Za-z0-9_-]+$

statusstringrequired

Session lifecycle status.

Allowed:createdactivatingactiveendingendedended_with_warningsfailed

stream_metadataobjectrequired

Media-plane connection metadata.

Show properties

ice_serversobject[]required

ICE servers the browser should use when negotiating a WebRTC transport. May be empty for `websocket_fmp4` sessions.

Show properties

Array of object

credentialstring

TURN credential (only for `turn:` servers).

urlsstring<uri> | string<uri>[]required

STUN/TURN URL or list of URLs (per RFC 7065). Example: `stun:stun.l.google.com:19302`.

Show properties

Any of:

string<uri>

string<uri>

string<uri>[]

Array of string<uri>

string<uri>

usernamestring

TURN username (only for `turn:` servers).

session_tokenstringrequired

Purpose-scoped session token used to authorize media-plane connections (WebSocket or SFU subscriber). Distinct from the API key.

min length 1

sfu_endpointstring<uri> | nullrequired

Cloudflare Realtime SFU publisher endpoint. `null` when the session is using the `websocket_fmp4` transport.

transportstringrequired

Allowed:autowebrtc_sfuwebsocket_fmp4

400Invalid request body, unknown `provider_type`, mismatched `provider_config`, or rejected `provider_connection_id`.

Any of:

object

codestringrequired

Allowed:AVTR_PROVIDER_DOWNSTREAM_FAILEDAVTR_PROVIDER_TIMEOUTAVTR_PROVIDER_UNAVAILABLEAVTR_RATE_LIMIT_CONCURRENT_SESSIONSAVTR_RATE_LIMIT_EXCEEDEDAVTR_RATE_LIMIT_PROVIDER_QUOTAAVTR_RENDER_CAPACITYAVTR_RENDER_TIMEOUTAVTR_SESSION_STATE_UNAVAILABLEAVTR_SFU_CONNECTION_FAILEDAVTR_SFU_NEGOTIATION_FAILEDAVTR_SFU_ROOM_FULL

doc_urlstring<uri>required

Absolute HTTPS URL to human-facing documentation for this error code.

matches ^https:\/\/

messagestringrequired

Human-readable, provider-agnostic error message. MUST NOT contain provider names, model ids, infrastructure identifiers (Modal/D1/DO), IP addresses, stack traces, or API keys. Consumers MAY localize.

min length 1

request_idstring<uuid>required

Per-request correlation UUID. Echoes the `X-Request-Id` response header. Used to locate traces and logs.

retry_afterintegerrequired

Seconds the client SHOULD wait before retrying (1..3600). REQUIRED for retryable codes; FORBIDDEN for non-retryable codes. Clients SHOULD honor this value and SHOULD apply jitter.

min 1 · max 3600

object

codestringrequired

Allowed:AVTR_AUTH_EXPIRED_TOKENAVTR_AUTH_FORBIDDENAVTR_AUTH_INVALID_KEYAVTR_AUTH_MISSING_CREDENTIALSAVTR_AUTH_MISSING_SCOPEAVTR_PROVIDER_MISCONFIGUREDAVTR_RENDER_FAILEDAVTR_RENDER_MISCONFIGUREDAVTR_SESSION_CANCELLEDAVTR_SESSION_CONFLICTAVTR_SESSION_ENDEDAVTR_SESSION_NOT_FOUNDAVTR_SFU_NOT_CONFIGURED

doc_urlstring<uri>required

Absolute HTTPS URL to human-facing documentation for this error code.

matches ^https:\/\/

messagestringrequired

Human-readable, provider-agnostic error message. MUST NOT contain provider names, model ids, infrastructure identifiers (Modal/D1/DO), IP addresses, stack traces, or API keys. Consumers MAY localize.

min length 1

request_idstring<uuid>required

Per-request correlation UUID. Echoes the `X-Request-Id` response header. Used to locate traces and logs.

401API key missing or invalid.

Any of:

object

codestringrequired

doc_urlstring<uri>required

Absolute HTTPS URL to human-facing documentation for this error code.

matches ^https:\/\/

messagestringrequired

Human-readable, provider-agnostic error message. MUST NOT contain provider names, model ids, infrastructure identifiers (Modal/D1/DO), IP addresses, stack traces, or API keys. Consumers MAY localize.

min length 1

request_idstring<uuid>required

Per-request correlation UUID. Echoes the `X-Request-Id` response header. Used to locate traces and logs.

retry_afterintegerrequired

Seconds the client SHOULD wait before retrying (1..3600). REQUIRED for retryable codes; FORBIDDEN for non-retryable codes. Clients SHOULD honor this value and SHOULD apply jitter.

min 1 · max 3600

object

codestringrequired

doc_urlstring<uri>required

Absolute HTTPS URL to human-facing documentation for this error code.

matches ^https:\/\/

messagestringrequired

Human-readable, provider-agnostic error message. MUST NOT contain provider names, model ids, infrastructure identifiers (Modal/D1/DO), IP addresses, stack traces, or API keys. Consumers MAY localize.

min length 1

request_idstring<uuid>required

Per-request correlation UUID. Echoes the `X-Request-Id` response header. Used to locate traces and logs.

403Missing `sessions:write` scope.

Any of:

object

codestringrequired

doc_urlstring<uri>required

Absolute HTTPS URL to human-facing documentation for this error code.

matches ^https:\/\/

messagestringrequired

Human-readable, provider-agnostic error message. MUST NOT contain provider names, model ids, infrastructure identifiers (Modal/D1/DO), IP addresses, stack traces, or API keys. Consumers MAY localize.

min length 1

request_idstring<uuid>required

Per-request correlation UUID. Echoes the `X-Request-Id` response header. Used to locate traces and logs.

retry_afterintegerrequired

Seconds the client SHOULD wait before retrying (1..3600). REQUIRED for retryable codes; FORBIDDEN for non-retryable codes. Clients SHOULD honor this value and SHOULD apply jitter.

min 1 · max 3600

object

codestringrequired

doc_urlstring<uri>required

Absolute HTTPS URL to human-facing documentation for this error code.

matches ^https:\/\/

messagestringrequired

Human-readable, provider-agnostic error message. MUST NOT contain provider names, model ids, infrastructure identifiers (Modal/D1/DO), IP addresses, stack traces, or API keys. Consumers MAY localize.

min length 1

request_idstring<uuid>required

Per-request correlation UUID. Echoes the `X-Request-Id` response header. Used to locate traces and logs.

429Rate limit exceeded.

Any of:

object

codestringrequired

doc_urlstring<uri>required

Absolute HTTPS URL to human-facing documentation for this error code.

matches ^https:\/\/

messagestringrequired

Human-readable, provider-agnostic error message. MUST NOT contain provider names, model ids, infrastructure identifiers (Modal/D1/DO), IP addresses, stack traces, or API keys. Consumers MAY localize.

min length 1

request_idstring<uuid>required

Per-request correlation UUID. Echoes the `X-Request-Id` response header. Used to locate traces and logs.

retry_afterintegerrequired

Seconds the client SHOULD wait before retrying (1..3600). REQUIRED for retryable codes; FORBIDDEN for non-retryable codes. Clients SHOULD honor this value and SHOULD apply jitter.

min 1 · max 3600

object

codestringrequired

doc_urlstring<uri>required

Absolute HTTPS URL to human-facing documentation for this error code.

matches ^https:\/\/

messagestringrequired

Human-readable, provider-agnostic error message. MUST NOT contain provider names, model ids, infrastructure identifiers (Modal/D1/DO), IP addresses, stack traces, or API keys. Consumers MAY localize.

min length 1

request_idstring<uuid>required

Per-request correlation UUID. Echoes the `X-Request-Id` response header. Used to locate traces and logs.

502Upstream provider returned an error or downstream failed during session start.

Any of:

object

codestringrequired

doc_urlstring<uri>required

Absolute HTTPS URL to human-facing documentation for this error code.

matches ^https:\/\/

messagestringrequired

Human-readable, provider-agnostic error message. MUST NOT contain provider names, model ids, infrastructure identifiers (Modal/D1/DO), IP addresses, stack traces, or API keys. Consumers MAY localize.

min length 1

request_idstring<uuid>required

Per-request correlation UUID. Echoes the `X-Request-Id` response header. Used to locate traces and logs.

retry_afterintegerrequired

Seconds the client SHOULD wait before retrying (1..3600). REQUIRED for retryable codes; FORBIDDEN for non-retryable codes. Clients SHOULD honor this value and SHOULD apply jitter.

min 1 · max 3600

object

codestringrequired

doc_urlstring<uri>required

Absolute HTTPS URL to human-facing documentation for this error code.

matches ^https:\/\/

messagestringrequired

Human-readable, provider-agnostic error message. MUST NOT contain provider names, model ids, infrastructure identifiers (Modal/D1/DO), IP addresses, stack traces, or API keys. Consumers MAY localize.

min length 1

request_idstring<uuid>required

Per-request correlation UUID. Echoes the `X-Request-Id` response header. Used to locate traces and logs.

503Provider unavailable, session state unavailable, or capacity exhausted.

Any of:

object

codestringrequired

doc_urlstring<uri>required

Absolute HTTPS URL to human-facing documentation for this error code.

matches ^https:\/\/

messagestringrequired

Human-readable, provider-agnostic error message. MUST NOT contain provider names, model ids, infrastructure identifiers (Modal/D1/DO), IP addresses, stack traces, or API keys. Consumers MAY localize.

min length 1

request_idstring<uuid>required

Per-request correlation UUID. Echoes the `X-Request-Id` response header. Used to locate traces and logs.

retry_afterintegerrequired

Seconds the client SHOULD wait before retrying (1..3600). REQUIRED for retryable codes; FORBIDDEN for non-retryable codes. Clients SHOULD honor this value and SHOULD apply jitter.

min 1 · max 3600

object

codestringrequired

doc_urlstring<uri>required

Absolute HTTPS URL to human-facing documentation for this error code.

matches ^https:\/\/

messagestringrequired

Human-readable, provider-agnostic error message. MUST NOT contain provider names, model ids, infrastructure identifiers (Modal/D1/DO), IP addresses, stack traces, or API keys. Consumers MAY localize.

min length 1

request_idstring<uuid>required

Per-request correlation UUID. Echoes the `X-Request-Id` response header. Used to locate traces and logs.

504Provider or render timeout during session start.

Any of:

object

codestringrequired

doc_urlstring<uri>required

Absolute HTTPS URL to human-facing documentation for this error code.

matches ^https:\/\/

messagestringrequired

Human-readable, provider-agnostic error message. MUST NOT contain provider names, model ids, infrastructure identifiers (Modal/D1/DO), IP addresses, stack traces, or API keys. Consumers MAY localize.

min length 1

request_idstring<uuid>required

Per-request correlation UUID. Echoes the `X-Request-Id` response header. Used to locate traces and logs.

retry_afterintegerrequired

Seconds the client SHOULD wait before retrying (1..3600). REQUIRED for retryable codes; FORBIDDEN for non-retryable codes. Clients SHOULD honor this value and SHOULD apply jitter.

min 1 · max 3600

object

codestringrequired

doc_urlstring<uri>required

Absolute HTTPS URL to human-facing documentation for this error code.

matches ^https:\/\/

messagestringrequired

Human-readable, provider-agnostic error message. MUST NOT contain provider names, model ids, infrastructure identifiers (Modal/D1/DO), IP addresses, stack traces, or API keys. Consumers MAY localize.

min length 1

request_idstring<uuid>required

Per-request correlation UUID. Echoes the `X-Request-Id` response header. Used to locate traces and logs.

Try it

Server

Base URLCustom base URLOverrides the selected server when set.

Authorization

Bearer tokenRemember on this deviceInclude my values in samples

Bodyapplication/json

Request body

Request

curl -X POST "https://api.avtr.internal/v1/v1/sessions" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "avatar_config": {
    "avatar_id": "string",
    "bg_id": "string"
  },
  "provider_config": {
    "openai_realtime": {
      "client_secret": "string"
    }
  },
  "provider_type": "openai_realtime",
  "transport": "auto",
  "webhook_url": "http://example.com"
}'

const response = await fetch("https://api.avtr.internal/v1/v1/sessions", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "avatar_config": {
    "avatar_id": "string",
    "bg_id": "string"
  },
  "provider_config": {
    "openai_realtime": {
      "client_secret": "string"
    }
  },
  "provider_type": "openai_realtime",
  "transport": "auto",
  "webhook_url": "http://example.com"
})
});

import requests

response = requests.post(
    "https://api.avtr.internal/v1/v1/sessions",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Content-Type": "application/json"
    },
    json={
  "avatar_config": {
    "avatar_id": "string",
    "bg_id": "string"
  },
  "provider_config": {
    "openai_realtime": {
      "client_secret": "string"
    }
  },
  "provider_type": "openai_realtime",
  "transport": "auto",
  "webhook_url": "http://example.com"
},
)

Response

{
  "client_token": "string",
  "expires_at": 0,
  "session_id": "session:02732348-1350-413a-9f0c-d6f47210b417",
  "status": "created",
  "stream_metadata": {
    "ice_servers": [
      {
        "credential": "string",
        "urls": "http://example.com",
        "username": "string"
      }
    ],
    "session_token": "string",
    "sfu_endpoint": "http://example.com"
  },
  "transport": "auto"
}

{
  "code": "AVTR_PROVIDER_DOWNSTREAM_FAILED",
  "doc_url": "http://example.com",
  "message": "string",
  "request_id": "266ea41d-adf5-480b-af50-15b940c2b846",
  "retry_after": 1
}

{
  "code": "AVTR_PROVIDER_DOWNSTREAM_FAILED",
  "doc_url": "http://example.com",
  "message": "string",
  "request_id": "266ea41d-adf5-480b-af50-15b940c2b846",
  "retry_after": 1
}

{
  "code": "AVTR_PROVIDER_DOWNSTREAM_FAILED",
  "doc_url": "http://example.com",
  "message": "string",
  "request_id": "266ea41d-adf5-480b-af50-15b940c2b846",
  "retry_after": 1
}

{
  "code": "AVTR_PROVIDER_DOWNSTREAM_FAILED",
  "doc_url": "http://example.com",
  "message": "string",
  "request_id": "266ea41d-adf5-480b-af50-15b940c2b846",
  "retry_after": 1
}

{
  "code": "AVTR_PROVIDER_DOWNSTREAM_FAILED",
  "doc_url": "http://example.com",
  "message": "string",
  "request_id": "266ea41d-adf5-480b-af50-15b940c2b846",
  "retry_after": 1
}

{
  "code": "AVTR_PROVIDER_DOWNSTREAM_FAILED",
  "doc_url": "http://example.com",
  "message": "string",
  "request_id": "266ea41d-adf5-480b-af50-15b940c2b846",
  "retry_after": 1
}

{
  "code": "AVTR_PROVIDER_DOWNSTREAM_FAILED",
  "doc_url": "http://example.com",
  "message": "string",
  "request_id": "266ea41d-adf5-480b-af50-15b940c2b846",
  "retry_after": 1
}