ANanam
Engine

create engine session

Changed on

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.
post/v1/engine/session

Request

  • Base URL
    https://api.anam.ai
  • URL
    https://api.anam.ai/v1/engine/session
  • Auth
    HTTP bearer

Request body

clientLabelstring

Label for the session, recorded for usage attribution. API-key auth only.

personaConfigobject

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.

clientMetadataobject

Optional client metadata forwarded to the engine (e.g. supportsPubSubSignalling).

Example request

{
  "sessionOptions": {
    "sessionReplay": {
      "enableSessionReplay": true
    },
    "dataRetention": {
      "transcripts": true
    },
    "videoQuality": "high",
    "showAIAvatarDisclosure": true,
    "videoWidth": 1152,
    "videoHeight": 768,
    "egress": {
      "mode": "daily",
      "daily": {
        "roomUrl": "https://your-domain.daily.co/avatar-room"
      }
    }
  }
}

Response

Session started

sessionIdstring uuid
engineHoststring

Host of the engine serving this session. Omitted for LiveKit/Agora integrations.

engineProtocolstring
signallingEndpointstring
clientConfigobject
region'eu' | 'us'

Actual region that served the session. Omitted when the serving session-service does not report it.

Changes

  • e85ef0cd491eRevision changes
    • info

      added the media type application/json for the response with the status

  • 2dffa737c11aRevision changes
    • info

      added the new optional request property /

    • info

      added the new optional request property /

    • info

      added the new optional request property /

    • info

      added the new optional request property /

    • info

      added the new optional request property /

    • info

      added the new optional request property /

    • info

      added the new optional request property /