> ## 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`; `expiresInSeconds`, `maxSessions` 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: Pronunciation Dictionaries - 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`; `expiresInSeconds`, `maxSessions` 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`. Knowledge tools accept optional fixed `topK` (integer 1–100), `minScore` (number 0–1), `maxContextTokens` (integer 1–200,000; content only) and `neighborChunks` (integer 0–10, default 0) on each tool. Omit or set null to retain defaults. Invalid values return 400. 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). `voiceGenerationOptions.pronunciationDictionaryId` selects a pronunciation dictionary for the session (see `SessionPronunciationDictionary`); its latest saved entries are applied when the session starts. environment: type: object description: >- Optional environment configuration (e.g. LiveKit settings). API-key auth only. properties: livekitUrl: type: string description: >- Must be reachable from the public internet; loopback, private, link-local, reserved, documentation, cluster-internal, and single-label targets are rejected with HTTP 400. Use an absolute URL with an ASCII hostname (punycode for international names), canonical dotted-decimal IPv4, and a port from 1 to 65535 if specified. Hostnames must resolve only to public addresses; DNS is checked when the session starts. Temporary DNS failures are service errors (5xx), not invalid URL errors. sessionOptions: type: object description: >- Optional session options for API-key-authenticated session creation, including data retention (recording and transcripts), video quality/dimensions, AI avatar disclosure, egress, and engine-region routing. For session-token authentication, configure these options when creating the token. properties: sessionReplay: type: object deprecated: true description: >- Legacy control for both the recording and the transcript. Use dataRetention instead. It can be sent alongside dataRetention: enableSessionReplay false turns both off, and so does an empty sessionReplay object; enableSessionReplay true leaves each to dataRetention. properties: enableSessionReplay: type: boolean deprecated: true description: >- Record the session and store its transcript. false turns off both, the same as dataRetention with recording and transcripts set to false. Under Zero Data Retention, sending true without dataRetention returns HTTP 400; with dataRetention sent, omitted settings are off and only a dataRetention setting of true that this flag (false, or an empty sessionReplay) does not turn off is rejected. example: true default: true dataRetention: type: object additionalProperties: false description: >- Choose what Anam keeps after the session. Each setting is independent, so you can turn off the recording and keep the transcript, or the other way round. A sessionReplay sent alongside it with enableSessionReplay false, or with no value, turns both off. Zero Data Retention sessions keep neither: an omitted setting is off, and a setting of true returns HTTP 400 unless sessionReplay turns both off. Not supported for LiveKit or Agora sessions (HTTP 400). properties: recording: type: boolean description: >- Record the session video. When false, GET /v1/sessions/{id}/recording returns 404. With sessionOptions.egress mode daily the recording must resolve to off: set this to false, or set enableSessionReplay to false or send an empty sessionReplay. default: true example: false transcripts: type: boolean description: >- Store the conversation transcript. When false, GET /v1/sessions/{id}/transcript returns transcriptsEnabled false and each message reads TRANSCRIPTS_DISABLED. default: true example: true videoQuality: type: string enum: - high - auto description: >- 'high' pins highest bitrate, 'auto' enables adaptive bitrate. example: high showAIAvatarDisclosure: type: boolean description: >- Show the AI avatar disclosure during the session. Defaults to false; set true to opt in. Agora sessions ignore this field. example: true 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. videoWidth: type: integer description: >- Output video frame width in pixels. Supply together with `videoHeight` (both or neither). Omit to use the avatar model's default. Supported pairs depend on the avatar model — cara-3: `720x480`; cara-4: `1152x768`. Unsupported pairs are rejected (the session is not silently downgraded). example: 1152 videoHeight: type: integer description: >- Output video frame height in pixels. Supply together with `videoWidth` (both or neither). See `videoWidth`. example: 768 egress: type: object description: > Set egress to an alternative egress transport mode. The avatar's audio/video are published to a 3rd party transport and not delivered over the native webRTC channel. The WebRTC peer connection still exists for signalling and the data channel (interrupts, status). Requires `personaConfig.enableAudioPassthrough=true`. Discriminated on `mode`. required: - mode properties: mode: type: string enum: - daily description: Egress provider. Only `daily` is supported today. example: daily daily: type: object description: Required when `mode` is `daily`. required: - roomUrl properties: roomUrl: type: string format: uri description: >- Daily room URL the avatar should join as a publisher. example: https://your-domain.daily.co/avatar-room token: type: string description: >- Optional Daily meeting token. Omit for public rooms. userName: type: string description: >- Optional display name for the avatar participant. Defaults to "anam-avatar". 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, that sets dataRetention.recording or dataRetention.transcripts to true without a sessionReplay that turns both off, or that sets sessionReplay.enableSessionReplay to true without dataRetention. Omitted dataRetention settings are off for ZDR sessions. 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. An avatar with no engine key (one created without an image) is rejected with `avatar_unusable`. Deleting that avatar is not enough on its own: deletion is a soft delete, a replacement created with `imageUrl` gets a new `avatarId`, and saved personas keep referencing the old one. Point the session config or saved persona at a usable `avatarId` instead. Engine 400 and 422 rejections return 400 `invalid_session_config`. `message` carries the engine's customer-facing `invalid_request_body` reason, or a fixed message for other errors. Rejected field names are returned in `invalid_fields` when the engine reports them. content: application/json: schema: type: object properties: error: type: string message: type: string avatarId: type: string description: ID of the unusable avatar, when error is avatar_unusable. invalid_fields: type: array items: type: string description: >- Rejected field names, when error is invalid_session_config and the engine reports them. example: error: avatar_unusable message: >- Avatar avatar-1 has no engine key and cannot be used in a session. Choose a usable avatar, or create a replacement with imageUrl, then update your session configuration or saved persona to use its avatarId. The unusable avatar can be deleted once nothing references it. avatarId: avatar-1 '401': description: >- Unauthorized - invalid API key, invalid/expired session token, a session token whose API key has since been deactivated or deleted, or a session token that has already started as many sessions as its `maxSessions` allows (error `Session token already used`) '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), or the organization belongs to a Shopify store that is no longer connected to the Anam app 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 '404': description: >- A referenced resource does not exist in your organization, for example an unknown, archived or other-organization `voiceGenerationOptions.pronunciationDictionaryId`. `toolIds` that are unknown, deleted or another organization's are rejected with `tools_not_found`, listing them in `toolIds`. content: application/json: schema: type: object properties: error: type: string message: type: string toolIds: type: array items: type: string description: >- The requested tool IDs that were not found, when error is tools_not_found. example: error: tools_not_found message: >- Tools not found: f56eba79-5403-40e0-9b09-6ae6c4757e21. Remove them from personaConfig.toolIds, or use the IDs of tools that exist in your organization. toolIds: - f56eba79-5403-40e0-9b09-6ae6c4757e21 '409': description: >- The pronunciation dictionary can't be used. `DICTIONARY_UNAVAILABLE`: the saved persona's dictionary was removed; choose another for the persona and publish it. `DICTIONARY_OUTDATED`: the dictionary's saved entries no longer meet the current entry rules; fix and save it in Lab. content: application/json: schema: type: object properties: error: type: string message: type: string code: type: string enum: - DICTIONARY_UNAVAILABLE - DICTIONARY_OUTDATED '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. A strictly pinned token also gets 503 with `error: session_store_unavailable` when that region's session storage is temporarily unavailable. Also returned with a `Retry-After` header when the API key could not be checked because of a temporary server problem; the key may be valid, so retry. headers: Retry-After: description: >- Seconds to wait before retrying. Present when the API key could not be checked. schema: type: integer content: application/json: schema: type: object required: - error properties: error: type: string message: type: string components: securitySchemes: BearerAuth: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.