Skip to content
Jami3D
Developer docs menu

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)

FieldTypeDescription
projectIdstring (uuid)

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

listingstring1–80 characters

What a request may name instead of a project id: a marketplace listing's slug.

release"latest" | string (uuid)default "latest"
publishableKeystring1–200 characters
viewerTokenstring1–4096 characters
shareTokenstring16–128 characters
localestring≤ 35 characters

The viewer's language (live AI replies follow it); absent: the release's content language.

parentOriginstring≤ 2048 characters
resumeSessionIdstring (uuid)

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

Response 201

Start a viewer session

FieldTypeDescription
sessionRequiredobject
session.idRequiredstring (uuid)

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

session.surfaceRequiredstring≥ 1 characters

One of V1_SURFACES; a reader treats a value it does not know as watch.

session.epochRequiredinteger0–9007199254740991
session.expiresAtRequiredstring (date-time)

When the token expires: heartbeat before then.

session.endsAtRequiredstring (date-time)

No heartbeat extends the session past this: mint again (with resumeSessionId).

session.heartbeatMsRequiredinteger0–9007199254740991
session.testRequiredboolean

Minted from the Studio or with a test key: kept out of the creator's analytics.

session.childDirectedRequiredboolean

The project is made for children: no persistent identifiers, stricter AI.

session.localeRequiredstring≤ 35 characters

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

session.resumedFromstring (uuid)

A resumed session: the session it continues…

session.resumeobject

…and where its story stands — the furthest anchor recorded and the last known playback position.

session.resume.headRequiredobject

WHERE in the story something happened: visit starts at 1 and grows only under navigationHistory: keep; sceneId names a scene of the session's release (the server maps it to the scene's index and compares anchors lexicographically as (visit, sceneIndex, ms)); ms is authored scene time — a fact recorded during a hold carries the hold's time.

session.resume.head.visitRequiredinteger1–9007199254740991
session.resume.head.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.

session.resume.head.msRequiredinteger0–9007199254740991

A non-negative integer count or time in milliseconds.

session.resume.positionobject

A position on the story axis without a visit: a scene and an authored time in it.

session.resume.position.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.

session.resume.position.msRequiredinteger0–9007199254740991

A non-negative integer count or time in milliseconds.

session.resumeOfferobject

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 resumeSessionId set to sessionId. Absent: nothing to offer (an anonymous viewer, a child-directed project, a server from before).

session.resumeOffer.sessionIdRequiredstring (uuid)

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

session.resumeOffer.headRequiredobject

WHERE in the story something happened: visit starts at 1 and grows only under navigationHistory: keep; sceneId names a scene of the session's release (the server maps it to the scene's index and compares anchors lexicographically as (visit, sceneIndex, ms)); ms is authored scene time — a fact recorded during a hold carries the hold's time.

session.resumeOffer.head.visitRequiredinteger1–9007199254740991
session.resumeOffer.head.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.

session.resumeOffer.head.msRequiredinteger0–9007199254740991

A non-negative integer count or time in milliseconds.

session.resumeOffer.positionobject

A position on the story axis without a visit: a scene and an authored time in it.

session.resumeOffer.position.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.

session.resumeOffer.position.msRequiredinteger0–9007199254740991

A non-negative integer count or time in milliseconds.

session.resumeOffer.seenAtRequiredstring (date-time)

When that session was last seen.

session.conversationRetentionDaysinteger0–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).

tokenRequiredstring≥ 1 characters
releaseRequiredobject
release.idRequiredstring≥ 1 characters

A release id; a Studio draft's is the draft's own (draft-{revision}).

release.kindRequiredstring≥ 1 characters

publish, preview or draft.

release.numberinteger0–9007199254740991

Absent for a draft.

release.manifestUrlRequiredstring≥ 1 characters

The release manifest (@jami3d/protocol/release): absolute, or root-relative (a draft; a protected release served by the app's own media route). A protected release's carries the session's asset token in its path, like assets.base.

assetsRequiredobject
assets.baseRequiredstring≥ 1 characters

Where the release's files are: a file's URL is base + its path (singleFilePath / bundleFilePath in namespace for content-addressed files, the manifest's paths for the release JSON). A protected release's base carries the session's asset token as a PATH segment (https://media.jami.live/t/{token}/) — never a query string: use it as it is. A heartbeat may hand out a new one (assets of its answer).

assets.tokenstring≥ 1 characters

A protected release: the asset token its base carries, on its own (for a client that tracks when it changes). It expires — a heartbeat hands out a fresh base before then. Never append it to a URL: base already carries it.

assets.namespacestring≥ 1 characters

The namespace of the content-addressed paths: one of V1_ASSET_NAMESPACES. Absent (a server from before protected releases, a Studio draft): pub. A reader that does not know the value cannot address the files and turns the release away as built for a newer player.

aiRequiredobject

The mint answer's AI section: the status, the effective limits and how to unlock text and voice.

ai.levelRequired"off" | "text" | "voice"
ai.reasonsRequiredstring[]
ai.scopesRequiredstring[]
ai.voiceRepliesstring1–32 characters

Added within v1: whether live replies are spoken here — the project's setting, one of V1_VOICE_REPLIES (open: a value a reader does not know reads as absent). Changing it moves the AI watch's stamp. Absent: this answer does not say (a server from before, an answer that reads the session alone — the events answer); keep what an earlier answer said, and with none, ask for spoken replies as before (output.audio true when audio can play).

ai.needsVerificationRequiredboolean

Text and voice need a human check first (POST …/verify); false when the mint was trusted.

ai.verificationobject

How a session's live AI must be unlocked, when it must.

ai.verification.kindRequiredstring≥ 1 characters

turnstile: render Cloudflare Turnstile with siteKey, post its token to …/verify.

ai.verification.siteKeyRequiredstring≥ 1 characters
ai.limitsRequiredobject

The effective per-viewer limits of live AI (the project's, tightened by an API key's).

ai.limits.turnsPerSessionRequiredinteger0–9007199254740991
ai.limits.turnsPerViewerDayRequiredinteger0–9007199254740991
ai.limits.voiceSecondsPerViewerDayRequiredinteger0–9007199254740991
ai.stampstring1–64 characters

Added within v1 (P8): the AI watch's stamp this status was decided under — what the first GET …/ai sends as since. Absent (a server from before the watch): the first watch answer carries the status.

brandingRequiredobject
branding.accentstring

The project's Live Room accent (#rrggbb); host options still win over it.

branding.badgeRequiredboolean

Show the "Made with Jami3D" badge (plans without removable branding).

protocolRequiredobject
protocol.versionRequiredinteger0–9007199254740991
protocol.capabilitiesRequiredstring[]
embedobject

An embed's session (embed, secure_embed) only: what the host page may be told. conversationEvents — the Live Room forwards the conversation's messages to the host (aimessage) — holds only when the project exposes them AND the publishable key (or the grant) carries conversation_events.

embed.conversationEventsRequiredboolean

Errors

  • 400invalid_input
  • 401key_invalid
  • 403origin_not_allowed
  • 404release_not_found
  • 429rate_limited
  • 503retry_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

NameInTypeDescription
idRequiredpathstring

The viewer session's id (session.id in the mint answer).

Request body (application/json)

FieldTypeDescription
positionobject

A position on the story axis without a visit: a scene and an authored time in it.

position.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.

position.msRequiredinteger0–9007199254740991

A non-negative integer count or time in milliseconds.

Response 200

Keep a session alive

FieldTypeDescription
tokenstring≥ 1 characters

A fresh token, when the old one had less than 10 minutes left; keep the old one otherwise.

expiresAtRequiredstring (date-time)

An ISO 8601 instant.

endsAtRequiredstring (date-time)

An ISO 8601 instant.

epochRequiredinteger0–9007199254740991
aiRequiredobject

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 text and shows "Live answers are paused" at off.

ai.levelRequired"off" | "text" | "voice"
ai.reasonsRequiredstring[]
ai.scopesRequiredstring[]
ai.voiceRepliesstring1–32 characters

Added within v1: whether live replies are spoken here — the project's setting, one of V1_VOICE_REPLIES (open: a value a reader does not know reads as absent). Changing it moves the AI watch's stamp. Absent: this answer does not say (a server from before, an answer that reads the session alone — the events answer); keep what an earlier answer said, and with none, ask for spoken replies as before (output.audio true when audio can play).

assetsRequiredobject

Where the session's files are now (a release's session; {} for a Studio draft and from a server before protected releases): base with its namespace and, for a protected release, the token it carries — as the mint's assets say them. They change when the asset token is refreshed (every few hours) and when the release's files move between the public CDN and the media host (the owner changed the project's embed policy or listing; the old place keeps serving until this answer said the new one). A client loads every file from now on from a base that differs from its own, keeps what it loaded, and keeps its own base when base is absent.

assets.tokenstring≥ 1 characters
assets.basestring≥ 1 characters
assets.namespacestring≥ 1 characters
protocolobject

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, objectUpdates). Absent (a server from before): keep what the mint said.

protocol.versionRequiredinteger0–9007199254740991
protocol.capabilitiesRequiredstring[]

Errors

  • 400invalid_input
  • 401invalid_token, session_expired
  • 404not_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

NameInTypeDescription
idRequiredpathstring

The viewer session's id (session.id in the mint answer).

Request body (application/json)

FieldTypeDescription
turnstileTokenRequiredstring1–2048 characters

Response 200

Verify the viewer (Turnstile)

FieldTypeDescription
tokenRequiredstring≥ 1 characters
expiresAtRequiredstring (date-time)

An ISO 8601 instant.

aiRequiredobject

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 text and shows "Live answers are paused" at off.

ai.levelRequired"off" | "text" | "voice"
ai.reasonsRequiredstring[]
ai.scopesRequiredstring[]
ai.voiceRepliesstring1–32 characters

Added within v1: whether live replies are spoken here — the project's setting, one of V1_VOICE_REPLIES (open: a value a reader does not know reads as absent). Changing it moves the AI watch's stamp. Absent: this answer does not say (a server from before, an answer that reads the session alone — the events answer); keep what an earlier answer said, and with none, ask for spoken replies as before (output.audio true when audio can play).

Errors

  • 401invalid_token, session_expired
  • 403verification_failed
  • 404not_found
  • 429rate_limited
  • 503retry_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

NameInTypeDescription
idRequiredpathstring

The viewer session's id (session.id in the mint answer).

sincequerystring

Response 200

Watch the session's live-AI level

FieldTypeDescription
stampRequiredstring1–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.

aiobject

The session's live-AI status, decided now: present when since was absent or is not stamp; absent when nothing that decides it changed (keep what you hold).

ai.levelRequired"off" | "text" | "voice"
ai.reasonsRequiredstring[]
ai.scopesRequiredstring[]
ai.voiceRepliesstring1–32 characters

Added within v1: whether live replies are spoken here — the project's setting, one of V1_VOICE_REPLIES (open: a value a reader does not know reads as absent). Changing it moves the AI watch's stamp. Absent: this answer does not say (a server from before, an answer that reads the session alone — the events answer); keep what an earlier answer said, and with none, ask for spoken replies as before (output.audio true when audio can play).

pollMsRequiredinteger0–9007199254740991

When to ask again, ms, while the Live Room stays visible.

Errors

  • 400invalid_input
  • 401invalid_token, session_expired
  • 404not_found
  • 429rate_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

NameInTypeDescription
idRequiredpathstring

The viewer session's id (session.id in the mint answer).

syncquery"0" | "1"

Request body (application/json)

FieldTypeDescription
epochRequiredinteger0–9007199254740991
seqRequiredinteger1–9007199254740991
factsRequiredobject[]1–50 items
facts[].kindRequiredstring1–64 characters
facts[].anchorRequiredobject

WHERE in the story something happened: visit starts at 1 and grows only under navigationHistory: keep; sceneId names a scene of the session's release (the server maps it to the scene's index and compares anchors lexicographically as (visit, sceneIndex, ms)); ms is authored scene time — a fact recorded during a hold carries the hold's time.

facts[].anchor.visitRequiredinteger1–9007199254740991
facts[].anchor.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.

facts[].anchor.msRequiredinteger0–9007199254740991

A non-negative integer count or time in milliseconds.

Response 200

Record the player's facts

FieldTypeDescription
epochRequiredinteger0–9007199254740991
ackSeqRequiredinteger0–9007199254740991

Every fact numbered up to here is settled (journaled or refused): drop it from the outbox.

headSeqRequiredinteger0–9007199254740991

The journal's last sequence number.

refusedobject[]
refused[].seqRequiredinteger1–9007199254740991

The refused fact's number (the request's seq + its index).

refused[].codeRequiredstring≥ 1 characters
refused[].messageRequiredstring
resyncboolean

The player's state may differ from the server's: read GET …/state before going on.

factsany[]

Facts the SERVER wrote because of this request (a graded answer's quiz.submitted), in journal order: apply them.

gradeobject

?sync=1: the grade of the request's quiz answer (absent when it was refused).

grade.correctRequiredboolean
grade.pointsRequirednumber≥ 0
grade.feedbackstring

The feedback for this answer: the chosen choice's own, else the question's correct / incorrect.

grade.correctAnswerone of

Present when the quiz's reveal policy shows it now.

When kind is “choice”
grade.correctAnswer.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”
grade.correctAnswer.choiceIdsRequiredstring[]
When kind is “boolean”
grade.correctAnswer.valueRequiredboolean
When kind is “text”
grade.correctAnswer.acceptedRequiredstring[]
grade.attemptsLeftRequiredinteger0–9007199254740991
grade.quizScoreRequirednumber≥ 0

The quiz's score after this answer.

grade.completedRequiredboolean

Every question of the quiz is finished.

aiRequiredobject

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 text and shows "Live answers are paused" at off.

ai.levelRequired"off" | "text" | "voice"
ai.reasonsRequiredstring[]
ai.scopesRequiredstring[]
ai.voiceRepliesstring1–32 characters

Added within v1: whether live replies are spoken here — the project's setting, one of V1_VOICE_REPLIES (open: a value a reader does not know reads as absent). Changing it moves the AI watch's stamp. Absent: this answer does not say (a server from before, an answer that reads the session alone — the events answer); keep what an earlier answer said, and with none, ask for spoken replies as before (output.audio true when audio can play).

Errors

  • 400invalid_input
  • 401invalid_token, session_expired
  • 404not_found
  • 409stale_epoch, seq_gap, rewind_required
  • 413body_too_large
  • 415unsupported_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

NameInTypeDescription
idRequiredpathstring

The viewer session's id (session.id in the mint answer).

Request body (application/json)

FieldTypeDescription
epochRequiredinteger0–9007199254740991
toRequiredobject

WHERE in the story something happened: visit starts at 1 and grows only under navigationHistory: keep; sceneId names a scene of the session's release (the server maps it to the scene's index and compares anchors lexicographically as (visit, sceneIndex, ms)); ms is authored scene time — a fact recorded during a hold carries the hold's time.

to.visitRequiredinteger1–9007199254740991
to.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.

to.msRequiredinteger0–9007199254740991

A non-negative integer count or time in milliseconds.

dryRunbooleandefault false
rewindIdstring (uuid)

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

Response 200

Go back in the story

FieldTypeDescription
dryRunRequiredboolean
epochRequiredinteger0–9007199254740991

A dry run: the session's epoch; a commit: the NEW epoch every later write carries.

headSeqRequiredinteger0–9007199254740991
impactRequiredobject

What a rewind erases: interaction facts, quiz answers, viewer questions; the quizzes whose answers go.

impact.eventsRequiredinteger0–9007199254740991
impact.quizAnswersRequiredinteger0–9007199254740991
impact.turnsRequiredinteger0–9007199254740991
impact.quizIdsRequiredstring[]
factone of

A commit: the session.rewound fact that ends the old epoch (apply it, then refold).

When kind is “scene.entered”
fact.seqRequiredinteger1–9007199254740991

The journal's order: strictly increasing, assigned by the server.

fact.epochRequiredinteger0–9007199254740991
fact.anchorRequiredobject

WHERE in the story something happened: visit starts at 1 and grows only under navigationHistory: keep; sceneId names a scene of the session's release (the server maps it to the scene's index and compares anchors lexicographically as (visit, sceneIndex, ms)); ms is authored scene time — a fact recorded during a hold carries the hold's time.

fact.anchor.visitRequiredinteger1–9007199254740991
fact.anchor.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.

fact.anchor.msRequiredinteger0–9007199254740991

A non-negative integer count or time in milliseconds.

fact.pinnedboolean

Kept by the AI log's window trims (navigation markers); a rewind still truncates it.

fact.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.

When kind is “beat.entered”
fact.seqRequiredinteger1–9007199254740991

The journal's order: strictly increasing, assigned by the server.

fact.epochRequiredinteger0–9007199254740991
fact.anchorRequiredobject

WHERE in the story something happened: visit starts at 1 and grows only under navigationHistory: keep; sceneId names a scene of the session's release (the server maps it to the scene's index and compares anchors lexicographically as (visit, sceneIndex, ms)); ms is authored scene time — a fact recorded during a hold carries the hold's time.

fact.anchor.visitRequiredinteger1–9007199254740991
fact.anchor.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.

fact.anchor.msRequiredinteger0–9007199254740991

A non-negative integer count or time in milliseconds.

fact.pinnedboolean

Kept by the AI log's window trims (navigation markers); a rewind still truncates it.

fact.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.

fact.varsRequiredrecord of boolean | number | string
When kind is “beat.exited”
fact.seqRequiredinteger1–9007199254740991

The journal's order: strictly increasing, assigned by the server.

fact.epochRequiredinteger0–9007199254740991
fact.anchorRequiredobject

WHERE in the story something happened: visit starts at 1 and grows only under navigationHistory: keep; sceneId names a scene of the session's release (the server maps it to the scene's index and compares anchors lexicographically as (visit, sceneIndex, ms)); ms is authored scene time — a fact recorded during a hold carries the hold's time.

fact.anchor.visitRequiredinteger1–9007199254740991
fact.anchor.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.

fact.anchor.msRequiredinteger0–9007199254740991

A non-negative integer count or time in milliseconds.

fact.pinnedboolean

Kept by the AI log's window trims (navigation markers); a rewind still truncates it.

fact.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.

fact.reasonRequired"continued" | "timer" | "satisfied" | "timeout" | "jump" | "seek" | "rewind" | "sceneExit"
When kind is “beat.skipped”
fact.seqRequiredinteger1–9007199254740991

The journal's order: strictly increasing, assigned by the server.

fact.epochRequiredinteger0–9007199254740991
fact.anchorRequiredobject

WHERE in the story something happened: visit starts at 1 and grows only under navigationHistory: keep; sceneId names a scene of the session's release (the server maps it to the scene's index and compares anchors lexicographically as (visit, sceneIndex, ms)); ms is authored scene time — a fact recorded during a hold carries the hold's time.

fact.anchor.visitRequiredinteger1–9007199254740991
fact.anchor.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.

fact.anchor.msRequiredinteger0–9007199254740991

A non-negative integer count or time in milliseconds.

fact.pinnedboolean

Kept by the AI log's window trims (navigation markers); a rewind still truncates it.

fact.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.

When kind is “seek.forward”
fact.seqRequiredinteger1–9007199254740991

The journal's order: strictly increasing, assigned by the server.

fact.epochRequiredinteger0–9007199254740991
fact.anchorRequiredobject

WHERE in the story something happened: visit starts at 1 and grows only under navigationHistory: keep; sceneId names a scene of the session's release (the server maps it to the scene's index and compares anchors lexicographically as (visit, sceneIndex, ms)); ms is authored scene time — a fact recorded during a hold carries the hold's time.

fact.anchor.visitRequiredinteger1–9007199254740991
fact.anchor.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.

fact.anchor.msRequiredinteger0–9007199254740991

A non-negative integer count or time in milliseconds.

fact.pinnedboolean

Kept by the AI log's window trims (navigation markers); a rewind still truncates it.

fact.fromRequiredobject

A position on the story axis without a visit: a scene and an authored time in it.

fact.from.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.

fact.from.msRequiredinteger0–9007199254740991

A non-negative integer count or time in milliseconds.

When kind is “object.interacted”
fact.seqRequiredinteger1–9007199254740991

The journal's order: strictly increasing, assigned by the server.

fact.epochRequiredinteger0–9007199254740991
fact.anchorRequiredobject

WHERE in the story something happened: visit starts at 1 and grows only under navigationHistory: keep; sceneId names a scene of the session's release (the server maps it to the scene's index and compares anchors lexicographically as (visit, sceneIndex, ms)); ms is authored scene time — a fact recorded during a hold carries the hold's time.

fact.anchor.visitRequiredinteger1–9007199254740991
fact.anchor.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.

fact.anchor.msRequiredinteger0–9007199254740991

A non-negative integer count or time in milliseconds.

fact.pinnedboolean

Kept by the AI log's window trims (navigation markers); a rewind still truncates it.

fact.entityIdRequiredstring1–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.

fact.behaviorIdstring1–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.

fact.regionstring1–64 characters
fact.changeobject

What changed about an object: a toggle's state, a book's spread, a visibility override.

fact.change.statestring1–64 characters
fact.change.spreadinteger0–9007199254740991
fact.change.visibleboolean
fact.listenerIdstring1–160 characters

Added within v1 (P17): the graph listener that heard the input.

fact.inputstring1–32 characters

Added within v1 (P17): the input (click, key, …), an open vocabulary.

fact.localnumber[]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.seqRequiredinteger1–9007199254740991

The journal's order: strictly increasing, assigned by the server.

fact.epochRequiredinteger0–9007199254740991
fact.anchorRequiredobject

WHERE in the story something happened: visit starts at 1 and grows only under navigationHistory: keep; sceneId names a scene of the session's release (the server maps it to the scene's index and compares anchors lexicographically as (visit, sceneIndex, ms)); ms is authored scene time — a fact recorded during a hold carries the hold's time.

fact.anchor.visitRequiredinteger1–9007199254740991
fact.anchor.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.

fact.anchor.msRequiredinteger0–9007199254740991

A non-negative integer count or time in milliseconds.

fact.pinnedboolean

Kept by the AI log's window trims (navigation markers); a rewind still truncates it.

fact.entityIdRequiredstring1–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.

fact.changeRequiredobject

What changed about an object: a toggle's state, a book's spread, a visibility override.

fact.change.statestring1–64 characters
fact.change.spreadinteger0–9007199254740991
fact.change.visibleboolean
fact.causeRequiredone 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 (studio: Set variable), which the server admits on Studio (draft) sessions only.

When kind is “rule”
fact.cause.ruleIdRequiredstring1–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.

fact.cause.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.

When kind is “event”
fact.cause.eventIdRequiredstring1–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.

fact.cause.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.

When kind is “behavior”
fact.cause.entityIdRequiredstring1–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.

fact.cause.behaviorIdRequiredstring1–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 “ai”
fact.cause.turnIdRequiredstring1–160 characters
When kind is “studio”
When kind is “var.changed”
fact.seqRequiredinteger1–9007199254740991

The journal's order: strictly increasing, assigned by the server.

fact.epochRequiredinteger0–9007199254740991
fact.anchorRequiredobject

WHERE in the story something happened: visit starts at 1 and grows only under navigationHistory: keep; sceneId names a scene of the session's release (the server maps it to the scene's index and compares anchors lexicographically as (visit, sceneIndex, ms)); ms is authored scene time — a fact recorded during a hold carries the hold's time.

fact.anchor.visitRequiredinteger1–9007199254740991
fact.anchor.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.

fact.anchor.msRequiredinteger0–9007199254740991

A non-negative integer count or time in milliseconds.

fact.pinnedboolean

Kept by the AI log's window trims (navigation markers); a rewind still truncates it.

fact.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.

fact.valueRequiredboolean | number | string

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

fact.causeRequiredone 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 (studio: Set variable), which the server admits on Studio (draft) sessions only.

When kind is “rule”
fact.cause.ruleIdRequiredstring1–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.

fact.cause.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.

When kind is “event”
fact.cause.eventIdRequiredstring1–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.

fact.cause.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.

When kind is “behavior”
fact.cause.entityIdRequiredstring1–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.

fact.cause.behaviorIdRequiredstring1–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 “ai”
fact.cause.turnIdRequiredstring1–160 characters
When kind is “studio”
When kind is “rule.fired”
fact.seqRequiredinteger1–9007199254740991

The journal's order: strictly increasing, assigned by the server.

fact.epochRequiredinteger0–9007199254740991
fact.anchorRequiredobject

WHERE in the story something happened: visit starts at 1 and grows only under navigationHistory: keep; sceneId names a scene of the session's release (the server maps it to the scene's index and compares anchors lexicographically as (visit, sceneIndex, ms)); ms is authored scene time — a fact recorded during a hold carries the hold's time.

fact.anchor.visitRequiredinteger1–9007199254740991
fact.anchor.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.

fact.anchor.msRequiredinteger0–9007199254740991

A non-negative integer count or time in milliseconds.

fact.pinnedboolean

Kept by the AI log's window trims (navigation markers); a rewind still truncates it.

fact.ruleIdRequiredstring1–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 “quiz.started”
fact.seqRequiredinteger1–9007199254740991

The journal's order: strictly increasing, assigned by the server.

fact.epochRequiredinteger0–9007199254740991
fact.anchorRequiredobject

WHERE in the story something happened: visit starts at 1 and grows only under navigationHistory: keep; sceneId names a scene of the session's release (the server maps it to the scene's index and compares anchors lexicographically as (visit, sceneIndex, ms)); ms is authored scene time — a fact recorded during a hold carries the hold's time.

fact.anchor.visitRequiredinteger1–9007199254740991
fact.anchor.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.

fact.anchor.msRequiredinteger0–9007199254740991

A non-negative integer count or time in milliseconds.

fact.pinnedboolean

Kept by the AI log's window trims (navigation markers); a rewind still truncates it.

fact.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.

When kind is “quiz.skipped”
fact.seqRequiredinteger1–9007199254740991

The journal's order: strictly increasing, assigned by the server.

fact.epochRequiredinteger0–9007199254740991
fact.anchorRequiredobject

WHERE in the story something happened: visit starts at 1 and grows only under navigationHistory: keep; sceneId names a scene of the session's release (the server maps it to the scene's index and compares anchors lexicographically as (visit, sceneIndex, ms)); ms is authored scene time — a fact recorded during a hold carries the hold's time.

fact.anchor.visitRequiredinteger1–9007199254740991
fact.anchor.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.

fact.anchor.msRequiredinteger0–9007199254740991

A non-negative integer count or time in milliseconds.

fact.pinnedboolean

Kept by the AI log's window trims (navigation markers); a rewind still truncates it.

fact.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.

When kind is “navigation.declined”
fact.seqRequiredinteger1–9007199254740991

The journal's order: strictly increasing, assigned by the server.

fact.epochRequiredinteger0–9007199254740991
fact.anchorRequiredobject

WHERE in the story something happened: visit starts at 1 and grows only under navigationHistory: keep; sceneId names a scene of the session's release (the server maps it to the scene's index and compares anchors lexicographically as (visit, sceneIndex, ms)); ms is authored scene time — a fact recorded during a hold carries the hold's time.

fact.anchor.visitRequiredinteger1–9007199254740991
fact.anchor.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.

fact.anchor.msRequiredinteger0–9007199254740991

A non-negative integer count or time in milliseconds.

fact.pinnedboolean

Kept by the AI log's window trims (navigation markers); a rewind still truncates it.

fact.toBeatIdRequiredstring1–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 “navigation.arrived”
fact.seqRequiredinteger1–9007199254740991

The journal's order: strictly increasing, assigned by the server.

fact.epochRequiredinteger0–9007199254740991
fact.anchorRequiredobject

WHERE in the story something happened: visit starts at 1 and grows only under navigationHistory: keep; sceneId names a scene of the session's release (the server maps it to the scene's index and compares anchors lexicographically as (visit, sceneIndex, ms)); ms is authored scene time — a fact recorded during a hold carries the hold's time.

fact.anchor.visitRequiredinteger1–9007199254740991
fact.anchor.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.

fact.anchor.msRequiredinteger0–9007199254740991

A non-negative integer count or time in milliseconds.

fact.pinnedboolean

Kept by the AI log's window trims (navigation markers); a rewind still truncates it.

fact.toBeatIdstring1–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.

fact.landingRequired"chapterStart" | "hold" | "origin"
When kind is “viewer.context”
fact.seqRequiredinteger1–9007199254740991

The journal's order: strictly increasing, assigned by the server.

fact.epochRequiredinteger0–9007199254740991
fact.anchorRequiredobject

WHERE in the story something happened: visit starts at 1 and grows only under navigationHistory: keep; sceneId names a scene of the session's release (the server maps it to the scene's index and compares anchors lexicographically as (visit, sceneIndex, ms)); ms is authored scene time — a fact recorded during a hold carries the hold's time.

fact.anchor.visitRequiredinteger1–9007199254740991
fact.anchor.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.

fact.anchor.msRequiredinteger0–9007199254740991

A non-negative integer count or time in milliseconds.

fact.pinnedboolean

Kept by the AI log's window trims (navigation markers); a rewind still truncates it.

fact.valuesRequiredrecord of string | number | boolean
When kind is “session.completed”
fact.seqRequiredinteger1–9007199254740991

The journal's order: strictly increasing, assigned by the server.

fact.epochRequiredinteger0–9007199254740991
fact.anchorRequiredobject

WHERE in the story something happened: visit starts at 1 and grows only under navigationHistory: keep; sceneId names a scene of the session's release (the server maps it to the scene's index and compares anchors lexicographically as (visit, sceneIndex, ms)); ms is authored scene time — a fact recorded during a hold carries the hold's time.

fact.anchor.visitRequiredinteger1–9007199254740991
fact.anchor.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.

fact.anchor.msRequiredinteger0–9007199254740991

A non-negative integer count or time in milliseconds.

fact.pinnedboolean

Kept by the AI log's window trims (navigation markers); a rewind still truncates it.

When kind is “quiz.submitted”
fact.seqRequiredinteger1–9007199254740991

The journal's order: strictly increasing, assigned by the server.

fact.epochRequiredinteger0–9007199254740991
fact.anchorRequiredobject

WHERE in the story something happened: visit starts at 1 and grows only under navigationHistory: keep; sceneId names a scene of the session's release (the server maps it to the scene's index and compares anchors lexicographically as (visit, sceneIndex, ms)); ms is authored scene time — a fact recorded during a hold carries the hold's time.

fact.anchor.visitRequiredinteger1–9007199254740991
fact.anchor.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.

fact.anchor.msRequiredinteger0–9007199254740991

A non-negative integer count or time in milliseconds.

fact.pinnedboolean

Kept by the AI log's window trims (navigation markers); a rewind still truncates it.

fact.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.

fact.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.

fact.respondentRequiredone 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.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.

fact.responseRequiredone 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.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”
fact.response.choiceIdsRequiredstring[]1–10 items
When kind is “boolean”
fact.response.valueRequiredboolean
When kind is “text”
fact.response.textRequiredstring≤ 2000 characters
fact.correctRequiredboolean
fact.pointsRequirednumber≥ 0
fact.attemptRequiredinteger1–9007199254740991
fact.finalRequiredboolean

Correct, or out of attempts: the question is finished.

When kind is “navigation.requested”
fact.seqRequiredinteger1–9007199254740991

The journal's order: strictly increasing, assigned by the server.

fact.epochRequiredinteger0–9007199254740991
fact.anchorRequiredobject

WHERE in the story something happened: visit starts at 1 and grows only under navigationHistory: keep; sceneId names a scene of the session's release (the server maps it to the scene's index and compares anchors lexicographically as (visit, sceneIndex, ms)); ms is authored scene time — a fact recorded during a hold carries the hold's time.

fact.anchor.visitRequiredinteger1–9007199254740991
fact.anchor.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.

fact.anchor.msRequiredinteger0–9007199254740991

A non-negative integer count or time in milliseconds.

fact.pinnedboolean

Kept by the AI log's window trims (navigation markers); a rewind still truncates it.

fact.toBeatIdRequiredstring1–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.

fact.landingRequired"chapterStart" | "hold"
fact.requestRequiredstring≤ 2000 characters
When kind is “navigation.confirmed”
fact.seqRequiredinteger1–9007199254740991

The journal's order: strictly increasing, assigned by the server.

fact.epochRequiredinteger0–9007199254740991
fact.anchorRequiredobject

WHERE in the story something happened: visit starts at 1 and grows only under navigationHistory: keep; sceneId names a scene of the session's release (the server maps it to the scene's index and compares anchors lexicographically as (visit, sceneIndex, ms)); ms is authored scene time — a fact recorded during a hold carries the hold's time.

fact.anchor.visitRequiredinteger1–9007199254740991
fact.anchor.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.

fact.anchor.msRequiredinteger0–9007199254740991

A non-negative integer count or time in milliseconds.

fact.pinnedboolean

Kept by the AI log's window trims (navigation markers); a rewind still truncates it.

fact.toBeatIdRequiredstring1–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.

fact.landingRequired"chapterStart" | "hold"
fact.requeststring≤ 2000 characters

The request the erased navigation.requested carried (it survives the truncation here).

When kind is “navigation.visitStarted”
fact.seqRequiredinteger1–9007199254740991

The journal's order: strictly increasing, assigned by the server.

fact.epochRequiredinteger0–9007199254740991
fact.anchorRequiredobject

WHERE in the story something happened: visit starts at 1 and grows only under navigationHistory: keep; sceneId names a scene of the session's release (the server maps it to the scene's index and compares anchors lexicographically as (visit, sceneIndex, ms)); ms is authored scene time — a fact recorded during a hold carries the hold's time.

fact.anchor.visitRequiredinteger1–9007199254740991
fact.anchor.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.

fact.anchor.msRequiredinteger0–9007199254740991

A non-negative integer count or time in milliseconds.

fact.pinnedboolean

Kept by the AI log's window trims (navigation markers); a rewind still truncates it.

fact.visitRequiredinteger1–9007199254740991
fact.fromBeatIdstring1–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.

fact.toBeatIdstring1–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.

fact.returnedboolean
When kind is “conversation.turn”
fact.seqRequiredinteger1–9007199254740991

The journal's order: strictly increasing, assigned by the server.

fact.epochRequiredinteger0–9007199254740991
fact.anchorRequiredobject

WHERE in the story something happened: visit starts at 1 and grows only under navigationHistory: keep; sceneId names a scene of the session's release (the server maps it to the scene's index and compares anchors lexicographically as (visit, sceneIndex, ms)); ms is authored scene time — a fact recorded during a hold carries the hold's time.

fact.anchor.visitRequiredinteger1–9007199254740991
fact.anchor.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.

fact.anchor.msRequiredinteger0–9007199254740991

A non-negative integer count or time in milliseconds.

fact.pinnedboolean

Kept by the AI log's window trims (navigation markers); a rewind still truncates it.

fact.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.

fact.turnIdRequiredstring1–160 characters
When kind is “session.rewound”
fact.seqRequiredinteger1–9007199254740991

The journal's order: strictly increasing, assigned by the server.

fact.epochRequiredinteger0–9007199254740991
fact.anchorRequiredobject

WHERE in the story something happened: visit starts at 1 and grows only under navigationHistory: keep; sceneId names a scene of the session's release (the server maps it to the scene's index and compares anchors lexicographically as (visit, sceneIndex, ms)); ms is authored scene time — a fact recorded during a hold carries the hold's time.

fact.anchor.visitRequiredinteger1–9007199254740991
fact.anchor.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.

fact.anchor.msRequiredinteger0–9007199254740991

A non-negative integer count or time in milliseconds.

fact.pinnedboolean

Kept by the AI log's window trims (navigation markers); a rewind still truncates it.

fact.toRequiredobject

WHERE in the story something happened: visit starts at 1 and grows only under navigationHistory: keep; sceneId names a scene of the session's release (the server maps it to the scene's index and compares anchors lexicographically as (visit, sceneIndex, ms)); ms is authored scene time — a fact recorded during a hold carries the hold's time.

fact.to.visitRequiredinteger1–9007199254740991
fact.to.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.

fact.to.msRequiredinteger0–9007199254740991

A non-negative integer count or time in milliseconds.

When kind is “object.updated”
fact.seqRequiredinteger1–9007199254740991

The journal's order: strictly increasing, assigned by the server.

fact.epochRequiredinteger0–9007199254740991
fact.anchorRequiredobject

WHERE in the story something happened: visit starts at 1 and grows only under navigationHistory: keep; sceneId names a scene of the session's release (the server maps it to the scene's index and compares anchors lexicographically as (visit, sceneIndex, ms)); ms is authored scene time — a fact recorded during a hold carries the hold's time.

fact.anchor.visitRequiredinteger1–9007199254740991
fact.anchor.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.

fact.anchor.msRequiredinteger0–9007199254740991

A non-negative integer count or time in milliseconds.

fact.pinnedboolean

Kept by the AI log's window trims (navigation markers); a rewind still truncates it.

fact.entityIdRequiredstring1–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.

fact.paramsrecord of boolean | number | string | (boolean | number | string)[]
fact.statesrecord of string
fact.causeRequiredone 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.ruleIdRequiredstring1–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.

fact.cause.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.

When kind is “event”
fact.cause.eventIdRequiredstring1–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.

fact.cause.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.

When kind is “behavior”
fact.cause.entityIdRequiredstring1–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.

fact.cause.behaviorIdRequiredstring1–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 “ai”
fact.cause.turnIdRequiredstring1–160 characters
When kind is “studio”
When kind is “input”
fact.cause.listenerIdstring1–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 “graph”
When kind is “host”
facts(one of)[]≥ 1 items

A commit (added within v1, P8): every fact it journaled, in order — fact first, then the narrator's backward navigation the rewind confirmed (navigation.confirmed, pinned), when it confirmed one. Apply them all, then refold: nothing else needs reading back. Absent (a dry run, a server from before): apply fact; a confirmed navigation is only in GET …/state.

When kind is “scene.entered”
facts[].seqRequiredinteger1–9007199254740991

The journal's order: strictly increasing, assigned by the server.

facts[].epochRequiredinteger0–9007199254740991
facts[].anchorRequiredobject

WHERE in the story something happened: visit starts at 1 and grows only under navigationHistory: keep; sceneId names a scene of the session's release (the server maps it to the scene's index and compares anchors lexicographically as (visit, sceneIndex, ms)); ms is authored scene time — a fact recorded during a hold carries the hold's time.

facts[].anchor.visitRequiredinteger1–9007199254740991
facts[].anchor.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.

facts[].anchor.msRequiredinteger0–9007199254740991

A non-negative integer count or time in milliseconds.

facts[].pinnedboolean

Kept by the AI log's window trims (navigation markers); a rewind still truncates it.

facts[].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.

When kind is “beat.entered”
facts[].seqRequiredinteger1–9007199254740991

The journal's order: strictly increasing, assigned by the server.

facts[].epochRequiredinteger0–9007199254740991
facts[].anchorRequiredobject

WHERE in the story something happened: visit starts at 1 and grows only under navigationHistory: keep; sceneId names a scene of the session's release (the server maps it to the scene's index and compares anchors lexicographically as (visit, sceneIndex, ms)); ms is authored scene time — a fact recorded during a hold carries the hold's time.

facts[].anchor.visitRequiredinteger1–9007199254740991
facts[].anchor.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.

facts[].anchor.msRequiredinteger0–9007199254740991

A non-negative integer count or time in milliseconds.

facts[].pinnedboolean

Kept by the AI log's window trims (navigation markers); a rewind still truncates it.

facts[].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.

facts[].varsRequiredrecord of boolean | number | string
When kind is “beat.exited”
facts[].seqRequiredinteger1–9007199254740991

The journal's order: strictly increasing, assigned by the server.

facts[].epochRequiredinteger0–9007199254740991
facts[].anchorRequiredobject

WHERE in the story something happened: visit starts at 1 and grows only under navigationHistory: keep; sceneId names a scene of the session's release (the server maps it to the scene's index and compares anchors lexicographically as (visit, sceneIndex, ms)); ms is authored scene time — a fact recorded during a hold carries the hold's time.

facts[].anchor.visitRequiredinteger1–9007199254740991
facts[].anchor.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.

facts[].anchor.msRequiredinteger0–9007199254740991

A non-negative integer count or time in milliseconds.

facts[].pinnedboolean

Kept by the AI log's window trims (navigation markers); a rewind still truncates it.

facts[].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.

facts[].reasonRequired"continued" | "timer" | "satisfied" | "timeout" | "jump" | "seek" | "rewind" | "sceneExit"
When kind is “beat.skipped”
facts[].seqRequiredinteger1–9007199254740991

The journal's order: strictly increasing, assigned by the server.

facts[].epochRequiredinteger0–9007199254740991
facts[].anchorRequiredobject

WHERE in the story something happened: visit starts at 1 and grows only under navigationHistory: keep; sceneId names a scene of the session's release (the server maps it to the scene's index and compares anchors lexicographically as (visit, sceneIndex, ms)); ms is authored scene time — a fact recorded during a hold carries the hold's time.

facts[].anchor.visitRequiredinteger1–9007199254740991
facts[].anchor.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.

facts[].anchor.msRequiredinteger0–9007199254740991

A non-negative integer count or time in milliseconds.

facts[].pinnedboolean

Kept by the AI log's window trims (navigation markers); a rewind still truncates it.

facts[].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.

When kind is “seek.forward”
facts[].seqRequiredinteger1–9007199254740991

The journal's order: strictly increasing, assigned by the server.

facts[].epochRequiredinteger0–9007199254740991
facts[].anchorRequiredobject

WHERE in the story something happened: visit starts at 1 and grows only under navigationHistory: keep; sceneId names a scene of the session's release (the server maps it to the scene's index and compares anchors lexicographically as (visit, sceneIndex, ms)); ms is authored scene time — a fact recorded during a hold carries the hold's time.

facts[].anchor.visitRequiredinteger1–9007199254740991
facts[].anchor.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.

facts[].anchor.msRequiredinteger0–9007199254740991

A non-negative integer count or time in milliseconds.

facts[].pinnedboolean

Kept by the AI log's window trims (navigation markers); a rewind still truncates it.

facts[].fromRequiredobject

A position on the story axis without a visit: a scene and an authored time in it.

facts[].from.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.

facts[].from.msRequiredinteger0–9007199254740991

A non-negative integer count or time in milliseconds.

When kind is “object.interacted”
facts[].seqRequiredinteger1–9007199254740991

The journal's order: strictly increasing, assigned by the server.

facts[].epochRequiredinteger0–9007199254740991
facts[].anchorRequiredobject

WHERE in the story something happened: visit starts at 1 and grows only under navigationHistory: keep; sceneId names a scene of the session's release (the server maps it to the scene's index and compares anchors lexicographically as (visit, sceneIndex, ms)); ms is authored scene time — a fact recorded during a hold carries the hold's time.

facts[].anchor.visitRequiredinteger1–9007199254740991
facts[].anchor.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.

facts[].anchor.msRequiredinteger0–9007199254740991

A non-negative integer count or time in milliseconds.

facts[].pinnedboolean

Kept by the AI log's window trims (navigation markers); a rewind still truncates it.

facts[].entityIdRequiredstring1–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.

facts[].behaviorIdstring1–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.

facts[].regionstring1–64 characters
facts[].changeobject

What changed about an object: a toggle's state, a book's spread, a visibility override.

facts[].change.statestring1–64 characters
facts[].change.spreadinteger0–9007199254740991
facts[].change.visibleboolean
facts[].listenerIdstring1–160 characters

Added within v1 (P17): the graph listener that heard the input.

facts[].inputstring1–32 characters

Added within v1 (P17): the input (click, key, …), an open vocabulary.

facts[].localnumber[]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[].seqRequiredinteger1–9007199254740991

The journal's order: strictly increasing, assigned by the server.

facts[].epochRequiredinteger0–9007199254740991
facts[].anchorRequiredobject

WHERE in the story something happened: visit starts at 1 and grows only under navigationHistory: keep; sceneId names a scene of the session's release (the server maps it to the scene's index and compares anchors lexicographically as (visit, sceneIndex, ms)); ms is authored scene time — a fact recorded during a hold carries the hold's time.

facts[].anchor.visitRequiredinteger1–9007199254740991
facts[].anchor.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.

facts[].anchor.msRequiredinteger0–9007199254740991

A non-negative integer count or time in milliseconds.

facts[].pinnedboolean

Kept by the AI log's window trims (navigation markers); a rewind still truncates it.

facts[].entityIdRequiredstring1–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.

facts[].changeRequiredobject

What changed about an object: a toggle's state, a book's spread, a visibility override.

facts[].change.statestring1–64 characters
facts[].change.spreadinteger0–9007199254740991
facts[].change.visibleboolean
facts[].causeRequiredone 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 (studio: Set variable), which the server admits on Studio (draft) sessions only.

When kind is “rule”
facts[].cause.ruleIdRequiredstring1–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.

facts[].cause.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.

When kind is “event”
facts[].cause.eventIdRequiredstring1–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.

facts[].cause.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.

When kind is “behavior”
facts[].cause.entityIdRequiredstring1–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.

facts[].cause.behaviorIdRequiredstring1–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 “ai”
facts[].cause.turnIdRequiredstring1–160 characters
When kind is “studio”
When kind is “var.changed”
facts[].seqRequiredinteger1–9007199254740991

The journal's order: strictly increasing, assigned by the server.

facts[].epochRequiredinteger0–9007199254740991
facts[].anchorRequiredobject

WHERE in the story something happened: visit starts at 1 and grows only under navigationHistory: keep; sceneId names a scene of the session's release (the server maps it to the scene's index and compares anchors lexicographically as (visit, sceneIndex, ms)); ms is authored scene time — a fact recorded during a hold carries the hold's time.

facts[].anchor.visitRequiredinteger1–9007199254740991
facts[].anchor.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.

facts[].anchor.msRequiredinteger0–9007199254740991

A non-negative integer count or time in milliseconds.

facts[].pinnedboolean

Kept by the AI log's window trims (navigation markers); a rewind still truncates it.

facts[].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.

facts[].valueRequiredboolean | number | string

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

facts[].causeRequiredone 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 (studio: Set variable), which the server admits on Studio (draft) sessions only.

When kind is “rule”
facts[].cause.ruleIdRequiredstring1–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.

facts[].cause.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.

When kind is “event”
facts[].cause.eventIdRequiredstring1–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.

facts[].cause.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.

When kind is “behavior”
facts[].cause.entityIdRequiredstring1–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.

facts[].cause.behaviorIdRequiredstring1–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 “ai”
facts[].cause.turnIdRequiredstring1–160 characters
When kind is “studio”
When kind is “rule.fired”
facts[].seqRequiredinteger1–9007199254740991

The journal's order: strictly increasing, assigned by the server.

facts[].epochRequiredinteger0–9007199254740991
facts[].anchorRequiredobject

WHERE in the story something happened: visit starts at 1 and grows only under navigationHistory: keep; sceneId names a scene of the session's release (the server maps it to the scene's index and compares anchors lexicographically as (visit, sceneIndex, ms)); ms is authored scene time — a fact recorded during a hold carries the hold's time.

facts[].anchor.visitRequiredinteger1–9007199254740991
facts[].anchor.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.

facts[].anchor.msRequiredinteger0–9007199254740991

A non-negative integer count or time in milliseconds.

facts[].pinnedboolean

Kept by the AI log's window trims (navigation markers); a rewind still truncates it.

facts[].ruleIdRequiredstring1–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 “quiz.started”
facts[].seqRequiredinteger1–9007199254740991

The journal's order: strictly increasing, assigned by the server.

facts[].epochRequiredinteger0–9007199254740991
facts[].anchorRequiredobject

WHERE in the story something happened: visit starts at 1 and grows only under navigationHistory: keep; sceneId names a scene of the session's release (the server maps it to the scene's index and compares anchors lexicographically as (visit, sceneIndex, ms)); ms is authored scene time — a fact recorded during a hold carries the hold's time.

facts[].anchor.visitRequiredinteger1–9007199254740991
facts[].anchor.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.

facts[].anchor.msRequiredinteger0–9007199254740991

A non-negative integer count or time in milliseconds.

facts[].pinnedboolean

Kept by the AI log's window trims (navigation markers); a rewind still truncates it.

facts[].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.

When kind is “quiz.skipped”
facts[].seqRequiredinteger1–9007199254740991

The journal's order: strictly increasing, assigned by the server.

facts[].epochRequiredinteger0–9007199254740991
facts[].anchorRequiredobject

WHERE in the story something happened: visit starts at 1 and grows only under navigationHistory: keep; sceneId names a scene of the session's release (the server maps it to the scene's index and compares anchors lexicographically as (visit, sceneIndex, ms)); ms is authored scene time — a fact recorded during a hold carries the hold's time.

facts[].anchor.visitRequiredinteger1–9007199254740991
facts[].anchor.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.

facts[].anchor.msRequiredinteger0–9007199254740991

A non-negative integer count or time in milliseconds.

facts[].pinnedboolean

Kept by the AI log's window trims (navigation markers); a rewind still truncates it.

facts[].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.

When kind is “navigation.declined”
facts[].seqRequiredinteger1–9007199254740991

The journal's order: strictly increasing, assigned by the server.

facts[].epochRequiredinteger0–9007199254740991
facts[].anchorRequiredobject

WHERE in the story something happened: visit starts at 1 and grows only under navigationHistory: keep; sceneId names a scene of the session's release (the server maps it to the scene's index and compares anchors lexicographically as (visit, sceneIndex, ms)); ms is authored scene time — a fact recorded during a hold carries the hold's time.

facts[].anchor.visitRequiredinteger1–9007199254740991
facts[].anchor.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.

facts[].anchor.msRequiredinteger0–9007199254740991

A non-negative integer count or time in milliseconds.

facts[].pinnedboolean

Kept by the AI log's window trims (navigation markers); a rewind still truncates it.

facts[].toBeatIdRequiredstring1–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 “navigation.arrived”
facts[].seqRequiredinteger1–9007199254740991

The journal's order: strictly increasing, assigned by the server.

facts[].epochRequiredinteger0–9007199254740991
facts[].anchorRequiredobject

WHERE in the story something happened: visit starts at 1 and grows only under navigationHistory: keep; sceneId names a scene of the session's release (the server maps it to the scene's index and compares anchors lexicographically as (visit, sceneIndex, ms)); ms is authored scene time — a fact recorded during a hold carries the hold's time.

facts[].anchor.visitRequiredinteger1–9007199254740991
facts[].anchor.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.

facts[].anchor.msRequiredinteger0–9007199254740991

A non-negative integer count or time in milliseconds.

facts[].pinnedboolean

Kept by the AI log's window trims (navigation markers); a rewind still truncates it.

facts[].toBeatIdstring1–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.

facts[].landingRequired"chapterStart" | "hold" | "origin"
When kind is “viewer.context”
facts[].seqRequiredinteger1–9007199254740991

The journal's order: strictly increasing, assigned by the server.

facts[].epochRequiredinteger0–9007199254740991
facts[].anchorRequiredobject

WHERE in the story something happened: visit starts at 1 and grows only under navigationHistory: keep; sceneId names a scene of the session's release (the server maps it to the scene's index and compares anchors lexicographically as (visit, sceneIndex, ms)); ms is authored scene time — a fact recorded during a hold carries the hold's time.

facts[].anchor.visitRequiredinteger1–9007199254740991
facts[].anchor.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.

facts[].anchor.msRequiredinteger0–9007199254740991

A non-negative integer count or time in milliseconds.

facts[].pinnedboolean

Kept by the AI log's window trims (navigation markers); a rewind still truncates it.

facts[].valuesRequiredrecord of string | number | boolean
When kind is “session.completed”
facts[].seqRequiredinteger1–9007199254740991

The journal's order: strictly increasing, assigned by the server.

facts[].epochRequiredinteger0–9007199254740991
facts[].anchorRequiredobject

WHERE in the story something happened: visit starts at 1 and grows only under navigationHistory: keep; sceneId names a scene of the session's release (the server maps it to the scene's index and compares anchors lexicographically as (visit, sceneIndex, ms)); ms is authored scene time — a fact recorded during a hold carries the hold's time.

facts[].anchor.visitRequiredinteger1–9007199254740991
facts[].anchor.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.

facts[].anchor.msRequiredinteger0–9007199254740991

A non-negative integer count or time in milliseconds.

facts[].pinnedboolean

Kept by the AI log's window trims (navigation markers); a rewind still truncates it.

When kind is “quiz.submitted”
facts[].seqRequiredinteger1–9007199254740991

The journal's order: strictly increasing, assigned by the server.

facts[].epochRequiredinteger0–9007199254740991
facts[].anchorRequiredobject

WHERE in the story something happened: visit starts at 1 and grows only under navigationHistory: keep; sceneId names a scene of the session's release (the server maps it to the scene's index and compares anchors lexicographically as (visit, sceneIndex, ms)); ms is authored scene time — a fact recorded during a hold carries the hold's time.

facts[].anchor.visitRequiredinteger1–9007199254740991
facts[].anchor.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.

facts[].anchor.msRequiredinteger0–9007199254740991

A non-negative integer count or time in milliseconds.

facts[].pinnedboolean

Kept by the AI log's window trims (navigation markers); a rewind still truncates it.

facts[].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.

facts[].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.

facts[].respondentRequiredone 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.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.

facts[].responseRequiredone 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.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”
facts[].response.choiceIdsRequiredstring[]1–10 items
When kind is “boolean”
facts[].response.valueRequiredboolean
When kind is “text”
facts[].response.textRequiredstring≤ 2000 characters
facts[].correctRequiredboolean
facts[].pointsRequirednumber≥ 0
facts[].attemptRequiredinteger1–9007199254740991
facts[].finalRequiredboolean

Correct, or out of attempts: the question is finished.

When kind is “navigation.requested”
facts[].seqRequiredinteger1–9007199254740991

The journal's order: strictly increasing, assigned by the server.

facts[].epochRequiredinteger0–9007199254740991
facts[].anchorRequiredobject

WHERE in the story something happened: visit starts at 1 and grows only under navigationHistory: keep; sceneId names a scene of the session's release (the server maps it to the scene's index and compares anchors lexicographically as (visit, sceneIndex, ms)); ms is authored scene time — a fact recorded during a hold carries the hold's time.

facts[].anchor.visitRequiredinteger1–9007199254740991
facts[].anchor.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.

facts[].anchor.msRequiredinteger0–9007199254740991

A non-negative integer count or time in milliseconds.

facts[].pinnedboolean

Kept by the AI log's window trims (navigation markers); a rewind still truncates it.

facts[].toBeatIdRequiredstring1–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.

facts[].landingRequired"chapterStart" | "hold"
facts[].requestRequiredstring≤ 2000 characters
When kind is “navigation.confirmed”
facts[].seqRequiredinteger1–9007199254740991

The journal's order: strictly increasing, assigned by the server.

facts[].epochRequiredinteger0–9007199254740991
facts[].anchorRequiredobject

WHERE in the story something happened: visit starts at 1 and grows only under navigationHistory: keep; sceneId names a scene of the session's release (the server maps it to the scene's index and compares anchors lexicographically as (visit, sceneIndex, ms)); ms is authored scene time — a fact recorded during a hold carries the hold's time.

facts[].anchor.visitRequiredinteger1–9007199254740991
facts[].anchor.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.

facts[].anchor.msRequiredinteger0–9007199254740991

A non-negative integer count or time in milliseconds.

facts[].pinnedboolean

Kept by the AI log's window trims (navigation markers); a rewind still truncates it.

facts[].toBeatIdRequiredstring1–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.

facts[].landingRequired"chapterStart" | "hold"
facts[].requeststring≤ 2000 characters

The request the erased navigation.requested carried (it survives the truncation here).

When kind is “navigation.visitStarted”
facts[].seqRequiredinteger1–9007199254740991

The journal's order: strictly increasing, assigned by the server.

facts[].epochRequiredinteger0–9007199254740991
facts[].anchorRequiredobject

WHERE in the story something happened: visit starts at 1 and grows only under navigationHistory: keep; sceneId names a scene of the session's release (the server maps it to the scene's index and compares anchors lexicographically as (visit, sceneIndex, ms)); ms is authored scene time — a fact recorded during a hold carries the hold's time.

facts[].anchor.visitRequiredinteger1–9007199254740991
facts[].anchor.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.

facts[].anchor.msRequiredinteger0–9007199254740991

A non-negative integer count or time in milliseconds.

facts[].pinnedboolean

Kept by the AI log's window trims (navigation markers); a rewind still truncates it.

facts[].visitRequiredinteger1–9007199254740991
facts[].fromBeatIdstring1–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.

facts[].toBeatIdstring1–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.

facts[].returnedboolean
When kind is “conversation.turn”
facts[].seqRequiredinteger1–9007199254740991

The journal's order: strictly increasing, assigned by the server.

facts[].epochRequiredinteger0–9007199254740991
facts[].anchorRequiredobject

WHERE in the story something happened: visit starts at 1 and grows only under navigationHistory: keep; sceneId names a scene of the session's release (the server maps it to the scene's index and compares anchors lexicographically as (visit, sceneIndex, ms)); ms is authored scene time — a fact recorded during a hold carries the hold's time.

facts[].anchor.visitRequiredinteger1–9007199254740991
facts[].anchor.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.

facts[].anchor.msRequiredinteger0–9007199254740991

A non-negative integer count or time in milliseconds.

facts[].pinnedboolean

Kept by the AI log's window trims (navigation markers); a rewind still truncates it.

facts[].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.

facts[].turnIdRequiredstring1–160 characters
When kind is “session.rewound”
facts[].seqRequiredinteger1–9007199254740991

The journal's order: strictly increasing, assigned by the server.

facts[].epochRequiredinteger0–9007199254740991
facts[].anchorRequiredobject

WHERE in the story something happened: visit starts at 1 and grows only under navigationHistory: keep; sceneId names a scene of the session's release (the server maps it to the scene's index and compares anchors lexicographically as (visit, sceneIndex, ms)); ms is authored scene time — a fact recorded during a hold carries the hold's time.

facts[].anchor.visitRequiredinteger1–9007199254740991
facts[].anchor.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.

facts[].anchor.msRequiredinteger0–9007199254740991

A non-negative integer count or time in milliseconds.

facts[].pinnedboolean

Kept by the AI log's window trims (navigation markers); a rewind still truncates it.

facts[].toRequiredobject

WHERE in the story something happened: visit starts at 1 and grows only under navigationHistory: keep; sceneId names a scene of the session's release (the server maps it to the scene's index and compares anchors lexicographically as (visit, sceneIndex, ms)); ms is authored scene time — a fact recorded during a hold carries the hold's time.

facts[].to.visitRequiredinteger1–9007199254740991
facts[].to.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.

facts[].to.msRequiredinteger0–9007199254740991

A non-negative integer count or time in milliseconds.

When kind is “object.updated”
facts[].seqRequiredinteger1–9007199254740991

The journal's order: strictly increasing, assigned by the server.

facts[].epochRequiredinteger0–9007199254740991
facts[].anchorRequiredobject

WHERE in the story something happened: visit starts at 1 and grows only under navigationHistory: keep; sceneId names a scene of the session's release (the server maps it to the scene's index and compares anchors lexicographically as (visit, sceneIndex, ms)); ms is authored scene time — a fact recorded during a hold carries the hold's time.

facts[].anchor.visitRequiredinteger1–9007199254740991
facts[].anchor.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.

facts[].anchor.msRequiredinteger0–9007199254740991

A non-negative integer count or time in milliseconds.

facts[].pinnedboolean

Kept by the AI log's window trims (navigation markers); a rewind still truncates it.

facts[].entityIdRequiredstring1–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.

facts[].paramsrecord of boolean | number | string | (boolean | number | string)[]
facts[].statesrecord of string
facts[].causeRequiredone 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.ruleIdRequiredstring1–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.

facts[].cause.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.

When kind is “event”
facts[].cause.eventIdRequiredstring1–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.

facts[].cause.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.

When kind is “behavior”
facts[].cause.entityIdRequiredstring1–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.

facts[].cause.behaviorIdRequiredstring1–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 “ai”
facts[].cause.turnIdRequiredstring1–160 characters
When kind is “studio”
When kind is “input”
facts[].cause.listenerIdstring1–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 “graph”
When kind is “host”

Errors

  • 400invalid_input
  • 401invalid_token, session_expired
  • 404not_found
  • 409stale_epoch

Read the session's state

GET/v1/sessions/{id}/stateViewer token

Parameters

NameInTypeDescription
idRequiredpathstring

The viewer session's id (session.id in the mint answer).

sinceSeqqueryintegerDefault 0

Response 200

Read the session's state

FieldTypeDescription
epochRequiredinteger0–9007199254740991
headSeqRequiredinteger0–9007199254740991
stateRequiredobject

The session's state as the server folded it (@jami3d/interaction SessionState, positions by scene id): the same function over the same journal gives the player the same state.

state.epochRequiredinteger0–9007199254740991
state.lastSeqRequiredinteger0–9007199254740991
state.headRequiredobject

The furthest story position recorded: the forward-only cursor.

state.head.visitRequiredinteger1–9007199254740991
state.head.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.

state.head.msRequiredinteger0–9007199254740991

A non-negative integer count or time in milliseconds.

state.visitRequiredinteger1–9007199254740991
state.sceneIdstring1–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.

state.openBeatIdstring1–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.

state.varsRequiredrecord of boolean | number | string
state.objectsRequiredrecord of object
state.objects{}.clicksRequiredinteger0–9007199254740991
state.objects{}.statestring

A toggle's state; an Interaction Graph's layer main (kept forever).

state.objects{}.spreadinteger0–9007199254740991

A book's spread (kept forever).

state.objects{}.visibleboolean
state.objects{}.paramsrecord of boolean | number | string | (boolean | number | string)[]

Added within v1 (P17): an Interaction Graph's committed session params that changed.

state.objects{}.statesrecord of string

Added within v1 (P17): an Interaction Graph's committed session layers' states, by layer.

state.beatsRequiredrecord of object
state.beats{}.entriesRequiredinteger0–9007199254740991
state.beats{}.visitedRequiredboolean
state.beats{}.completedRequiredboolean
state.beats{}.skippedRequiredboolean
state.beats{}.turnsRequiredinteger0–9007199254740991
state.beats{}.openRequiredboolean
state.beats{}.lastExitstring
state.quizzesRequiredrecord of object
state.quizzes{}.startedRequiredboolean
state.quizzes{}.skippedRequiredboolean
state.quizzes{}.questionsRequiredrecord of object
state.quizzes{}.questions{}.attemptsRequiredinteger0–9007199254740991
state.quizzes{}.questions{}.answeredRequiredboolean
state.quizzes{}.questions{}.correctRequiredboolean
state.quizzes{}.questions{}.finishedRequiredboolean
state.quizzes{}.questions{}.pointsRequirednumber≥ 0
state.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”
state.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”
state.quizzes{}.questions{}.response.choiceIdsRequiredstring[]1–10 items
When kind is “boolean”
state.quizzes{}.questions{}.response.valueRequiredboolean
When kind is “text”
state.quizzes{}.questions{}.response.textRequiredstring≤ 2000 characters
state.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”
state.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.

state.quizzes{}.lastobject
state.quizzes{}.last.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.

state.quizzes{}.last.responseRequiredone 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.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”
state.quizzes{}.last.response.choiceIdsRequiredstring[]1–10 items
When kind is “boolean”
state.quizzes{}.last.response.valueRequiredboolean
When kind is “text”
state.quizzes{}.last.response.textRequiredstring≤ 2000 characters
state.quizzes{}.last.respondentRequiredone 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.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.

state.quizzes{}.last.correctRequiredboolean
state.quizzes{}.last.pointsRequirednumber≥ 0
state.quizzes{}.last.attemptRequiredinteger1–9007199254740991
state.quizzes{}.scoreRequirednumber≥ 0
state.quizzes{}.correctCountRequiredinteger0–9007199254740991
state.quizzes{}.completedRequiredboolean
state.sceneEntriesRequiredrecord of integer
state.firedOnceRequiredrecord of string
state.turnsRequiredinteger0–9007199254740991
state.completedRequiredboolean
state.viewerContextRequiredrecord of string | number | boolean
state.pendingNavigationobject
state.pendingNavigation.toBeatIdRequiredstring1–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.

state.pendingNavigation.landingRequiredstring≥ 1 characters
state.pendingNavigation.anchorRequiredobject

WHERE in the story something happened: visit starts at 1 and grows only under navigationHistory: keep; sceneId names a scene of the session's release (the server maps it to the scene's index and compares anchors lexicographically as (visit, sceneIndex, ms)); ms is authored scene time — a fact recorded during a hold carries the hold's time.

state.pendingNavigation.anchor.visitRequiredinteger1–9007199254740991
state.pendingNavigation.anchor.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.

state.pendingNavigation.anchor.msRequiredinteger0–9007199254740991

A non-negative integer count or time in milliseconds.

factsRequiredany[]

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.

moreRequiredboolean

More kept facts follow the last one here: ask again with sinceSeq = its seq.

Errors

  • 400invalid_input
  • 401invalid_token, session_expired
  • 404not_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

NameInTypeDescription
idRequiredpathstring

The viewer session's id (session.id in the mint answer).

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

A report template of the project (html, docx, xlsx); absent: the default layout.

Response 200

GET /v1/sessions/{id}/result (format=json).

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).

text/html — format=html

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

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

Errors

  • 400invalid_input
  • 401invalid_token, session_expired
  • 403scope_required
  • 404not_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

NameInTypeDescription
idRequiredpathstring

The viewer session's id (session.id in the mint answer).

Request body (application/json, text/plain)

FieldTypeDescription
tokenRequiredstring1–4096 characters
eventsRequiredobject[]1–50 items
events[].typeRequiredstring1–64 characters

Response 202

202: what was kept. A beacon never reads it; a fetch with keepalive may.

FieldTypeDescription
acceptedRequiredinteger0–9007199254740991
droppedRequiredinteger0–9007199254740991

Errors

  • 400invalid_input
  • 401invalid_token
  • 413body_too_large
  • 415unsupported_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

NameInTypeDescription
idRequiredpathstring

The viewer session's id (session.id in the mint answer).

Request body (application/json, text/plain)

FieldTypeDescription
tokenRequiredstring1–4096 characters
linesRequiredobject[]≤ 50 items
lines[].kindRequiredstring1–32 characters

Response 202

202: what was kept, and whether the session is being captured now.

FieldTypeDescription
acceptedRequiredinteger0–9007199254740991

Lines kept for the capture.

droppedRequiredinteger0–9007199254740991

Lines refused: malformed, of an unknown kind, or sent while nothing is captured.

capturingRequiredboolean

A capture covers this session now: keep reporting. False: stop until asked again.

Errors

  • 400invalid_input
  • 401invalid_token
  • 403scope_required
  • 413body_too_large
  • 415unsupported_media_type
  • 429rate_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

NameInTypeDescription
idRequiredpathstring

The viewer session's id (session.id in the mint answer).

Request body (application/json)

FieldTypeDescription
reasonRequired"inappropriate" | "ai_misbehaviour" | "copyright" | "broken" | "other"
detailsstring1–2000 characters

What the viewer adds in their own words.

Response 201

201: the confirmation of receipt.

FieldTypeDescription
idRequiredstring (uuid)

The notice's reference.

receivedAtRequiredstring (date-time)

An ISO 8601 instant.

Errors

  • 400invalid_input
  • 401invalid_token
  • 404not_found
  • 429rate_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

NameInTypeDescription
tokenRequiredpathstring

The session's asset token, as assets.base of the mint (or a heartbeat) carries it.

pathRequiredpathstring

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