REST API: Viewer sessions
Every operation of this group with its parameters, body, answer and errors, as the OpenAPI document states them.
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 /v1 is a frozen contract.
Start a viewer session
POST/v1/sessionsNo bearer token
Rate limited per client address (30 a minute, a burst of 10 more). A signed-in jami.live caller plays as themselves.
Request body (application/json)
| Field | Type | Description |
|---|---|---|
projectId | string (uuid) | A server-minted id (sessions, projects, releases, users): a UUID. |
listing | string1–80 characters | What a request may name instead of a project id: a marketplace listing's slug. |
release | "latest" | string (uuid)default "latest" | |
publishableKey | string1–200 characters | |
viewerToken | string1–4096 characters | |
shareToken | string16–128 characters | |
locale | string≤ 35 characters | The viewer's language (live AI replies follow it); absent: the release's content language. |
parentOrigin | string≤ 2048 characters | |
resumeSessionId | string (uuid) | A server-minted id (sessions, projects, releases, users): a UUID. |
Response 201
Start a viewer session
| Field | Type | Description |
|---|---|---|
sessionRequired | object | |
session.idRequired | string (uuid) | A server-minted id (sessions, projects, releases, users): a UUID. |
session.surfaceRequired | string≥ 1 characters | One of |
session.epochRequired | integer0–9007199254740991 | |
session.expiresAtRequired | string (date-time) | When the token expires: heartbeat before then. |
session.endsAtRequired | string (date-time) | No heartbeat extends the session past this: mint again (with |
session.heartbeatMsRequired | integer0–9007199254740991 | |
session.testRequired | boolean | Minted from the Studio or with a test key: kept out of the creator's analytics. |
session.childDirectedRequired | boolean | The project is made for children: no persistent identifiers, stricter AI. |
session.localeRequired | string≤ 35 characters | A UI or reply language: a BCP 47 tag ( |
session.resumedFrom | string (uuid) | A resumed session: the session it continues… |
session.resume | object | …and where its story stands — the furthest anchor recorded and the last known playback position. |
session.resume.headRequired | object | WHERE in the story something happened: |
session.resume.head.visitRequired | integer1–9007199254740991 | |
session.resume.head.sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
session.resume.head.msRequired | integer0–9007199254740991 | A non-negative integer count or time in milliseconds. |
session.resume.position | object | A position on the story axis without a visit: a scene and an authored time in it. |
session.resume.position.sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
session.resume.position.msRequired | integer0–9007199254740991 | A non-negative integer count or time in milliseconds. |
session.resumeOffer | object | Added within v1 (P8): a signed-in viewer's mint that named no session to resume, when they left this release's story unfinished in another session within the resume window (on another device, say) — the latest such session, and where its story stands. The session this answer opened starts from the beginning; to continue the other one instead, ask the viewer, then mint again with |
session.resumeOffer.sessionIdRequired | string (uuid) | A server-minted id (sessions, projects, releases, users): a UUID. |
session.resumeOffer.headRequired | object | WHERE in the story something happened: |
session.resumeOffer.head.visitRequired | integer1–9007199254740991 | |
session.resumeOffer.head.sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
session.resumeOffer.head.msRequired | integer0–9007199254740991 | A non-negative integer count or time in milliseconds. |
session.resumeOffer.position | object | A position on the story axis without a visit: a scene and an authored time in it. |
session.resumeOffer.position.sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
session.resumeOffer.position.msRequired | integer0–9007199254740991 | A non-negative integer count or time in milliseconds. |
session.resumeOffer.seenAtRequired | string (date-time) | When that session was last seen. |
session.conversationRetentionDays | integer0–9007199254740991 | Added within v1 (P8): how many days the words of this session's conversation are kept before they are erased — the project's choice, one day for a child-directed project — which the Live Room's "About this experience" tells the viewer. Absent: a server from before (say no number then). |
tokenRequired | string≥ 1 characters | |
releaseRequired | object | |
release.idRequired | string≥ 1 characters | A release id; a Studio draft's is the draft's own ( |
release.kindRequired | string≥ 1 characters |
|
release.number | integer0–9007199254740991 | Absent for a draft. |
release.manifestUrlRequired | string≥ 1 characters | The release manifest ( |
assetsRequired | object | |
assets.baseRequired | string≥ 1 characters | Where the release's files are: a file's URL is |
assets.token | string≥ 1 characters | A protected release: the asset token its |
assets.namespace | string≥ 1 characters | The namespace of the content-addressed paths: one of |
aiRequired | object | The mint answer's AI section: the status, the effective limits and how to unlock text and voice. |
ai.levelRequired | "off" | "text" | "voice" | |
ai.reasonsRequired | string[] | |
ai.scopesRequired | string[] | |
ai.voiceReplies | string1–32 characters | Added within v1: whether live replies are spoken here — the project's setting, one of |
ai.needsVerificationRequired | boolean | Text and voice need a human check first ( |
ai.verification | object | How a session's live AI must be unlocked, when it must. |
ai.verification.kindRequired | string≥ 1 characters |
|
ai.verification.siteKeyRequired | string≥ 1 characters | |
ai.limitsRequired | object | The effective per-viewer limits of live AI (the project's, tightened by an API key's). |
ai.limits.turnsPerSessionRequired | integer0–9007199254740991 | |
ai.limits.turnsPerViewerDayRequired | integer0–9007199254740991 | |
ai.limits.voiceSecondsPerViewerDayRequired | integer0–9007199254740991 | |
ai.stamp | string1–64 characters | Added within v1 (P8): the AI watch's stamp this status was decided under — what the first |
brandingRequired | object | |
branding.accent | string | The project's Live Room accent ( |
branding.badgeRequired | boolean | Show the "Made with Jami3D" badge (plans without removable branding). |
protocolRequired | object | |
protocol.versionRequired | integer0–9007199254740991 | |
protocol.capabilitiesRequired | string[] | |
embed | object | An embed's session ( |
embed.conversationEventsRequired | boolean |
Errors
400invalid_input401key_invalid403origin_not_allowed404release_not_found429rate_limited503retry_later
Keep a session alive
POST/v1/sessions/{id}/heartbeatViewer token
Every 5 minutes; a fresh token when the old one has less than 10 minutes left. A session ends 8 hours after it began.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idRequired | path | string | The viewer session's id ( |
Request body (application/json)
| Field | Type | Description |
|---|---|---|
position | object | A position on the story axis without a visit: a scene and an authored time in it. |
position.sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
position.msRequired | integer0–9007199254740991 | A non-negative integer count or time in milliseconds. |
Response 200
Keep a session alive
| Field | Type | Description |
|---|---|---|
token | string≥ 1 characters | A fresh token, when the old one had less than 10 minutes left; keep the old one otherwise. |
expiresAtRequired | string (date-time) | An ISO 8601 instant. |
endsAtRequired | string (date-time) | An ISO 8601 instant. |
epochRequired | integer0–9007199254740991 | |
aiRequired | object | The session's live-AI status: the level and every reason that holds at it, and the scopes the token carries. The UI hides voice at |
ai.levelRequired | "off" | "text" | "voice" | |
ai.reasonsRequired | string[] | |
ai.scopesRequired | string[] | |
ai.voiceReplies | string1–32 characters | Added within v1: whether live replies are spoken here — the project's setting, one of |
assetsRequired | object | Where the session's files are now (a release's session; |
assets.token | string≥ 1 characters | |
assets.base | string≥ 1 characters | |
assets.namespace | string≥ 1 characters | |
protocol | object | Added within v1 (P17): the protocol as this server speaks it now — what a session minted on an older pod learns at its next heartbeat (a capability switched on since, |
protocol.versionRequired | integer0–9007199254740991 | |
protocol.capabilitiesRequired | string[] |
Errors
400invalid_input401invalid_token,session_expired404not_found
Verify the viewer (Turnstile)
POST/v1/sessions/{id}/verifyViewer token
The human check that grants text and voice in a fresh token; five an hour per client address.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idRequired | path | string | The viewer session's id ( |
Request body (application/json)
| Field | Type | Description |
|---|---|---|
turnstileTokenRequired | string1–2048 characters |
Response 200
Verify the viewer (Turnstile)
| Field | Type | Description |
|---|---|---|
tokenRequired | string≥ 1 characters | |
expiresAtRequired | string (date-time) | An ISO 8601 instant. |
aiRequired | object | The session's live-AI status: the level and every reason that holds at it, and the scopes the token carries. The UI hides voice at |
ai.levelRequired | "off" | "text" | "voice" | |
ai.reasonsRequired | string[] | |
ai.scopesRequired | string[] | |
ai.voiceReplies | string1–32 characters | Added within v1: whether live replies are spoken here — the project's setting, one of |
Errors
401invalid_token,session_expired403verification_failed404not_found429rate_limited503retry_later
Watch the session's live-AI level
GET/v1/sessions/{id}/aiViewer token
Added within v1 (P8), capability ai.watch: the session's live-AI status, asked while the Live Room is visible — the status itself only when it changed since the client's stamp.
Every pollMs (6 seconds), with the last stamp as since: a top-up, a kill switch or a spend cap shows within seconds instead of at the next heartbeat. Cheap when nothing changed: no status, no database read.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idRequired | path | string | The viewer session's id ( |
since | query | string |
Response 200
Watch the session's live-AI level
| Field | Type | Description |
|---|---|---|
stampRequired | string1–64 characters | What decides the session's level beyond the viewer's own use — the switches, the project's settings, the payer's credits and caps, the key's limits — condensed: the same stamp, the same level. Opaque: compare it, never read it. |
ai | object | The session's live-AI status, decided now: present when |
ai.levelRequired | "off" | "text" | "voice" | |
ai.reasonsRequired | string[] | |
ai.scopesRequired | string[] | |
ai.voiceReplies | string1–32 characters | Added within v1: whether live replies are spoken here — the project's setting, one of |
pollMsRequired | integer0–9007199254740991 | When to ask again, ms, while the Live Room stays visible. |
Errors
400invalid_input401invalid_token,session_expired404not_found429rate_limited
Record the player's facts
POST/v1/sessions/{id}/eventsViewer token
With sync=1 the request's quiz answer is graded against the private quiz and the grade comes back in the answer.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idRequired | path | string | The viewer session's id ( |
sync | query | "0" | "1" |
Request body (application/json)
| Field | Type | Description |
|---|---|---|
epochRequired | integer0–9007199254740991 | |
seqRequired | integer1–9007199254740991 | |
factsRequired | object[]1–50 items | |
facts[].kindRequired | string1–64 characters | |
facts[].anchorRequired | object | WHERE in the story something happened: |
facts[].anchor.visitRequired | integer1–9007199254740991 | |
facts[].anchor.sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
facts[].anchor.msRequired | integer0–9007199254740991 | A non-negative integer count or time in milliseconds. |
Response 200
Record the player's facts
| Field | Type | Description |
|---|---|---|
epochRequired | integer0–9007199254740991 | |
ackSeqRequired | integer0–9007199254740991 | Every fact numbered up to here is settled (journaled or refused): drop it from the outbox. |
headSeqRequired | integer0–9007199254740991 | The journal's last sequence number. |
refused | object[] | |
refused[].seqRequired | integer1–9007199254740991 | The refused fact's number (the request's |
refused[].codeRequired | string≥ 1 characters | |
refused[].messageRequired | string | |
resync | boolean | The player's state may differ from the server's: read |
facts | any[] | Facts the SERVER wrote because of this request (a graded answer's |
grade | object |
|
grade.correctRequired | boolean | |
grade.pointsRequired | number≥ 0 | |
grade.feedback | string | The feedback for this answer: the chosen choice's own, else the question's correct / incorrect. |
grade.correctAnswer | one of | Present when the quiz's reveal policy shows it now. |
| When kind is “choice” | ||
grade.correctAnswer.choiceIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
| When kind is “choices” | ||
grade.correctAnswer.choiceIdsRequired | string[] | |
| When kind is “boolean” | ||
grade.correctAnswer.valueRequired | boolean | |
| When kind is “text” | ||
grade.correctAnswer.acceptedRequired | string[] | |
grade.attemptsLeftRequired | integer0–9007199254740991 | |
grade.quizScoreRequired | number≥ 0 | The quiz's score after this answer. |
grade.completedRequired | boolean | Every question of the quiz is finished. |
aiRequired | object | The session's live-AI status: the level and every reason that holds at it, and the scopes the token carries. The UI hides voice at |
ai.levelRequired | "off" | "text" | "voice" | |
ai.reasonsRequired | string[] | |
ai.scopesRequired | string[] | |
ai.voiceReplies | string1–32 characters | Added within v1: whether live replies are spoken here — the project's setting, one of |
Errors
400invalid_input401invalid_token,session_expired404not_found409stale_epoch,seq_gap,rewind_required413body_too_large415unsupported_media_type
Go back in the story
POST/v1/sessions/{id}/rewindViewer token
A dry run counts what going back erases; a commit erases it and starts the next epoch (idempotent by rewindId).
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idRequired | path | string | The viewer session's id ( |
Request body (application/json)
| Field | Type | Description |
|---|---|---|
epochRequired | integer0–9007199254740991 | |
toRequired | object | WHERE in the story something happened: |
to.visitRequired | integer1–9007199254740991 | |
to.sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
to.msRequired | integer0–9007199254740991 | A non-negative integer count or time in milliseconds. |
dryRun | booleandefault false | |
rewindId | string (uuid) | A server-minted id (sessions, projects, releases, users): a UUID. |
Response 200
Go back in the story
| Field | Type | Description |
|---|---|---|
dryRunRequired | boolean | |
epochRequired | integer0–9007199254740991 | A dry run: the session's epoch; a commit: the NEW epoch every later write carries. |
headSeqRequired | integer0–9007199254740991 | |
impactRequired | object | What a rewind erases: interaction facts, quiz answers, viewer questions; the quizzes whose answers go. |
impact.eventsRequired | integer0–9007199254740991 | |
impact.quizAnswersRequired | integer0–9007199254740991 | |
impact.turnsRequired | integer0–9007199254740991 | |
impact.quizIdsRequired | string[] | |
fact | one of | A commit: the |
| When kind is “scene.entered” | ||
fact.seqRequired | integer1–9007199254740991 | The journal's order: strictly increasing, assigned by the server. |
fact.epochRequired | integer0–9007199254740991 | |
fact.anchorRequired | object | WHERE in the story something happened: |
fact.anchor.visitRequired | integer1–9007199254740991 | |
fact.anchor.sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
fact.anchor.msRequired | integer0–9007199254740991 | A non-negative integer count or time in milliseconds. |
fact.pinned | boolean | Kept by the AI log's window trims (navigation markers); a rewind still truncates it. |
fact.sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
| When kind is “beat.entered” | ||
fact.seqRequired | integer1–9007199254740991 | The journal's order: strictly increasing, assigned by the server. |
fact.epochRequired | integer0–9007199254740991 | |
fact.anchorRequired | object | WHERE in the story something happened: |
fact.anchor.visitRequired | integer1–9007199254740991 | |
fact.anchor.sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
fact.anchor.msRequired | integer0–9007199254740991 | A non-negative integer count or time in milliseconds. |
fact.pinned | boolean | Kept by the AI log's window trims (navigation markers); a rewind still truncates it. |
fact.beatIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
fact.varsRequired | record of boolean | number | string | |
| When kind is “beat.exited” | ||
fact.seqRequired | integer1–9007199254740991 | The journal's order: strictly increasing, assigned by the server. |
fact.epochRequired | integer0–9007199254740991 | |
fact.anchorRequired | object | WHERE in the story something happened: |
fact.anchor.visitRequired | integer1–9007199254740991 | |
fact.anchor.sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
fact.anchor.msRequired | integer0–9007199254740991 | A non-negative integer count or time in milliseconds. |
fact.pinned | boolean | Kept by the AI log's window trims (navigation markers); a rewind still truncates it. |
fact.beatIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
fact.reasonRequired | "continued" | "timer" | "satisfied" | "timeout" | "jump" | "seek" | "rewind" | "sceneExit" | |
| When kind is “beat.skipped” | ||
fact.seqRequired | integer1–9007199254740991 | The journal's order: strictly increasing, assigned by the server. |
fact.epochRequired | integer0–9007199254740991 | |
fact.anchorRequired | object | WHERE in the story something happened: |
fact.anchor.visitRequired | integer1–9007199254740991 | |
fact.anchor.sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
fact.anchor.msRequired | integer0–9007199254740991 | A non-negative integer count or time in milliseconds. |
fact.pinned | boolean | Kept by the AI log's window trims (navigation markers); a rewind still truncates it. |
fact.beatIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
| When kind is “seek.forward” | ||
fact.seqRequired | integer1–9007199254740991 | The journal's order: strictly increasing, assigned by the server. |
fact.epochRequired | integer0–9007199254740991 | |
fact.anchorRequired | object | WHERE in the story something happened: |
fact.anchor.visitRequired | integer1–9007199254740991 | |
fact.anchor.sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
fact.anchor.msRequired | integer0–9007199254740991 | A non-negative integer count or time in milliseconds. |
fact.pinned | boolean | Kept by the AI log's window trims (navigation markers); a rewind still truncates it. |
fact.fromRequired | object | A position on the story axis without a visit: a scene and an authored time in it. |
fact.from.sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
fact.from.msRequired | integer0–9007199254740991 | A non-negative integer count or time in milliseconds. |
| When kind is “object.interacted” | ||
fact.seqRequired | integer1–9007199254740991 | The journal's order: strictly increasing, assigned by the server. |
fact.epochRequired | integer0–9007199254740991 | |
fact.anchorRequired | object | WHERE in the story something happened: |
fact.anchor.visitRequired | integer1–9007199254740991 | |
fact.anchor.sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
fact.anchor.msRequired | integer0–9007199254740991 | A non-negative integer count or time in milliseconds. |
fact.pinned | boolean | Kept by the AI log's window trims (navigation markers); a rewind still truncates it. |
fact.entityIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
fact.behaviorId | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
fact.region | string1–64 characters | |
fact.change | object | What changed about an object: a toggle's state, a book's spread, a visibility override. |
fact.change.state | string1–64 characters | |
fact.change.spread | integer0–9007199254740991 | |
fact.change.visible | boolean | |
fact.listenerId | string1–160 characters | Added within v1 (P17): the graph listener that heard the input. |
fact.input | string1–32 characters | Added within v1 (P17): the input ( |
fact.local | number[]3–3 items | Added within v1 (P17): where on the entity the input landed, in its local frame: x, y, z. |
| When kind is “object.changed” | ||
fact.seqRequired | integer1–9007199254740991 | The journal's order: strictly increasing, assigned by the server. |
fact.epochRequired | integer0–9007199254740991 | |
fact.anchorRequired | object | WHERE in the story something happened: |
fact.anchor.visitRequired | integer1–9007199254740991 | |
fact.anchor.sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
fact.anchor.msRequired | integer0–9007199254740991 | A non-negative integer count or time in milliseconds. |
fact.pinned | boolean | Kept by the AI log's window trims (navigation markers); a rewind still truncates it. |
fact.entityIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
fact.changeRequired | object | What changed about an object: a toggle's state, a book's spread, a visibility override. |
fact.change.state | string1–64 characters | |
fact.change.spread | integer0–9007199254740991 | |
fact.change.visible | boolean | |
fact.causeRequired | one of | Why story state changed: a rule, a timed event, a behaviour of its own accord, the AI — or the author, from the Studio preview's Session Inspector ( |
| When kind is “rule” | ||
fact.cause.ruleIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
fact.cause.sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
| When kind is “event” | ||
fact.cause.eventIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
fact.cause.sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
| When kind is “behavior” | ||
fact.cause.entityIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
fact.cause.behaviorIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
| When kind is “ai” | ||
fact.cause.turnIdRequired | string1–160 characters | |
| When kind is “studio” | ||
| When kind is “var.changed” | ||
fact.seqRequired | integer1–9007199254740991 | The journal's order: strictly increasing, assigned by the server. |
fact.epochRequired | integer0–9007199254740991 | |
fact.anchorRequired | object | WHERE in the story something happened: |
fact.anchor.visitRequired | integer1–9007199254740991 | |
fact.anchor.sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
fact.anchor.msRequired | integer0–9007199254740991 | A non-negative integer count or time in milliseconds. |
fact.pinned | boolean | Kept by the AI log's window trims (navigation markers); a rewind still truncates it. |
fact.variableIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
fact.valueRequired | boolean | number | string | A story value: a boolean, a number, or a short text (a choice is its key). |
fact.causeRequired | one of | Why story state changed: a rule, a timed event, a behaviour of its own accord, the AI — or the author, from the Studio preview's Session Inspector ( |
| When kind is “rule” | ||
fact.cause.ruleIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
fact.cause.sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
| When kind is “event” | ||
fact.cause.eventIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
fact.cause.sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
| When kind is “behavior” | ||
fact.cause.entityIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
fact.cause.behaviorIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
| When kind is “ai” | ||
fact.cause.turnIdRequired | string1–160 characters | |
| When kind is “studio” | ||
| When kind is “rule.fired” | ||
fact.seqRequired | integer1–9007199254740991 | The journal's order: strictly increasing, assigned by the server. |
fact.epochRequired | integer0–9007199254740991 | |
fact.anchorRequired | object | WHERE in the story something happened: |
fact.anchor.visitRequired | integer1–9007199254740991 | |
fact.anchor.sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
fact.anchor.msRequired | integer0–9007199254740991 | A non-negative integer count or time in milliseconds. |
fact.pinned | boolean | Kept by the AI log's window trims (navigation markers); a rewind still truncates it. |
fact.ruleIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
| When kind is “quiz.started” | ||
fact.seqRequired | integer1–9007199254740991 | The journal's order: strictly increasing, assigned by the server. |
fact.epochRequired | integer0–9007199254740991 | |
fact.anchorRequired | object | WHERE in the story something happened: |
fact.anchor.visitRequired | integer1–9007199254740991 | |
fact.anchor.sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
fact.anchor.msRequired | integer0–9007199254740991 | A non-negative integer count or time in milliseconds. |
fact.pinned | boolean | Kept by the AI log's window trims (navigation markers); a rewind still truncates it. |
fact.quizIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
| When kind is “quiz.skipped” | ||
fact.seqRequired | integer1–9007199254740991 | The journal's order: strictly increasing, assigned by the server. |
fact.epochRequired | integer0–9007199254740991 | |
fact.anchorRequired | object | WHERE in the story something happened: |
fact.anchor.visitRequired | integer1–9007199254740991 | |
fact.anchor.sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
fact.anchor.msRequired | integer0–9007199254740991 | A non-negative integer count or time in milliseconds. |
fact.pinned | boolean | Kept by the AI log's window trims (navigation markers); a rewind still truncates it. |
fact.quizIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
| When kind is “navigation.declined” | ||
fact.seqRequired | integer1–9007199254740991 | The journal's order: strictly increasing, assigned by the server. |
fact.epochRequired | integer0–9007199254740991 | |
fact.anchorRequired | object | WHERE in the story something happened: |
fact.anchor.visitRequired | integer1–9007199254740991 | |
fact.anchor.sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
fact.anchor.msRequired | integer0–9007199254740991 | A non-negative integer count or time in milliseconds. |
fact.pinned | boolean | Kept by the AI log's window trims (navigation markers); a rewind still truncates it. |
fact.toBeatIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
| When kind is “navigation.arrived” | ||
fact.seqRequired | integer1–9007199254740991 | The journal's order: strictly increasing, assigned by the server. |
fact.epochRequired | integer0–9007199254740991 | |
fact.anchorRequired | object | WHERE in the story something happened: |
fact.anchor.visitRequired | integer1–9007199254740991 | |
fact.anchor.sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
fact.anchor.msRequired | integer0–9007199254740991 | A non-negative integer count or time in milliseconds. |
fact.pinned | boolean | Kept by the AI log's window trims (navigation markers); a rewind still truncates it. |
fact.toBeatId | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
fact.landingRequired | "chapterStart" | "hold" | "origin" | |
| When kind is “viewer.context” | ||
fact.seqRequired | integer1–9007199254740991 | The journal's order: strictly increasing, assigned by the server. |
fact.epochRequired | integer0–9007199254740991 | |
fact.anchorRequired | object | WHERE in the story something happened: |
fact.anchor.visitRequired | integer1–9007199254740991 | |
fact.anchor.sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
fact.anchor.msRequired | integer0–9007199254740991 | A non-negative integer count or time in milliseconds. |
fact.pinned | boolean | Kept by the AI log's window trims (navigation markers); a rewind still truncates it. |
fact.valuesRequired | record of string | number | boolean | |
| When kind is “session.completed” | ||
fact.seqRequired | integer1–9007199254740991 | The journal's order: strictly increasing, assigned by the server. |
fact.epochRequired | integer0–9007199254740991 | |
fact.anchorRequired | object | WHERE in the story something happened: |
fact.anchor.visitRequired | integer1–9007199254740991 | |
fact.anchor.sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
fact.anchor.msRequired | integer0–9007199254740991 | A non-negative integer count or time in milliseconds. |
fact.pinned | boolean | Kept by the AI log's window trims (navigation markers); a rewind still truncates it. |
| When kind is “quiz.submitted” | ||
fact.seqRequired | integer1–9007199254740991 | The journal's order: strictly increasing, assigned by the server. |
fact.epochRequired | integer0–9007199254740991 | |
fact.anchorRequired | object | WHERE in the story something happened: |
fact.anchor.visitRequired | integer1–9007199254740991 | |
fact.anchor.sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
fact.anchor.msRequired | integer0–9007199254740991 | A non-negative integer count or time in milliseconds. |
fact.pinned | boolean | Kept by the AI log's window trims (navigation markers); a rewind still truncates it. |
fact.quizIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
fact.questionIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
fact.respondentRequired | one of | Who answers a quiz: the viewer, or the viewer playing a cast member ("as Cat"). |
| When kind is “viewer” | ||
| When kind is “character” | ||
fact.respondent.castIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
fact.responseRequired | one 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” | ||
fact.response.choiceIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
| When kind is “choices” | ||
fact.response.choiceIdsRequired | string[]1–10 items | |
| When kind is “boolean” | ||
fact.response.valueRequired | boolean | |
| When kind is “text” | ||
fact.response.textRequired | string≤ 2000 characters | |
fact.correctRequired | boolean | |
fact.pointsRequired | number≥ 0 | |
fact.attemptRequired | integer1–9007199254740991 | |
fact.finalRequired | boolean | Correct, or out of attempts: the question is finished. |
| When kind is “navigation.requested” | ||
fact.seqRequired | integer1–9007199254740991 | The journal's order: strictly increasing, assigned by the server. |
fact.epochRequired | integer0–9007199254740991 | |
fact.anchorRequired | object | WHERE in the story something happened: |
fact.anchor.visitRequired | integer1–9007199254740991 | |
fact.anchor.sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
fact.anchor.msRequired | integer0–9007199254740991 | A non-negative integer count or time in milliseconds. |
fact.pinned | boolean | Kept by the AI log's window trims (navigation markers); a rewind still truncates it. |
fact.toBeatIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
fact.landingRequired | "chapterStart" | "hold" | |
fact.requestRequired | string≤ 2000 characters | |
| When kind is “navigation.confirmed” | ||
fact.seqRequired | integer1–9007199254740991 | The journal's order: strictly increasing, assigned by the server. |
fact.epochRequired | integer0–9007199254740991 | |
fact.anchorRequired | object | WHERE in the story something happened: |
fact.anchor.visitRequired | integer1–9007199254740991 | |
fact.anchor.sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
fact.anchor.msRequired | integer0–9007199254740991 | A non-negative integer count or time in milliseconds. |
fact.pinned | boolean | Kept by the AI log's window trims (navigation markers); a rewind still truncates it. |
fact.toBeatIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
fact.landingRequired | "chapterStart" | "hold" | |
fact.request | string≤ 2000 characters | The request the erased |
| When kind is “navigation.visitStarted” | ||
fact.seqRequired | integer1–9007199254740991 | The journal's order: strictly increasing, assigned by the server. |
fact.epochRequired | integer0–9007199254740991 | |
fact.anchorRequired | object | WHERE in the story something happened: |
fact.anchor.visitRequired | integer1–9007199254740991 | |
fact.anchor.sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
fact.anchor.msRequired | integer0–9007199254740991 | A non-negative integer count or time in milliseconds. |
fact.pinned | boolean | Kept by the AI log's window trims (navigation markers); a rewind still truncates it. |
fact.visitRequired | integer1–9007199254740991 | |
fact.fromBeatId | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
fact.toBeatId | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
fact.returned | boolean | |
| When kind is “conversation.turn” | ||
fact.seqRequired | integer1–9007199254740991 | The journal's order: strictly increasing, assigned by the server. |
fact.epochRequired | integer0–9007199254740991 | |
fact.anchorRequired | object | WHERE in the story something happened: |
fact.anchor.visitRequired | integer1–9007199254740991 | |
fact.anchor.sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
fact.anchor.msRequired | integer0–9007199254740991 | A non-negative integer count or time in milliseconds. |
fact.pinned | boolean | Kept by the AI log's window trims (navigation markers); a rewind still truncates it. |
fact.beatIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
fact.turnIdRequired | string1–160 characters | |
| When kind is “session.rewound” | ||
fact.seqRequired | integer1–9007199254740991 | The journal's order: strictly increasing, assigned by the server. |
fact.epochRequired | integer0–9007199254740991 | |
fact.anchorRequired | object | WHERE in the story something happened: |
fact.anchor.visitRequired | integer1–9007199254740991 | |
fact.anchor.sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
fact.anchor.msRequired | integer0–9007199254740991 | A non-negative integer count or time in milliseconds. |
fact.pinned | boolean | Kept by the AI log's window trims (navigation markers); a rewind still truncates it. |
fact.toRequired | object | WHERE in the story something happened: |
fact.to.visitRequired | integer1–9007199254740991 | |
fact.to.sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
fact.to.msRequired | integer0–9007199254740991 | A non-negative integer count or time in milliseconds. |
| When kind is “object.updated” | ||
fact.seqRequired | integer1–9007199254740991 | The journal's order: strictly increasing, assigned by the server. |
fact.epochRequired | integer0–9007199254740991 | |
fact.anchorRequired | object | WHERE in the story something happened: |
fact.anchor.visitRequired | integer1–9007199254740991 | |
fact.anchor.sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
fact.anchor.msRequired | integer0–9007199254740991 | A non-negative integer count or time in milliseconds. |
fact.pinned | boolean | Kept by the AI log's window trims (navigation markers); a rewind still truncates it. |
fact.entityIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
fact.params | record of boolean | number | string | (boolean | number | string)[] | |
fact.states | record of string | |
fact.causeRequired | one of | Why an object's Interaction Graph changed: a fact's causes, or a viewer's input (the listener that heard it), the graph on its own (a transition ending, a tween landing, a timer), the host page through the SDK. |
| When kind is “rule” | ||
fact.cause.ruleIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
fact.cause.sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
| When kind is “event” | ||
fact.cause.eventIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
fact.cause.sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
| When kind is “behavior” | ||
fact.cause.entityIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
fact.cause.behaviorIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
| When kind is “ai” | ||
fact.cause.turnIdRequired | string1–160 characters | |
| When kind is “studio” | ||
| When kind is “input” | ||
fact.cause.listenerId | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
| When kind is “graph” | ||
| When kind is “host” | ||
facts | (one of)[]≥ 1 items | A commit (added within v1, P8): every fact it journaled, in order — |
| When kind is “scene.entered” | ||
facts[].seqRequired | integer1–9007199254740991 | The journal's order: strictly increasing, assigned by the server. |
facts[].epochRequired | integer0–9007199254740991 | |
facts[].anchorRequired | object | WHERE in the story something happened: |
facts[].anchor.visitRequired | integer1–9007199254740991 | |
facts[].anchor.sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
facts[].anchor.msRequired | integer0–9007199254740991 | A non-negative integer count or time in milliseconds. |
facts[].pinned | boolean | Kept by the AI log's window trims (navigation markers); a rewind still truncates it. |
facts[].sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
| When kind is “beat.entered” | ||
facts[].seqRequired | integer1–9007199254740991 | The journal's order: strictly increasing, assigned by the server. |
facts[].epochRequired | integer0–9007199254740991 | |
facts[].anchorRequired | object | WHERE in the story something happened: |
facts[].anchor.visitRequired | integer1–9007199254740991 | |
facts[].anchor.sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
facts[].anchor.msRequired | integer0–9007199254740991 | A non-negative integer count or time in milliseconds. |
facts[].pinned | boolean | Kept by the AI log's window trims (navigation markers); a rewind still truncates it. |
facts[].beatIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
facts[].varsRequired | record of boolean | number | string | |
| When kind is “beat.exited” | ||
facts[].seqRequired | integer1–9007199254740991 | The journal's order: strictly increasing, assigned by the server. |
facts[].epochRequired | integer0–9007199254740991 | |
facts[].anchorRequired | object | WHERE in the story something happened: |
facts[].anchor.visitRequired | integer1–9007199254740991 | |
facts[].anchor.sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
facts[].anchor.msRequired | integer0–9007199254740991 | A non-negative integer count or time in milliseconds. |
facts[].pinned | boolean | Kept by the AI log's window trims (navigation markers); a rewind still truncates it. |
facts[].beatIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
facts[].reasonRequired | "continued" | "timer" | "satisfied" | "timeout" | "jump" | "seek" | "rewind" | "sceneExit" | |
| When kind is “beat.skipped” | ||
facts[].seqRequired | integer1–9007199254740991 | The journal's order: strictly increasing, assigned by the server. |
facts[].epochRequired | integer0–9007199254740991 | |
facts[].anchorRequired | object | WHERE in the story something happened: |
facts[].anchor.visitRequired | integer1–9007199254740991 | |
facts[].anchor.sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
facts[].anchor.msRequired | integer0–9007199254740991 | A non-negative integer count or time in milliseconds. |
facts[].pinned | boolean | Kept by the AI log's window trims (navigation markers); a rewind still truncates it. |
facts[].beatIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
| When kind is “seek.forward” | ||
facts[].seqRequired | integer1–9007199254740991 | The journal's order: strictly increasing, assigned by the server. |
facts[].epochRequired | integer0–9007199254740991 | |
facts[].anchorRequired | object | WHERE in the story something happened: |
facts[].anchor.visitRequired | integer1–9007199254740991 | |
facts[].anchor.sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
facts[].anchor.msRequired | integer0–9007199254740991 | A non-negative integer count or time in milliseconds. |
facts[].pinned | boolean | Kept by the AI log's window trims (navigation markers); a rewind still truncates it. |
facts[].fromRequired | object | A position on the story axis without a visit: a scene and an authored time in it. |
facts[].from.sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
facts[].from.msRequired | integer0–9007199254740991 | A non-negative integer count or time in milliseconds. |
| When kind is “object.interacted” | ||
facts[].seqRequired | integer1–9007199254740991 | The journal's order: strictly increasing, assigned by the server. |
facts[].epochRequired | integer0–9007199254740991 | |
facts[].anchorRequired | object | WHERE in the story something happened: |
facts[].anchor.visitRequired | integer1–9007199254740991 | |
facts[].anchor.sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
facts[].anchor.msRequired | integer0–9007199254740991 | A non-negative integer count or time in milliseconds. |
facts[].pinned | boolean | Kept by the AI log's window trims (navigation markers); a rewind still truncates it. |
facts[].entityIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
facts[].behaviorId | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
facts[].region | string1–64 characters | |
facts[].change | object | What changed about an object: a toggle's state, a book's spread, a visibility override. |
facts[].change.state | string1–64 characters | |
facts[].change.spread | integer0–9007199254740991 | |
facts[].change.visible | boolean | |
facts[].listenerId | string1–160 characters | Added within v1 (P17): the graph listener that heard the input. |
facts[].input | string1–32 characters | Added within v1 (P17): the input ( |
facts[].local | number[]3–3 items | Added within v1 (P17): where on the entity the input landed, in its local frame: x, y, z. |
| When kind is “object.changed” | ||
facts[].seqRequired | integer1–9007199254740991 | The journal's order: strictly increasing, assigned by the server. |
facts[].epochRequired | integer0–9007199254740991 | |
facts[].anchorRequired | object | WHERE in the story something happened: |
facts[].anchor.visitRequired | integer1–9007199254740991 | |
facts[].anchor.sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
facts[].anchor.msRequired | integer0–9007199254740991 | A non-negative integer count or time in milliseconds. |
facts[].pinned | boolean | Kept by the AI log's window trims (navigation markers); a rewind still truncates it. |
facts[].entityIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
facts[].changeRequired | object | What changed about an object: a toggle's state, a book's spread, a visibility override. |
facts[].change.state | string1–64 characters | |
facts[].change.spread | integer0–9007199254740991 | |
facts[].change.visible | boolean | |
facts[].causeRequired | one of | Why story state changed: a rule, a timed event, a behaviour of its own accord, the AI — or the author, from the Studio preview's Session Inspector ( |
| When kind is “rule” | ||
facts[].cause.ruleIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
facts[].cause.sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
| When kind is “event” | ||
facts[].cause.eventIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
facts[].cause.sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
| When kind is “behavior” | ||
facts[].cause.entityIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
facts[].cause.behaviorIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
| When kind is “ai” | ||
facts[].cause.turnIdRequired | string1–160 characters | |
| When kind is “studio” | ||
| When kind is “var.changed” | ||
facts[].seqRequired | integer1–9007199254740991 | The journal's order: strictly increasing, assigned by the server. |
facts[].epochRequired | integer0–9007199254740991 | |
facts[].anchorRequired | object | WHERE in the story something happened: |
facts[].anchor.visitRequired | integer1–9007199254740991 | |
facts[].anchor.sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
facts[].anchor.msRequired | integer0–9007199254740991 | A non-negative integer count or time in milliseconds. |
facts[].pinned | boolean | Kept by the AI log's window trims (navigation markers); a rewind still truncates it. |
facts[].variableIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
facts[].valueRequired | boolean | number | string | A story value: a boolean, a number, or a short text (a choice is its key). |
facts[].causeRequired | one of | Why story state changed: a rule, a timed event, a behaviour of its own accord, the AI — or the author, from the Studio preview's Session Inspector ( |
| When kind is “rule” | ||
facts[].cause.ruleIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
facts[].cause.sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
| When kind is “event” | ||
facts[].cause.eventIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
facts[].cause.sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
| When kind is “behavior” | ||
facts[].cause.entityIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
facts[].cause.behaviorIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
| When kind is “ai” | ||
facts[].cause.turnIdRequired | string1–160 characters | |
| When kind is “studio” | ||
| When kind is “rule.fired” | ||
facts[].seqRequired | integer1–9007199254740991 | The journal's order: strictly increasing, assigned by the server. |
facts[].epochRequired | integer0–9007199254740991 | |
facts[].anchorRequired | object | WHERE in the story something happened: |
facts[].anchor.visitRequired | integer1–9007199254740991 | |
facts[].anchor.sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
facts[].anchor.msRequired | integer0–9007199254740991 | A non-negative integer count or time in milliseconds. |
facts[].pinned | boolean | Kept by the AI log's window trims (navigation markers); a rewind still truncates it. |
facts[].ruleIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
| When kind is “quiz.started” | ||
facts[].seqRequired | integer1–9007199254740991 | The journal's order: strictly increasing, assigned by the server. |
facts[].epochRequired | integer0–9007199254740991 | |
facts[].anchorRequired | object | WHERE in the story something happened: |
facts[].anchor.visitRequired | integer1–9007199254740991 | |
facts[].anchor.sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
facts[].anchor.msRequired | integer0–9007199254740991 | A non-negative integer count or time in milliseconds. |
facts[].pinned | boolean | Kept by the AI log's window trims (navigation markers); a rewind still truncates it. |
facts[].quizIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
| When kind is “quiz.skipped” | ||
facts[].seqRequired | integer1–9007199254740991 | The journal's order: strictly increasing, assigned by the server. |
facts[].epochRequired | integer0–9007199254740991 | |
facts[].anchorRequired | object | WHERE in the story something happened: |
facts[].anchor.visitRequired | integer1–9007199254740991 | |
facts[].anchor.sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
facts[].anchor.msRequired | integer0–9007199254740991 | A non-negative integer count or time in milliseconds. |
facts[].pinned | boolean | Kept by the AI log's window trims (navigation markers); a rewind still truncates it. |
facts[].quizIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
| When kind is “navigation.declined” | ||
facts[].seqRequired | integer1–9007199254740991 | The journal's order: strictly increasing, assigned by the server. |
facts[].epochRequired | integer0–9007199254740991 | |
facts[].anchorRequired | object | WHERE in the story something happened: |
facts[].anchor.visitRequired | integer1–9007199254740991 | |
facts[].anchor.sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
facts[].anchor.msRequired | integer0–9007199254740991 | A non-negative integer count or time in milliseconds. |
facts[].pinned | boolean | Kept by the AI log's window trims (navigation markers); a rewind still truncates it. |
facts[].toBeatIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
| When kind is “navigation.arrived” | ||
facts[].seqRequired | integer1–9007199254740991 | The journal's order: strictly increasing, assigned by the server. |
facts[].epochRequired | integer0–9007199254740991 | |
facts[].anchorRequired | object | WHERE in the story something happened: |
facts[].anchor.visitRequired | integer1–9007199254740991 | |
facts[].anchor.sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
facts[].anchor.msRequired | integer0–9007199254740991 | A non-negative integer count or time in milliseconds. |
facts[].pinned | boolean | Kept by the AI log's window trims (navigation markers); a rewind still truncates it. |
facts[].toBeatId | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
facts[].landingRequired | "chapterStart" | "hold" | "origin" | |
| When kind is “viewer.context” | ||
facts[].seqRequired | integer1–9007199254740991 | The journal's order: strictly increasing, assigned by the server. |
facts[].epochRequired | integer0–9007199254740991 | |
facts[].anchorRequired | object | WHERE in the story something happened: |
facts[].anchor.visitRequired | integer1–9007199254740991 | |
facts[].anchor.sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
facts[].anchor.msRequired | integer0–9007199254740991 | A non-negative integer count or time in milliseconds. |
facts[].pinned | boolean | Kept by the AI log's window trims (navigation markers); a rewind still truncates it. |
facts[].valuesRequired | record of string | number | boolean | |
| When kind is “session.completed” | ||
facts[].seqRequired | integer1–9007199254740991 | The journal's order: strictly increasing, assigned by the server. |
facts[].epochRequired | integer0–9007199254740991 | |
facts[].anchorRequired | object | WHERE in the story something happened: |
facts[].anchor.visitRequired | integer1–9007199254740991 | |
facts[].anchor.sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
facts[].anchor.msRequired | integer0–9007199254740991 | A non-negative integer count or time in milliseconds. |
facts[].pinned | boolean | Kept by the AI log's window trims (navigation markers); a rewind still truncates it. |
| When kind is “quiz.submitted” | ||
facts[].seqRequired | integer1–9007199254740991 | The journal's order: strictly increasing, assigned by the server. |
facts[].epochRequired | integer0–9007199254740991 | |
facts[].anchorRequired | object | WHERE in the story something happened: |
facts[].anchor.visitRequired | integer1–9007199254740991 | |
facts[].anchor.sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
facts[].anchor.msRequired | integer0–9007199254740991 | A non-negative integer count or time in milliseconds. |
facts[].pinned | boolean | Kept by the AI log's window trims (navigation markers); a rewind still truncates it. |
facts[].quizIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
facts[].questionIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
facts[].respondentRequired | one of | Who answers a quiz: the viewer, or the viewer playing a cast member ("as Cat"). |
| When kind is “viewer” | ||
| When kind is “character” | ||
facts[].respondent.castIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
facts[].responseRequired | one 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” | ||
facts[].response.choiceIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
| When kind is “choices” | ||
facts[].response.choiceIdsRequired | string[]1–10 items | |
| When kind is “boolean” | ||
facts[].response.valueRequired | boolean | |
| When kind is “text” | ||
facts[].response.textRequired | string≤ 2000 characters | |
facts[].correctRequired | boolean | |
facts[].pointsRequired | number≥ 0 | |
facts[].attemptRequired | integer1–9007199254740991 | |
facts[].finalRequired | boolean | Correct, or out of attempts: the question is finished. |
| When kind is “navigation.requested” | ||
facts[].seqRequired | integer1–9007199254740991 | The journal's order: strictly increasing, assigned by the server. |
facts[].epochRequired | integer0–9007199254740991 | |
facts[].anchorRequired | object | WHERE in the story something happened: |
facts[].anchor.visitRequired | integer1–9007199254740991 | |
facts[].anchor.sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
facts[].anchor.msRequired | integer0–9007199254740991 | A non-negative integer count or time in milliseconds. |
facts[].pinned | boolean | Kept by the AI log's window trims (navigation markers); a rewind still truncates it. |
facts[].toBeatIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
facts[].landingRequired | "chapterStart" | "hold" | |
facts[].requestRequired | string≤ 2000 characters | |
| When kind is “navigation.confirmed” | ||
facts[].seqRequired | integer1–9007199254740991 | The journal's order: strictly increasing, assigned by the server. |
facts[].epochRequired | integer0–9007199254740991 | |
facts[].anchorRequired | object | WHERE in the story something happened: |
facts[].anchor.visitRequired | integer1–9007199254740991 | |
facts[].anchor.sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
facts[].anchor.msRequired | integer0–9007199254740991 | A non-negative integer count or time in milliseconds. |
facts[].pinned | boolean | Kept by the AI log's window trims (navigation markers); a rewind still truncates it. |
facts[].toBeatIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
facts[].landingRequired | "chapterStart" | "hold" | |
facts[].request | string≤ 2000 characters | The request the erased |
| When kind is “navigation.visitStarted” | ||
facts[].seqRequired | integer1–9007199254740991 | The journal's order: strictly increasing, assigned by the server. |
facts[].epochRequired | integer0–9007199254740991 | |
facts[].anchorRequired | object | WHERE in the story something happened: |
facts[].anchor.visitRequired | integer1–9007199254740991 | |
facts[].anchor.sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
facts[].anchor.msRequired | integer0–9007199254740991 | A non-negative integer count or time in milliseconds. |
facts[].pinned | boolean | Kept by the AI log's window trims (navigation markers); a rewind still truncates it. |
facts[].visitRequired | integer1–9007199254740991 | |
facts[].fromBeatId | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
facts[].toBeatId | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
facts[].returned | boolean | |
| When kind is “conversation.turn” | ||
facts[].seqRequired | integer1–9007199254740991 | The journal's order: strictly increasing, assigned by the server. |
facts[].epochRequired | integer0–9007199254740991 | |
facts[].anchorRequired | object | WHERE in the story something happened: |
facts[].anchor.visitRequired | integer1–9007199254740991 | |
facts[].anchor.sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
facts[].anchor.msRequired | integer0–9007199254740991 | A non-negative integer count or time in milliseconds. |
facts[].pinned | boolean | Kept by the AI log's window trims (navigation markers); a rewind still truncates it. |
facts[].beatIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
facts[].turnIdRequired | string1–160 characters | |
| When kind is “session.rewound” | ||
facts[].seqRequired | integer1–9007199254740991 | The journal's order: strictly increasing, assigned by the server. |
facts[].epochRequired | integer0–9007199254740991 | |
facts[].anchorRequired | object | WHERE in the story something happened: |
facts[].anchor.visitRequired | integer1–9007199254740991 | |
facts[].anchor.sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
facts[].anchor.msRequired | integer0–9007199254740991 | A non-negative integer count or time in milliseconds. |
facts[].pinned | boolean | Kept by the AI log's window trims (navigation markers); a rewind still truncates it. |
facts[].toRequired | object | WHERE in the story something happened: |
facts[].to.visitRequired | integer1–9007199254740991 | |
facts[].to.sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
facts[].to.msRequired | integer0–9007199254740991 | A non-negative integer count or time in milliseconds. |
| When kind is “object.updated” | ||
facts[].seqRequired | integer1–9007199254740991 | The journal's order: strictly increasing, assigned by the server. |
facts[].epochRequired | integer0–9007199254740991 | |
facts[].anchorRequired | object | WHERE in the story something happened: |
facts[].anchor.visitRequired | integer1–9007199254740991 | |
facts[].anchor.sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
facts[].anchor.msRequired | integer0–9007199254740991 | A non-negative integer count or time in milliseconds. |
facts[].pinned | boolean | Kept by the AI log's window trims (navigation markers); a rewind still truncates it. |
facts[].entityIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
facts[].params | record of boolean | number | string | (boolean | number | string)[] | |
facts[].states | record of string | |
facts[].causeRequired | one of | Why an object's Interaction Graph changed: a fact's causes, or a viewer's input (the listener that heard it), the graph on its own (a transition ending, a tween landing, a timer), the host page through the SDK. |
| When kind is “rule” | ||
facts[].cause.ruleIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
facts[].cause.sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
| When kind is “event” | ||
facts[].cause.eventIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
facts[].cause.sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
| When kind is “behavior” | ||
facts[].cause.entityIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
facts[].cause.behaviorIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
| When kind is “ai” | ||
facts[].cause.turnIdRequired | string1–160 characters | |
| When kind is “studio” | ||
| When kind is “input” | ||
facts[].cause.listenerId | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
| When kind is “graph” | ||
| When kind is “host” | ||
Errors
400invalid_input401invalid_token,session_expired404not_found409stale_epoch
Read the session's state
GET/v1/sessions/{id}/stateViewer token
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idRequired | path | string | The viewer session's id ( |
sinceSeq | query | integerDefault 0 |
Response 200
Read the session's state
| Field | Type | Description |
|---|---|---|
epochRequired | integer0–9007199254740991 | |
headSeqRequired | integer0–9007199254740991 | |
stateRequired | object | The session's state as the server folded it ( |
state.epochRequired | integer0–9007199254740991 | |
state.lastSeqRequired | integer0–9007199254740991 | |
state.headRequired | object | The furthest story position recorded: the forward-only cursor. |
state.head.visitRequired | integer1–9007199254740991 | |
state.head.sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
state.head.msRequired | integer0–9007199254740991 | A non-negative integer count or time in milliseconds. |
state.visitRequired | integer1–9007199254740991 | |
state.sceneId | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
state.openBeatId | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
state.varsRequired | record of boolean | number | string | |
state.objectsRequired | record of object | |
state.objects{}.clicksRequired | integer0–9007199254740991 | |
state.objects{}.state | string | A toggle's state; an Interaction Graph's layer |
state.objects{}.spread | integer0–9007199254740991 | A book's spread (kept forever). |
state.objects{}.visible | boolean | |
state.objects{}.params | record of boolean | number | string | (boolean | number | string)[] | Added within v1 (P17): an Interaction Graph's committed session params that changed. |
state.objects{}.states | record of string | Added within v1 (P17): an Interaction Graph's committed session layers' states, by layer. |
state.beatsRequired | record of object | |
state.beats{}.entriesRequired | integer0–9007199254740991 | |
state.beats{}.visitedRequired | boolean | |
state.beats{}.completedRequired | boolean | |
state.beats{}.skippedRequired | boolean | |
state.beats{}.turnsRequired | integer0–9007199254740991 | |
state.beats{}.openRequired | boolean | |
state.beats{}.lastExit | string | |
state.quizzesRequired | record of object | |
state.quizzes{}.startedRequired | boolean | |
state.quizzes{}.skippedRequired | boolean | |
state.quizzes{}.questionsRequired | record of object | |
state.quizzes{}.questions{}.attemptsRequired | integer0–9007199254740991 | |
state.quizzes{}.questions{}.answeredRequired | boolean | |
state.quizzes{}.questions{}.correctRequired | boolean | |
state.quizzes{}.questions{}.finishedRequired | boolean | |
state.quizzes{}.questions{}.pointsRequired | number≥ 0 | |
state.quizzes{}.questions{}.response | one 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” | ||
state.quizzes{}.questions{}.response.choiceIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
| When kind is “choices” | ||
state.quizzes{}.questions{}.response.choiceIdsRequired | string[]1–10 items | |
| When kind is “boolean” | ||
state.quizzes{}.questions{}.response.valueRequired | boolean | |
| When kind is “text” | ||
state.quizzes{}.questions{}.response.textRequired | string≤ 2000 characters | |
state.quizzes{}.questions{}.respondent | one of | Who answers a quiz: the viewer, or the viewer playing a cast member ("as Cat"). |
| When kind is “viewer” | ||
| When kind is “character” | ||
state.quizzes{}.questions{}.respondent.castIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
state.quizzes{}.last | object | |
state.quizzes{}.last.questionIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
state.quizzes{}.last.responseRequired | one 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” | ||
state.quizzes{}.last.response.choiceIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
| When kind is “choices” | ||
state.quizzes{}.last.response.choiceIdsRequired | string[]1–10 items | |
| When kind is “boolean” | ||
state.quizzes{}.last.response.valueRequired | boolean | |
| When kind is “text” | ||
state.quizzes{}.last.response.textRequired | string≤ 2000 characters | |
state.quizzes{}.last.respondentRequired | one of | Who answers a quiz: the viewer, or the viewer playing a cast member ("as Cat"). |
| When kind is “viewer” | ||
| When kind is “character” | ||
state.quizzes{}.last.respondent.castIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
state.quizzes{}.last.correctRequired | boolean | |
state.quizzes{}.last.pointsRequired | number≥ 0 | |
state.quizzes{}.last.attemptRequired | integer1–9007199254740991 | |
state.quizzes{}.scoreRequired | number≥ 0 | |
state.quizzes{}.correctCountRequired | integer0–9007199254740991 | |
state.quizzes{}.completedRequired | boolean | |
state.sceneEntriesRequired | record of integer | |
state.firedOnceRequired | record of string | |
state.turnsRequired | integer0–9007199254740991 | |
state.completedRequired | boolean | |
state.viewerContextRequired | record of string | number | boolean | |
state.pendingNavigation | object | |
state.pendingNavigation.toBeatIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
state.pendingNavigation.landingRequired | string≥ 1 characters | |
state.pendingNavigation.anchorRequired | object | WHERE in the story something happened: |
state.pendingNavigation.anchor.visitRequired | integer1–9007199254740991 | |
state.pendingNavigation.anchor.sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
state.pendingNavigation.anchor.msRequired | integer0–9007199254740991 | A non-negative integer count or time in milliseconds. |
factsRequired | any[] | A journal as a reader takes it: every fact it knows, in order; a fact of a kind it does not know (a newer server's) is skipped rather than failing the whole answer. |
moreRequired | boolean | More kept facts follow the last one here: ask again with |
Errors
400invalid_input401invalid_token,session_expired404not_found
Read the session's result
GET/v1/sessions/{id}/resultViewer token
Needs the results scope. Other formats are the learner report: a page, a Word document or a workbook.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idRequired | path | string | The viewer session's id ( |
format | query | "json" | "html" | "docx" | "xlsx"Default "json" | |
template | query | string | A report template of the project ( |
Response 200
GET /v1/sessions/{id}/result (format=json).
| Field | Type | Description |
|---|---|---|
sessionRequired | object | |
session.idRequired | string (uuid) | A server-minted id (sessions, projects, releases, users): a UUID. |
session.projectIdRequired | string (uuid) | A server-minted id (sessions, projects, releases, users): a UUID. |
session.releaseId | string (uuid) | The release played (a draft session has none). |
session.titleRequired | string | |
session.startedAtRequired | string (date-time) | An ISO 8601 instant. |
session.lastSeenAtRequired | string (date-time) | An ISO 8601 instant. |
session.durationMsRequired | integer0–9007199254740991 | |
resultRequired | object | |
result.viewerRequired | one 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.externalUserIdRequired | string≥ 1 characters | |
| When kind is “account” | ||
result.viewer.userIdRequired | string (uuid) | A server-minted id (sessions, projects, releases, users): a UUID. |
result.epochRequired | integer0–9007199254740991 | |
result.completedRequired | boolean | |
result.beatsRequired | object[] | |
result.beats[].beatIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
result.beats[].aliasRequired | string | |
result.beats[].nameRequired | string | |
result.beats[].sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
result.beats[].requiredRequired | boolean | |
result.beats[].statusRequired | string≥ 1 characters |
|
result.beats[].turnsRequired | integer0–9007199254740991 | |
result.quizzesRequired | object[] | |
result.quizzes[].quizIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
result.quizzes[].aliasRequired | string | |
result.quizzes[].title | string | |
result.quizzes[].statusRequired | string≥ 1 characters |
|
result.quizzes[].scoreRequired | number≥ 0 | |
result.quizzes[].maxScoreRequired | number≥ 0 | |
result.quizzes[].percentRequired | number0–100 | 0–100, one decimal. |
result.quizzes[].passed | boolean | Against the quiz's pass mark, once the quiz is completed. |
result.quizzes[].correctCountRequired | integer0–9007199254740991 | |
result.quizzes[].questionsRequired | object[] | |
result.quizzes[].questions[].questionIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
result.quizzes[].questions[].keyRequired | string | |
result.quizzes[].questions[].prompt | string | |
result.quizzes[].questions[].answeredRequired | boolean | |
result.quizzes[].questions[].correctRequired | boolean | |
result.quizzes[].questions[].pointsRequired | number≥ 0 | |
result.quizzes[].questions[].maxPointsRequired | number≥ 0 | |
result.quizzes[].questions[].attemptsRequired | integer0–9007199254740991 | |
result.quizzes[].questions[].response | one 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.choiceIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
| When kind is “choices” | ||
result.quizzes[].questions[].response.choiceIdsRequired | string[]1–10 items | |
| When kind is “boolean” | ||
result.quizzes[].questions[].response.valueRequired | boolean | |
| When kind is “text” | ||
result.quizzes[].questions[].response.textRequired | string≤ 2000 characters | |
result.quizzes[].questions[].responseText | string | The response in words: the chosen choices' text, true / false, the typed answer. |
result.quizzes[].questions[].respondent | one 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.castIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
result.variablesRequired | object[] | |
result.variables[].variableIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
result.variables[].aliasRequired | string | |
result.variables[].typeRequired | string≥ 1 characters | |
result.variables[].valueRequired | boolean | number | string | A story value: a boolean, a number, or a short text (a choice is its key). |
result.itemsRequired | object[] | |
result.items[].resultIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
result.items[].aliasRequired | string | |
result.items[].labelRequired | string | |
result.items[].kindRequired | string≥ 1 characters |
|
result.items[].valueRequired | number | boolean | |
result.totalsRequired | object | |
result.totals.scoreRequired | number≥ 0 | |
result.totals.maxScoreRequired | number≥ 0 | |
result.totals.percentRequired | number0–100 | |
result.totals.passed | boolean | |
result.totals.correctCountRequired | integer0–9007199254740991 | |
result.totals.questionCountRequired | integer0–9007199254740991 | |
result.totals.answeredCountRequired | integer0–9007199254740991 | |
result.totals.beatsCompletedRequired | integer0–9007199254740991 | |
result.totals.beatsTotalRequired | integer0–9007199254740991 | |
result.totals.completionRequired | number0–1 | Completed Beats ÷ all Beats (1 when there are none). |
text/html — format=html
application/vnd.openxmlformats-officedocument.wordprocessingml.document — format=docx
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet — format=xlsx
Errors
400invalid_input401invalid_token,session_expired403scope_required404not_found
Send content-free telemetry
POST/v1/sessions/{id}/telemetryNo bearer token
The viewer token rides in the body (token): navigator.sendBeacon sets no headers, and may send the JSON as text/plain. Unknown or malformed events are dropped, never stored.
The viewer token travels in the request body (token), not in a header.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idRequired | path | string | The viewer session's id ( |
Request body (application/json, text/plain)
| Field | Type | Description |
|---|---|---|
tokenRequired | string1–4096 characters | |
eventsRequired | object[]1–50 items | |
events[].typeRequired | string1–64 characters |
Response 202
202: what was kept. A beacon never reads it; a fetch with keepalive may.
| Field | Type | Description |
|---|---|---|
acceptedRequired | integer0–9007199254740991 | |
droppedRequired | integer0–9007199254740991 |
Errors
400invalid_input401invalid_token413body_too_large415unsupported_media_type
Report the browser's lines of a debug capture
POST/v1/sessions/{id}/debug-logNo bearer token
The browser's lines of a staff debug capture: kept only while the session, its project or its signed-in viewer is being captured.
Offered when the mint announces the debug-log capability. Every answer says whether the session is being captured (capturing); while it is not, every line is dropped and the browser stops reporting. Send no lines to ask. Lines are redacted before they are stored: no query strings, no tokens.
The viewer token travels in the request body (token), not in a header.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idRequired | path | string | The viewer session's id ( |
Request body (application/json, text/plain)
| Field | Type | Description |
|---|---|---|
tokenRequired | string1–4096 characters | |
linesRequired | object[]≤ 50 items | |
lines[].kindRequired | string1–32 characters |
Response 202
202: what was kept, and whether the session is being captured now.
| Field | Type | Description |
|---|---|---|
acceptedRequired | integer0–9007199254740991 | Lines kept for the capture. |
droppedRequired | integer0–9007199254740991 | Lines refused: malformed, of an unknown kind, or sent while nothing is captured. |
capturingRequired | boolean | A capture covers this session now: keep reporting. False: stop until asked again. |
Errors
400invalid_input401invalid_token403scope_required413body_too_large415unsupported_media_type429rate_limited
Report a problem with the experience
POST/v1/sessions/{id}/reportsViewer token
The Live Room's notice (DSA Art. 16); a token past its expiry still reports, for a day.
At most five reports a session an hour.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idRequired | path | string | The viewer session's id ( |
Request body (application/json)
| Field | Type | Description |
|---|---|---|
reasonRequired | "inappropriate" | "ai_misbehaviour" | "copyright" | "broken" | "other" | |
details | string1–2000 characters | What the viewer adds in their own words. |
Response 201
201: the confirmation of receipt.
| Field | Type | Description |
|---|---|---|
idRequired | string (uuid) | The notice's reference. |
receivedAtRequired | string (date-time) | An ISO 8601 instant. |
Errors
400invalid_input401invalid_token404not_found429rate_limited
Open a protected release's file
GET/v1/media/t/{token}/{path}No bearer token
Only for a protected release (a secure-only or privately listed project) whose media host is this server: use assets.base as the mint gives it — it already carries the token. A heartbeat hands out a fresh base before the token expires.
The token is part of the path: the link itself is the credential.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
tokenRequired | path | string | The session's asset token, as |
pathRequired | path | string | The file, after the token: the release JSON or a content-addressed file (it may contain slashes). |
Response 302
A redirect to a short-lived download of the file, never cached. An unknown, tampered or expired token and a path the token does not open are the same 404.
Errors
404not_found