liforma docs

Session Launch

The per-launch public contract between the API and the SDK.

What is a Session Launch?

Both mint endpoints return a SessionLaunchResponse — not a full runtime configuration document:

  • session — minimal public facts (id, experience, revision, expiry, locale, mode, capabilities)
  • launch — asymmetrically signed opaque bootstrap for @liforma/client / player.liforma.ai

Do I need to parse launch?

No. The SDK and player consume launch automatically. Do not parse it — its structure is unsupported and may change. Opaque means contract boundary, not a promise that page JavaScript cannot inspect the bytes.

Example response

session-launch.json
{
  "session": {
    "id": "sess_…",
    "experienceId": "exp_…",
    "experienceRevisionId": "…",
    "expiresAt": "2026-08-11T12:30:00.000Z",
    "locale": "en-GB",
    "secondaryLocale": "fr-FR",
    "mode": "conversation",
    "status": "active",
    "capabilities": {
      "speech": { "input": true, "output": true, "externalAudio": false },
      "conversation": { "managed": true },
      "avatar": { "enabled": true },
      "tools": { "enabled": false }
    }
  },
  "launch": "eyJ…"
}

Public session fields

FieldPurpose
idSession id (sess_…)
experienceIdExperience being run
experienceRevisionIdPublished revision this session runs
expiresAtISO 8601 expiry
localeResolved primary / user language (BCP 47)
secondaryLocalePaired / learning language when dual; omitted for plain sessions
modeconversation or presenter
capabilitiesAvatar, speech I/O, tools, external audio flags

Transport, pipeline, renderer, characters, and credentials live only inside opaque launch (private runtime bootstrap). Player chrome (startButton, returnUrl, …) is configured via SDK attach, not mint.

How launches are minted

EndpointAuth
POST /v1/browser-sessionsOrigin allowlist + browser embeds enabled
POST /v1/sessionsDeveloper API key

Both return 201 with the same SessionLaunchResponse shape and Cache-Control: no-store, private.