Concepts
Core ideas behind the Liforma platform.
The mental model
Experience
↓
published ExperienceRevision
↓
Session Launch
↓
SDK You configure an Experience. Publishing freezes a revision. Each mint returns a Session Launch (session + opaque launch). The SDK runs the session.
You integrate at the Experience level — not at tokens, HTTP routes, or player endpoints.
Experience
An Experience is your reusable product configuration, identified by exp_…. It
defines who appears, how they behave, and what they can do.
- Characters — who appears (agent + avatar + voice)
- World — rules and context for the session
- Location — where the scene takes place
- State — structured facts that update during the session
- Tools — controlled capabilities the character can invoke
Session
A Session is one live runtime instance — one user opening your experience, one conversation, one playthrough. Sessions are short-lived and scoped.
Session Launch
When a session starts, the API returns a SessionLaunchResponse: a minimal
public session object plus an opaque launch string for the player.
Do not parse launch.
Most developers never inspect the response details. The SDK consumes it automatically. See Session Launch.
How sessions are authorized (mint auth)
There are two ways to start a session:
| Mint path | How it works | When |
|---|---|---|
| Server sessions (API key) | Your backend calls POST /v1/sessions; key never hits the browser | Preferred when you have a server — per-user context, tighter control |
| Browser embeds (origins) | SDK calls the browser mint endpoint; Liforma checks the page Origin against your allowlist | Client-only apps with no backend |
Allowed origins stop third parties from embedding your experience on websites you did not approve — so they cannot burn your paid minutes.
Character
A Character is an entity inside an experience — the combination of conversational agent, visual avatar, and voice. A simple tutor has one character; richer experiences can have several.
Transport
Transport is how the player connects to the Liforma runtime. It is sealed inside opaque launch and hidden from integrators. You never configure HTTP
routes, WebSockets, or LiveKit rooms.
Catalog vs session mint
Creators manage human-friendly slug values and gallery ordering in Studio. Your app
fetches the project catalog server-side, links by slug, and still mints sessions with experienceId.
See Build a Dynamic Experience Gallery and Experience Catalog API.
Tool
A Tool is a controlled external capability — look up a score, advance a quest, fetch account data. Tools are declared on the experience and invoked by the character. Your app observes results via events and state updates, not by calling tool HTTP endpoints directly.
Event
Events are the SDK's way of reporting what happened — new messages, activityChange (idle / listening / thinking / speaking), and speech boundaries.
Subscribe with experience.on(…).
See Listen to Events.
IDs are not secret
Experience IDs (exp_…) are public identifiers, like YouTube video IDs. Security
comes from origin allowlists, session tokens, quotas, and API keys — not ID secrecy.