Skip to content
Jami3D
Developer docs menu

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_… or sk_test_…), from your backend only: it is shown once when you create it.

Reference by group

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.

CodeStatusDescription
quota_exceeded—

Reserved for a quota refusal; no route answers it in this version.

ai_unavailable403

Live AI cannot serve this request now (details.reason says why); playback goes on without it.

origin_not_allowed403

The publishable key does not allow the calling page's origin (the request's Origin).

release_not_found404

Nothing playable here: no live release, a deleted or denylisted project, or one that cannot be embedded this way.

session_expired401

The session ended (8 hours after it began, or its access was withdrawn): start a new one.

rate_limited429

Too many requests: wait the seconds details.retryAfter (and the Retry-After header) give.

stale_epoch409

A write carried an epoch older than the session's: a rewind happened since.

seq_gap409

Facts arrived with a gap in their sequence; the client resyncs before retrying.

rewind_required409

An append landed before the session's story cursor: rewind first.

invalid_input400

The request is not what the route takes; details names the fields.

invalid_token401

The viewer token is missing, malformed, or signed by a key this server does not trust.

not_found404

Nothing by that id for this caller — unknown, another session's, or a draft.

scope_required403

The viewer token lacks the scope this route needs.

verification_failed403

The human check (Turnstile) failed; playback goes on without live AI.

key_invalid401

The publishable key or viewer-token grant is unknown, revoked or expired.

body_too_large413

The request body is larger than the route accepts.

unsupported_media_type415

The request body is not JSON (telemetry also takes text/plain JSON).

format_unsupported501

OEmbed asked for a format other than JSON.

retry_later503

Something the route needs is unavailable for a moment; retry with backoff.

internal_error500

An unexpected failure (logged on the server).