Skip to content
Jami3D
Developer docs menu

REST API: Server API

Every operation of this group with its parameters, body, answer and errors, as the OpenAPI document states them.

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.

Issue a secure-embed grant

POST/v1/viewer-tokensSecret key

Needs the key's sessions capability and a plan with secure embeds. A child-directed project also needs the key's consent attestation.

Request body (application/json)

FieldTypeDescription
projectIdRequiredstring (uuid)

A server-minted id (sessions, projects, releases, users): a UUID.

externalUserIdRequiredstring1–200 characters

The integrator's own id for the learner: printable text, no control characters.

ttlSecinteger60–3600 · default 600
caps("playback" | "text_ai" | "voice_ai" | "conversation_events")[]≤ 16 items

Response 201

Issue a secure-embed grant

FieldTypeDescription
viewerTokenRequiredstring≥ 1 characters

The single-use grant: createPlayer({viewerToken}), exchanged at POST /v1/sessions.

expiresAtRequiredstring (date-time)

Exchange it before this; a used or expired grant answers 401 key_invalid.

cardTokenRequiredstring≥ 1 characters

createPlayer({cardToken}): lets the facade read the project's card.

cardTokenExpiresAtRequiredstring (date-time)

An ISO 8601 instant.

capabilitiesRequiredstring[]

What the session will be allowed (the request's caps, playback always).

Errors

  • 400invalid_input
  • 401key_invalid
  • 403scope_required
  • 404not_found
  • 429rate_limited

List your projects

GET/v1/projectsSecret key

Needs the projects capability. A project-scoped key sees its projects only.

Parameters

NameInTypeDescription
limitqueryintegerDefault 50
cursorquerystring (uuid)

The last project id of the previous page (nextCursor).

Response 200

List your projects

FieldTypeDescription
projectsRequiredobject[]
projects[].idRequiredstring (uuid)

A server-minted id (sessions, projects, releases, users): a UUID.

projects[].titleRequiredstring
projects[].contentLanguageRequiredstring≤ 35 characters

A UI or reply language: a BCP 47 tag (en, pt-BR, zh-Hant-TW).

projects[].statusRequiredstring≥ 1 characters

active or archived.

projects[].liveRequiredobject | null

The release a new viewer gets; null before the first publish.

projects[].live.releaseIdRequiredstring (uuid)

A server-minted id (sessions, projects, releases, users): a UUID.

projects[].live.numberRequiredinteger0–9007199254740991
projects[].live.publishedAtRequiredstring (date-time) | null

An ISO 8601 instant.

projects[].embedRequiredobject
projects[].embed.policyRequiredstring≥ 1 characters

open (keys and keyless embeds) or secure_only (viewer-token grants only).

projects[].embed.allowKeylessRequiredboolean

Anyone may frame it without a key (the owner pays).

projects[].embed.urlRequiredstring≥ 1 characters

The embed document: https://embed.jami.live/p/{id}.

projects[].listingRequiredobject | null

Its marketplace listing, when it has one.

projects[].listing.slugRequiredstring≥ 1 characters
projects[].listing.visibilityRequiredstring≥ 1 characters

public, unlisted or private.

projects[].listing.allowEmbedRequiredboolean

Other accounts may embed it with their own keys.

projects[].listing.urlRequiredstring≥ 1 characters
projects[].createdAtRequiredstring (date-time)

An ISO 8601 instant.

projects[].updatedAtRequiredstring (date-time)

An ISO 8601 instant.

nextCursorstring (uuid)

Present when there are more: pass it as cursor.

Errors

  • 400invalid_input
  • 401key_invalid
  • 403scope_required

Read your usage

GET/v1/usageSecret key

Needs the usage capability. Amounts are integer millicredits from the hourly rollup.

Parameters

NameInTypeDescription
fromquerystring (date)

First UTC day (YYYY-MM-DD); absent: 29 days before to.

toquerystring (date)

Last UTC day, inclusive; absent: today.

groupByquery"day" | "project" | "key" | "surface" | "service"Default "day"

Response 200

Read your usage

FieldTypeDescription
fromRequiredstring (date)
toRequiredstring (date)
groupByRequiredstring≥ 1 characters
totalsRequiredobject

Amounts in integer MILLIcredits (1 credit = 1,000), exact over any range.

totals.eventsRequiredinteger0–9007199254740991

Paid calls (LLM, TTS, ASR, RTC, egress).

totals.creditsMilliRequiredinteger0–9007199254740991
totals.billableCreditsMilliRequiredinteger0–9007199254740991

The part charged to the account (test-key sessions are recorded but not billed).

groupsRequiredobject[]
groups[].eventsRequiredinteger0–9007199254740991

Paid calls (LLM, TTS, ASR, RTC, egress).

groups[].creditsMilliRequiredinteger0–9007199254740991
groups[].billableCreditsMilliRequiredinteger0–9007199254740991

The part charged to the account (test-key sessions are recorded but not billed).

groups[].keyRequiredstring | null

The day, project id, key id, surface or service; null: no project / no key.

balanceobject

The account's credits this period (an unscoped key only).

balance.periodStartRequiredstring (date-time)

An ISO 8601 instant.

balance.periodEndRequiredstring (date-time)

An ISO 8601 instant.

balance.allowanceMilliRequiredinteger0–9007199254740991
balance.usedMilliRequiredinteger0–9007199254740991
balance.availableMilliRequiredinteger-9007199254740991–9007199254740991
countedUntilRequiredstring (date-time) | null

Usage is folded hourly: everything before this instant is counted.

Errors

  • 400invalid_input
  • 401key_invalid
  • 403scope_required

List learners' results

GET/v1/resultsSecret key

Needs the results capability: the results of the sessions minted with your account's keys, newest change first.

Parameters

NameInTypeDescription
projectIdquerystring (uuid)

A server-minted id (sessions, projects, releases, users): a UUID.

externalUserIdquerystring

The integrator's own id for the learner: printable text, no control characters.

fromquerystring (date-time)

Results that changed at or after this instant.

toquerystring (date-time)

Results that changed before this instant.

limitqueryintegerDefault 50
cursorquerystring

The previous page's nextCursor.

Response 200

List learners' results

FieldTypeDescription
resultsRequiredobject[]
results[].sessionIdRequiredstring (uuid)

The story's latest session: the report is GET /v1/results/{sessionId}/report.

results[].projectIdRequiredstring (uuid)

A server-minted id (sessions, projects, releases, users): a UUID.

results[].releaseIdstring (uuid)

A server-minted id (sessions, projects, releases, users): a UUID.

results[].surfaceRequiredstring≥ 1 characters

embed or secure_embed.

results[].keyIdRequiredstring (uuid)

The key the session was minted with.

results[].testRequiredboolean

Minted with a test key.

results[].viewerRequiredone of

The learner: the integrator's own id for a secure embed's learner, else nobody by name.

When kind is “anonymous”
When kind is “external”
results[].viewer.externalUserIdRequiredstring≥ 1 characters
When kind is “account”
results[].viewer.userIdRequiredstring (uuid)

A server-minted id (sessions, projects, releases, users): a UUID.

results[].startedAtRequiredstring (date-time)

An ISO 8601 instant.

results[].updatedAtRequiredstring (date-time)

An ISO 8601 instant.

results[].completedAtstring (date-time)

When the story was completed; absent while it is not.

results[].completedRequiredboolean
results[].epochRequiredinteger0–9007199254740991

Grows with every rewind; a result is read as of its epoch.

results[].scoreRequirednumber≥ 0
results[].maxScoreRequirednumber≥ 0
results[].percentRequirednumber0–100

0–100, one decimal.

results[].passedboolean

Every quiz completed and passed; absent while a quiz is not completed.

results[].answeredCountRequiredinteger0–9007199254740991
results[].questionCountRequiredinteger0–9007199254740991
nextCursorstring≥ 1 characters

Present when there are more: pass it as cursor.

Errors

  • 400invalid_input
  • 401key_invalid
  • 403scope_required

Download a learner's report

GET/v1/results/{id}/reportSecret key

Needs the results capability. A session your account's keys did not mint answers 404.

Parameters

NameInTypeDescription
idRequiredpathstring

The result's sessionId.

formatquery"json" | "html" | "csv" | "docx" | "xlsx"Default "json"
templatequerystring

One of the project's report templates; absent: the default layout.

localequerystring

The report's language; absent: the session's.

Response 200

format=json: the session and its result as the viewer's own GET …/result gives them, and — only when the project lets reports carry the conversation, never for a project made for children, and only while its retention keeps it — the conversation.

FieldTypeDescription
sessionRequiredobject
session.idRequiredstring (uuid)

A server-minted id (sessions, projects, releases, users): a UUID.

session.projectIdRequiredstring (uuid)

A server-minted id (sessions, projects, releases, users): a UUID.

session.releaseIdstring (uuid)

The release played (a draft session has none).

session.titleRequiredstring
session.startedAtRequiredstring (date-time)

An ISO 8601 instant.

session.lastSeenAtRequiredstring (date-time)

An ISO 8601 instant.

session.durationMsRequiredinteger0–9007199254740991
resultRequiredobject
result.viewerRequiredone of

Who a result is about: nobody by name, a secure embed's learner, a signed-in account.

When kind is “anonymous”
When kind is “external”
result.viewer.externalUserIdRequiredstring≥ 1 characters
When kind is “account”
result.viewer.userIdRequiredstring (uuid)

A server-minted id (sessions, projects, releases, users): a UUID.

result.epochRequiredinteger0–9007199254740991
result.completedRequiredboolean
result.beatsRequiredobject[]
result.beats[].beatIdRequiredstring1–160 characters

An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is scene:{sceneId}), an entity, a behaviour, a rule, a variable, a quiz, a question, a choice.

result.beats[].aliasRequiredstring
result.beats[].nameRequiredstring
result.beats[].sceneIdRequiredstring1–160 characters

An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is scene:{sceneId}), an entity, a behaviour, a rule, a variable, a quiz, a question, a choice.

result.beats[].requiredRequiredboolean
result.beats[].statusRequiredstring≥ 1 characters

completed, skipped, visited or notVisited.

result.beats[].turnsRequiredinteger0–9007199254740991
result.quizzesRequiredobject[]
result.quizzes[].quizIdRequiredstring1–160 characters

An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is scene:{sceneId}), an entity, a behaviour, a rule, a variable, a quiz, a question, a choice.

result.quizzes[].aliasRequiredstring
result.quizzes[].titlestring
result.quizzes[].statusRequiredstring≥ 1 characters

completed, inProgress, skipped or notStarted.

result.quizzes[].scoreRequirednumber≥ 0
result.quizzes[].maxScoreRequirednumber≥ 0
result.quizzes[].percentRequirednumber0–100

0–100, one decimal.

result.quizzes[].passedboolean

Against the quiz's pass mark, once the quiz is completed.

result.quizzes[].correctCountRequiredinteger0–9007199254740991
result.quizzes[].questionsRequiredobject[]
result.quizzes[].questions[].questionIdRequiredstring1–160 characters

An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is scene:{sceneId}), an entity, a behaviour, a rule, a variable, a quiz, a question, a choice.

result.quizzes[].questions[].keyRequiredstring
result.quizzes[].questions[].promptstring
result.quizzes[].questions[].answeredRequiredboolean
result.quizzes[].questions[].correctRequiredboolean
result.quizzes[].questions[].pointsRequirednumber≥ 0
result.quizzes[].questions[].maxPointsRequirednumber≥ 0
result.quizzes[].questions[].attemptsRequiredinteger0–9007199254740991
result.quizzes[].questions[].responseone of

A response to one question: a choice (single, image choice), a set of choices (multi), true or false, or a typed answer. The server trims and bounds text itself (grading refuses an answer over 500 characters), so the wire allows some slack rather than failing a whole request.

When kind is “choice”
result.quizzes[].questions[].response.choiceIdRequiredstring1–160 characters

An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is scene:{sceneId}), an entity, a behaviour, a rule, a variable, a quiz, a question, a choice.

When kind is “choices”
result.quizzes[].questions[].response.choiceIdsRequiredstring[]1–10 items
When kind is “boolean”
result.quizzes[].questions[].response.valueRequiredboolean
When kind is “text”
result.quizzes[].questions[].response.textRequiredstring≤ 2000 characters
result.quizzes[].questions[].responseTextstring

The response in words: the chosen choices' text, true / false, the typed answer.

result.quizzes[].questions[].respondentone of

Who answers a quiz: the viewer, or the viewer playing a cast member ("as Cat").

When kind is “viewer”
When kind is “character”
result.quizzes[].questions[].respondent.castIdRequiredstring1–160 characters

An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is scene:{sceneId}), an entity, a behaviour, a rule, a variable, a quiz, a question, a choice.

result.variablesRequiredobject[]
result.variables[].variableIdRequiredstring1–160 characters

An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is scene:{sceneId}), an entity, a behaviour, a rule, a variable, a quiz, a question, a choice.

result.variables[].aliasRequiredstring
result.variables[].typeRequiredstring≥ 1 characters
result.variables[].valueRequiredboolean | number | string

A story value: a boolean, a number, or a short text (a choice is its key).

result.itemsRequiredobject[]
result.items[].resultIdRequiredstring1–160 characters

An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is scene:{sceneId}), an entity, a behaviour, a rule, a variable, a quiz, a question, a choice.

result.items[].aliasRequiredstring
result.items[].labelRequiredstring
result.items[].kindRequiredstring≥ 1 characters

quiz, score or flag.

result.items[].valueRequirednumber | boolean
result.totalsRequiredobject
result.totals.scoreRequirednumber≥ 0
result.totals.maxScoreRequirednumber≥ 0
result.totals.percentRequirednumber0–100
result.totals.passedboolean
result.totals.correctCountRequiredinteger0–9007199254740991
result.totals.questionCountRequiredinteger0–9007199254740991
result.totals.answeredCountRequiredinteger0–9007199254740991
result.totals.beatsCompletedRequiredinteger0–9007199254740991
result.totals.beatsTotalRequiredinteger0–9007199254740991
result.totals.completionRequirednumber0–1

Completed Beats ÷ all Beats (1 when there are none).

transcriptobject[]
transcript[].speakerRequiredstring≥ 1 characters

viewer, narrator, cast:{castId} or prop:{entityId}.

transcript[].speakerNameRequiredstring
transcript[].addresseestring≥ 1 characters

Who it was said to (the same keys, or all).

transcript[].textRequiredstring
transcript[].atRequiredstring (date-time)

An ISO 8601 instant.

text/html — format=html

text/csv — format=csv

application/vnd.openxmlformats-officedocument.wordprocessingml.document — format=docx

application/vnd.openxmlformats-officedocument.spreadsheetml.sheet — format=xlsx

Errors

  • 400invalid_input
  • 401key_invalid
  • 403scope_required
  • 404not_found