Sessions

POST /v1/sessions

Mint a Session Launch using a developer API key. Server-to-server only — preferred when you have a backend. See Server sessions.

Request

POST https://api.liforma.ai/v1/sessions
Authorization: Bearer YOUR_API_KEY
Idempotency-Key: optional-unique-key
Content-Type: application/json

{
"experienceId": "exp_t0i7acmq",
"locale": "en-GB",
"mode": "presenter",
"speechInputMode": "manual",
"speechOnly": false
}

Response `201`

SessionLaunchResponse — same shape as browser sessions. Header: Cache-Control: no-store, private.

Authentication

Authorization: Bearer <developer_api_key> ( lfm_test_… or lfm_live_…; requires scope sessions:create). Never expose API keys to the browser.

Optional Idempotency-Key (max 256 characters; longer values → 400 IDEMPOTENCY_KEY_INVALID): same key + same body replays the prior launch; same key + different body → 409 IDEMPOTENCY_CONFLICT; same key still pending → 409 IDEMPOTENCY_IN_PROGRESS with Retry-After: 1. Branch on error.code, not HTTP 409 alone.

Parameters

Field	Required	Description
`experienceId`	Yes	Experience to launch
`locale`	No	Primary / user language (BCP 47, e.g. `en-GB`)
`secondaryLocale`	No*	Dual: paired / learning language. Non-dual Match: immerses the session in this language (wins over `locale`).
`learningLocale`	No	Alias of `secondaryLocale` (language-learning apps)
`mode`	No	`conversation` or `presenter`
`speechInputMode`	No	`auto`, `manual`, or `off`
`runtimeContext`	No	Session JSON for prompts and the opening template. Prefer this for personalization. Legacy `variables` is still accepted and is not injected into prompts.
`speechOnly`	No	When `true`, mint a voice-only session (no avatar capability / location scene)

Required for dual experiences when the paired/learning language is Match in Studio. See Browser Sessions for the same locale contract.

Player chrome (startButton, closeButton, returnUrl, fit) belongs on SDK attach / component props — not on this request.

Machine-readable contract: /openapi/sessions.json.

Example

curl -X POST https://api.liforma.ai/v1/sessions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"experienceId": "exp_t0i7acmq"}'

GET /v1/sessions/{sessionId}

Read a persisted runtime session (API key, scope sessions:read). Returns status, timestamps, and stub usage: { seconds: 0 } until metering ships.

POST /v1/sessions/{sessionId}/end

Mark a session ended (API key, scope sessions:create). Sets status: ended and endedAt.