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 optionalclientMetadata. 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-tokenbody (personaConfig,environment,sessionOptions, plus optionalclientLabelandclientMetadata;expiresInandwidgetConfigdo 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.
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
Label for the session, recorded for usage attribution. API-key auth only.
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.
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).
Optional environment configuration (e.g. LiveKit settings). API-key auth only.
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.
Optional client metadata forwarded to the engine (e.g. supportsPubSubSignalling).
Response
Session started
Host of the engine serving this session. Omitted for LiveKit/Agora integrations.
Actual region that served the session. Omitted when the serving session-service does not report it.
eu, us 
