Sign in

v4

latestOpenAPI 3.1.02026-08-086635375.7 KB
Engine

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

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. 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).

environmentobject

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

clientMetadataobject

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

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.