create engine session

curl --request POST \
  --url https://api.anam.ai/v1/engine/session \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "clientLabel": "<string>",
  "personaConfig": {},
  "environment": {},
  "sessionOptions": {},
  "clientMetadata": {}
}
'

{
  "sessionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "engineHost": "<string>",
  "engineProtocol": "<string>",
  "signallingEndpoint": "<string>",
  "clientConfig": {}
}

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.

POST

/

v1

/

engine

/

session

create engine session

curl --request POST \
  --url https://api.anam.ai/v1/engine/session \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "clientLabel": "<string>",
  "personaConfig": {},
  "environment": {},
  "sessionOptions": {},
  "clientMetadata": {}
}
'

{
  "sessionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "engineHost": "<string>",
  "engineProtocol": "<string>",
  "signallingEndpoint": "<string>",
  "clientConfig": {}
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

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.

environment

object

Optional environment configuration (e.g. LiveKit settings). API-key auth only.

sessionOptions

object

Optional session options (session replay, video quality/dimensions, egress). API-key auth only.

clientMetadata

object

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

Response

Session started

sessionId

string<uuid>

engineHost

string

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

engineProtocol

string

signallingEndpoint

string

clientConfig

object

Last modified on July 6, 2026

delete share link

⌘I