> ## Documentation Index > Fetch the complete documentation index at: https://anam.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # create 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. ## OpenAPI ````yaml https://api.anam.ai/swagger.json post /v1/engine/session openapi: 3.1.0 info: title: Anam AI API version: '1.0' servers: - url: https://api.anam.ai description: Anam API security: - BearerAuth: [] tags: - name: Sessions - name: Avatar Videos - name: Meetings - name: Personas - name: Avatars - name: Voices - name: LLMs - name: Knowledge - name: Tools - name: Share Links - name: Engine paths: /v1/engine/session: post: tags: - Engine summary: create engine session description: > 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. operationId: createEngineSession requestBody: required: false content: application/json: schema: type: object properties: clientLabel: type: string description: >- Label for the session, recorded for usage attribution. API-key auth only. personaConfig: type: object description: > 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. An avatar-only config (avatarId without voiceId and without enableAudioPassthrough: true) is only accepted together with a LiveKit, Agora or ElevenLabs Agent integration `environment`; on the default Anam WebRTC transport send an ephemeral config with voiceId and llmId (llmId "CUSTOMER_CLIENT_V1" for a client-side LLM) or set enableAudioPassthrough to true. Otherwise the request fails with 400 `avatar_only_requires_integration`. 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: type: object description: >- Optional environment configuration (e.g. LiveKit settings). API-key auth only. sessionOptions: type: object description: >- 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. properties: region: type: string enum: - eu - us description: >- Requested engine region. Explicit selection works even when automatic geographic routing is disabled. regionPolicy: type: string enum: - preferred - strict default: preferred description: >- `preferred` allows cross-region capacity failover. `strict` requires `region` and never serves the session from another region. clientMetadata: type: object description: >- Optional client metadata forwarded to the engine (e.g. supportsPubSubSignalling). responses: '200': description: Session started content: application/json: schema: type: object properties: sessionId: type: string format: uuid engineHost: type: string description: >- Host of the engine serving this session. Omitted for LiveKit/Agora integrations. engineProtocol: type: string signallingEndpoint: type: string clientConfig: type: object region: type: string enum: - eu - us description: >- Actual region that served the session. Omitted when the serving session-service does not report it. '400': description: >- 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`. Avatar-only persona configs (avatarId without voiceId and without enableAudioPassthrough: true) are rejected with `avatar_only_requires_integration` unless a LiveKit, Agora or ElevenLabs Agent integration `environment` is supplied. '401': description: Unauthorized - invalid API key, or invalid/expired session token '402': description: >- The organization has an overdue payment and paid access is temporarily restricted content: application/json: schema: type: object required: - error - message - recovery_url properties: error: type: string enum: - billing_payment_required message: type: string recovery_url: type: string format: uri example: error: billing_payment_required message: >- Your organization has an overdue payment. An owner can restore access from Billing. recovery_url: https://lab.anam.ai/subscription?billing=overdue '403': description: >- 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) content: application/json: schema: type: object required: - error properties: error: type: string message: type: string examples: sessionRegionNotAvailable: value: error: session_region_not_available message: >- Session region selection is not available for this organization '429': description: Concurrent session limit or spend cap reached '503': description: >- 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. components: securitySchemes: BearerAuth: type: http scheme: bearer ````