REST API
Every /v1 route — the server API your backend calls, embeds, viewer sessions, the conversation and voice — with the webhook events and the error codes, rendered from the OpenAPI document.
Overview
Version 1 of the API is additive only, forever: fields and values are added, never renamed, narrowed or removed, and every SDK of the last 24 months keeps working. Read answers tolerantly — ignore fields and values you do not know — and branch on the absence of a field, never on a version.
Errors come in one envelope, { error, message, details? }, whose error is one of the codes below (x-jami3d-error-codes); new codes are only ever added.
Your backend calls the Server API with a secret key. The Live Room player in the embed makes the session calls itself, with the viewer token the mint answers.
Download the OpenAPI 3.1.1 document (version 1)
Servers
https://api.jami.liveThe server API (secret keys).https://embed.jami.liveEmbeds: the Live Room's calls and the card.https://jami.livejami.live's own pages.
Authentication
- Viewer tokenThe viewer token of
POST /v1/sessions(ES256, verifiable with/.well-known/jwks.json): 15 minutes, renewed by the heartbeat. - Secret keyA secret key (
sk_live_…orsk_test_…), from your backend only: it is shown once when you create it.
Reference by group
Server API
What your backend calls with a secret key (
Authorization: Bearer sk_live_…): secure-embed grants, your projects, usage, learners' results and reports. Never from a browser: no CORS, never cached.Embeds
Public reads a page makes before anything plays: a project's card (the SDK's facade), oEmbed, and the keys viewer tokens are signed with.
Viewer sessions
The Live Room player's own calls, with the viewer token of
POST /v1/sessions. The player in the embed makes them for you; they are documented because/v1is a frozen contract.POST /v1/sessionsPOST /v1/sessions/{id}/heartbeatPOST /v1/sessions/{id}/verifyGET /v1/sessions/{id}/aiPOST /v1/sessions/{id}/eventsPOST /v1/sessions/{id}/rewindGET /v1/sessions/{id}/stateGET /v1/sessions/{id}/resultPOST /v1/sessions/{id}/telemetryPOST /v1/sessions/{id}/debug-logPOST /v1/sessions/{id}/reportsGET /v1/media/t/{token}/{path}
Conversation
Live AI: a question or an AI Line answered as an event stream, its cancel, the shared transcript, and the session-bound media links the events hand out.
Voice
Push-to-talk: the first Talk press, which joins the session's voice room, and the HTTPS fallback that transcribes a recorded question.
Webhooks
Events delivered to your endpoints: a signed JSON POST, retried at +1 min, +5 min, +30 min, +2 h, +6 h, +12 h, +24 h, +24 h, then dead. An endpoint failing for 3 days running is disabled and its owner told.
Error codes
Every error answers the same envelope — error, message and, for some codes, details — whose error is one of these codes. Codes are only ever added.
| Code | Status | Description |
|---|---|---|
quota_exceeded | — | Reserved for a quota refusal; no route answers it in this version. |
ai_unavailable | 403 | Live AI cannot serve this request now ( |
origin_not_allowed | 403 | The publishable key does not allow the calling page's origin (the request's |
release_not_found | 404 | Nothing playable here: no live release, a deleted or denylisted project, or one that cannot be embedded this way. |
session_expired | 401 | The session ended (8 hours after it began, or its access was withdrawn): start a new one. |
rate_limited | 429 | Too many requests: wait the seconds |
stale_epoch | 409 | A write carried an epoch older than the session's: a rewind happened since. |
seq_gap | 409 | Facts arrived with a gap in their sequence; the client resyncs before retrying. |
rewind_required | 409 | An append landed before the session's story cursor: rewind first. |
invalid_input | 400 | The request is not what the route takes; |
invalid_token | 401 | The viewer token is missing, malformed, or signed by a key this server does not trust. |
not_found | 404 | Nothing by that id for this caller — unknown, another session's, or a draft. |
scope_required | 403 | The viewer token lacks the scope this route needs. |
verification_failed | 403 | The human check (Turnstile) failed; playback goes on without live AI. |
key_invalid | 401 | The publishable key or viewer-token grant is unknown, revoked or expired. |
body_too_large | 413 | The request body is larger than the route accepts. |
unsupported_media_type | 415 | The request body is not JSON (telemetry also takes |
format_unsupported | 501 | OEmbed asked for a format other than JSON. |
retry_later | 503 | Something the route needs is unavailable for a moment; retry with backoff. |
internal_error | 500 | An unexpected failure (logged on the server). |