---
title: "create engine session"
method: POST
path: "/v1/engine/session"
tags: ["Engine"]
---

# create engine session

`POST /v1/engine/session`

Start a live persona session.

Two authentication modes are supported via the `Authorization: Bearer` header:

- **Session token** (browser clients): pass a session token minted by `POST /v1/auth/session-token`.
  The session configuration was bound to the token when it was created, so the body only carries
  optional `clientMetadata`. This is the flow the client-side SDKs use; you normally don't call
  this endpoint yourself.
- **API key** (server-side SDKs): pass your API key directly and supply the session configuration
  in the request body — the same shape as the `/v1/auth/session-token` body (`personaConfig`,
  `environment`, `sessionOptions`, plus optional `clientLabel` and `clientMetadata`; `expiresIn`
  and `widgetConfig` do not apply). This skips the session-token exchange. Only use this from a
  secure server-side context — never expose an API key in a browser.

## Request body

- object
  - `clientLabel` string — Label for the session, recorded for usage attribution. API-key auth only.
  - `personaConfig` object — Session persona configuration (API-key auth only). Same shape as the `/v1/auth/session-token` request: supply `personaId` for a persona you've already created, or `avatarId`/`voiceId`/`llmId`/`systemPrompt` for an ephemeral persona. Inline `tools` are supported; each client/webhook tool's `parameters` (and webhook `queryParameters`) JSON Schema must serialize to 10,000 bytes or less (UTF-8).
  - `environment` object — Optional environment configuration (e.g. LiveKit settings). API-key auth only.
  - `sessionOptions` object — Optional session options for API-key-authenticated session creation, including session replay, video quality/dimensions, AI avatar disclosure, egress, and engine-region routing. For session-token authentication, configure these options when creating the token.
    - `region` 'eu' | 'us' — Requested engine region. Explicit selection works even when automatic geographic routing is disabled.
    - `regionPolicy` 'preferred' | 'strict' — `preferred` allows cross-region capacity failover. `strict` requires `region` and never serves the session from another region.
  - `clientMetadata` object — Optional client metadata forwarded to the engine (e.g. supportsPubSubSignalling).

## Response `200`

Session started

- object
  - `sessionId` string, uuid
  - `engineHost` string — Host of the engine serving this session. Omitted for LiveKit/Agora integrations.
  - `engineProtocol` string
  - `signallingEndpoint` string
  - `clientConfig` object
  - `region` 'eu' | 'us' — Actual region that served the session. Omitted when the serving session-service does not report it.

## Other responses

- `400` — Invalid request body or persona configuration, including a ZDR request whose selected voice or LLM is incompatible, whose compatibility cannot be verified, or that enables session replay. Region values must be `eu` or `us`, and `regionPolicy: strict` requires an explicit `region`.
- `401` — Unauthorized - invalid API key, or invalid/expired session token
- `403` — Forbidden - the API key lacks the required permission, or the organization is not entitled to a requested feature (e.g. Zero Data Retention, session region selection, gated avatar model, devSettings)
- `429` — Concurrent session limit or spend cap reached
- `503` — No engines available. For `regionPolicy: strict`, this also means the requested region is unavailable or has no remaining capacity; the session is not retried in another region.

---

[API](https://skmtc.net/anam/apis/anam-ai-api.md) · [All operations](https://skmtc.net/anam/apis/anam-ai-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/anam/anam-ai-api/revisions/67afd1c5db59/schema)