> ## 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: 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.
                environment:
                  type: object
                  description: >-
                    Optional environment configuration (e.g. LiveKit settings).
                    API-key auth only.
                sessionOptions:
                  type: object
                  description: >-
                    Optional session options (session replay, video
                    quality/dimensions, egress). API-key auth only.
                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
        '400':
          description: Invalid request body or persona configuration
        '401':
          description: Unauthorized - invalid API key, or invalid/expired session token
        '403':
          description: >-
            Forbidden - the organization is not entitled to a requested feature
            (e.g. gated avatar model, devSettings)
        '429':
          description: Concurrent session limit or spend cap reached
        '503':
          description: No engines available
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer

````