REST API: Server API
Every operation of this group with its parameters, body, answer and errors, as the OpenAPI document states them.
What your backend calls with a secret key (Authorization: Bearer sk_live_…): secure-embed grants, your projects, usage, learners' results and reports. Never from a browser: no CORS, never cached.
Issue a secure-embed grant
POST/v1/viewer-tokensSecret key
Needs the key's sessions capability and a plan with secure embeds. A child-directed project also needs the key's consent attestation.
Request body (application/json)
| Field | Type | Description |
|---|---|---|
projectIdRequired | string (uuid) | A server-minted id (sessions, projects, releases, users): a UUID. |
externalUserIdRequired | string1–200 characters | The integrator's own id for the learner: printable text, no control characters. |
ttlSec | integer60–3600 · default 600 | |
caps | ("playback" | "text_ai" | "voice_ai" | "conversation_events")[]≤ 16 items |
Response 201
Issue a secure-embed grant
| Field | Type | Description |
|---|---|---|
viewerTokenRequired | string≥ 1 characters | The single-use grant: |
expiresAtRequired | string (date-time) | Exchange it before this; a used or expired grant answers 401 |
cardTokenRequired | string≥ 1 characters |
|
cardTokenExpiresAtRequired | string (date-time) | An ISO 8601 instant. |
capabilitiesRequired | string[] | What the session will be allowed (the request's |
Errors
400invalid_input401key_invalid403scope_required404not_found429rate_limited
List your projects
GET/v1/projectsSecret key
Needs the projects capability. A project-scoped key sees its projects only.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
limit | query | integerDefault 50 | |
cursor | query | string (uuid) | The last project id of the previous page ( |
Response 200
List your projects
| Field | Type | Description |
|---|---|---|
projectsRequired | object[] | |
projects[].idRequired | string (uuid) | A server-minted id (sessions, projects, releases, users): a UUID. |
projects[].titleRequired | string | |
projects[].contentLanguageRequired | string≤ 35 characters | A UI or reply language: a BCP 47 tag ( |
projects[].statusRequired | string≥ 1 characters |
|
projects[].liveRequired | object | null | The release a new viewer gets; null before the first publish. |
projects[].live.releaseIdRequired | string (uuid) | A server-minted id (sessions, projects, releases, users): a UUID. |
projects[].live.numberRequired | integer0–9007199254740991 | |
projects[].live.publishedAtRequired | string (date-time) | null | An ISO 8601 instant. |
projects[].embedRequired | object | |
projects[].embed.policyRequired | string≥ 1 characters |
|
projects[].embed.allowKeylessRequired | boolean | Anyone may frame it without a key (the owner pays). |
projects[].embed.urlRequired | string≥ 1 characters | The embed document: |
projects[].listingRequired | object | null | Its marketplace listing, when it has one. |
projects[].listing.slugRequired | string≥ 1 characters | |
projects[].listing.visibilityRequired | string≥ 1 characters |
|
projects[].listing.allowEmbedRequired | boolean | Other accounts may embed it with their own keys. |
projects[].listing.urlRequired | string≥ 1 characters | |
projects[].createdAtRequired | string (date-time) | An ISO 8601 instant. |
projects[].updatedAtRequired | string (date-time) | An ISO 8601 instant. |
nextCursor | string (uuid) | Present when there are more: pass it as |
Errors
400invalid_input401key_invalid403scope_required
Read your usage
GET/v1/usageSecret key
Needs the usage capability. Amounts are integer millicredits from the hourly rollup.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
from | query | string (date) | First UTC day ( |
to | query | string (date) | Last UTC day, inclusive; absent: today. |
groupBy | query | "day" | "project" | "key" | "surface" | "service"Default "day" |
Response 200
Read your usage
| Field | Type | Description |
|---|---|---|
fromRequired | string (date) | |
toRequired | string (date) | |
groupByRequired | string≥ 1 characters | |
totalsRequired | object | Amounts in integer MILLIcredits (1 credit = 1,000), exact over any range. |
totals.eventsRequired | integer0–9007199254740991 | Paid calls (LLM, TTS, ASR, RTC, egress). |
totals.creditsMilliRequired | integer0–9007199254740991 | |
totals.billableCreditsMilliRequired | integer0–9007199254740991 | The part charged to the account (test-key sessions are recorded but not billed). |
groupsRequired | object[] | |
groups[].eventsRequired | integer0–9007199254740991 | Paid calls (LLM, TTS, ASR, RTC, egress). |
groups[].creditsMilliRequired | integer0–9007199254740991 | |
groups[].billableCreditsMilliRequired | integer0–9007199254740991 | The part charged to the account (test-key sessions are recorded but not billed). |
groups[].keyRequired | string | null | The day, project id, key id, surface or service; null: no project / no key. |
balance | object | The account's credits this period (an unscoped key only). |
balance.periodStartRequired | string (date-time) | An ISO 8601 instant. |
balance.periodEndRequired | string (date-time) | An ISO 8601 instant. |
balance.allowanceMilliRequired | integer0–9007199254740991 | |
balance.usedMilliRequired | integer0–9007199254740991 | |
balance.availableMilliRequired | integer-9007199254740991–9007199254740991 | |
countedUntilRequired | string (date-time) | null | Usage is folded hourly: everything before this instant is counted. |
Errors
400invalid_input401key_invalid403scope_required
List learners' results
GET/v1/resultsSecret key
Needs the results capability: the results of the sessions minted with your account's keys, newest change first.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
projectId | query | string (uuid) | A server-minted id (sessions, projects, releases, users): a UUID. |
externalUserId | query | string | The integrator's own id for the learner: printable text, no control characters. |
from | query | string (date-time) | Results that changed at or after this instant. |
to | query | string (date-time) | Results that changed before this instant. |
limit | query | integerDefault 50 | |
cursor | query | string | The previous page's |
Response 200
List learners' results
| Field | Type | Description |
|---|---|---|
resultsRequired | object[] | |
results[].sessionIdRequired | string (uuid) | The story's latest session: the report is |
results[].projectIdRequired | string (uuid) | A server-minted id (sessions, projects, releases, users): a UUID. |
results[].releaseId | string (uuid) | A server-minted id (sessions, projects, releases, users): a UUID. |
results[].surfaceRequired | string≥ 1 characters |
|
results[].keyIdRequired | string (uuid) | The key the session was minted with. |
results[].testRequired | boolean | Minted with a test key. |
results[].viewerRequired | one of | The learner: the integrator's own id for a secure embed's learner, else nobody by name. |
| When kind is “anonymous” | ||
| When kind is “external” | ||
results[].viewer.externalUserIdRequired | string≥ 1 characters | |
| When kind is “account” | ||
results[].viewer.userIdRequired | string (uuid) | A server-minted id (sessions, projects, releases, users): a UUID. |
results[].startedAtRequired | string (date-time) | An ISO 8601 instant. |
results[].updatedAtRequired | string (date-time) | An ISO 8601 instant. |
results[].completedAt | string (date-time) | When the story was completed; absent while it is not. |
results[].completedRequired | boolean | |
results[].epochRequired | integer0–9007199254740991 | Grows with every rewind; a result is read as of its epoch. |
results[].scoreRequired | number≥ 0 | |
results[].maxScoreRequired | number≥ 0 | |
results[].percentRequired | number0–100 | 0–100, one decimal. |
results[].passed | boolean | Every quiz completed and passed; absent while a quiz is not completed. |
results[].answeredCountRequired | integer0–9007199254740991 | |
results[].questionCountRequired | integer0–9007199254740991 | |
nextCursor | string≥ 1 characters | Present when there are more: pass it as |
Errors
400invalid_input401key_invalid403scope_required
Download a learner's report
GET/v1/results/{id}/reportSecret key
Needs the results capability. A session your account's keys did not mint answers 404.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idRequired | path | string | The result's |
format | query | "json" | "html" | "csv" | "docx" | "xlsx"Default "json" | |
template | query | string | One of the project's report templates; absent: the default layout. |
locale | query | string | The report's language; absent: the session's. |
Response 200
format=json: the session and its result as the viewer's own GET …/result gives them, and — only when the project lets reports carry the conversation, never for a project made for children, and only while its retention keeps it — the conversation.
| Field | Type | Description |
|---|---|---|
sessionRequired | object | |
session.idRequired | string (uuid) | A server-minted id (sessions, projects, releases, users): a UUID. |
session.projectIdRequired | string (uuid) | A server-minted id (sessions, projects, releases, users): a UUID. |
session.releaseId | string (uuid) | The release played (a draft session has none). |
session.titleRequired | string | |
session.startedAtRequired | string (date-time) | An ISO 8601 instant. |
session.lastSeenAtRequired | string (date-time) | An ISO 8601 instant. |
session.durationMsRequired | integer0–9007199254740991 | |
resultRequired | object | |
result.viewerRequired | one of | Who a result is about: nobody by name, a secure embed's learner, a signed-in account. |
| When kind is “anonymous” | ||
| When kind is “external” | ||
result.viewer.externalUserIdRequired | string≥ 1 characters | |
| When kind is “account” | ||
result.viewer.userIdRequired | string (uuid) | A server-minted id (sessions, projects, releases, users): a UUID. |
result.epochRequired | integer0–9007199254740991 | |
result.completedRequired | boolean | |
result.beatsRequired | object[] | |
result.beats[].beatIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
result.beats[].aliasRequired | string | |
result.beats[].nameRequired | string | |
result.beats[].sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
result.beats[].requiredRequired | boolean | |
result.beats[].statusRequired | string≥ 1 characters |
|
result.beats[].turnsRequired | integer0–9007199254740991 | |
result.quizzesRequired | object[] | |
result.quizzes[].quizIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
result.quizzes[].aliasRequired | string | |
result.quizzes[].title | string | |
result.quizzes[].statusRequired | string≥ 1 characters |
|
result.quizzes[].scoreRequired | number≥ 0 | |
result.quizzes[].maxScoreRequired | number≥ 0 | |
result.quizzes[].percentRequired | number0–100 | 0–100, one decimal. |
result.quizzes[].passed | boolean | Against the quiz's pass mark, once the quiz is completed. |
result.quizzes[].correctCountRequired | integer0–9007199254740991 | |
result.quizzes[].questionsRequired | object[] | |
result.quizzes[].questions[].questionIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
result.quizzes[].questions[].keyRequired | string | |
result.quizzes[].questions[].prompt | string | |
result.quizzes[].questions[].answeredRequired | boolean | |
result.quizzes[].questions[].correctRequired | boolean | |
result.quizzes[].questions[].pointsRequired | number≥ 0 | |
result.quizzes[].questions[].maxPointsRequired | number≥ 0 | |
result.quizzes[].questions[].attemptsRequired | integer0–9007199254740991 | |
result.quizzes[].questions[].response | one of | A response to one question: a choice (single, image choice), a set of choices (multi), true or false, or a typed answer. The server trims and bounds text itself (grading refuses an answer over 500 characters), so the wire allows some slack rather than failing a whole request. |
| When kind is “choice” | ||
result.quizzes[].questions[].response.choiceIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
| When kind is “choices” | ||
result.quizzes[].questions[].response.choiceIdsRequired | string[]1–10 items | |
| When kind is “boolean” | ||
result.quizzes[].questions[].response.valueRequired | boolean | |
| When kind is “text” | ||
result.quizzes[].questions[].response.textRequired | string≤ 2000 characters | |
result.quizzes[].questions[].responseText | string | The response in words: the chosen choices' text, true / false, the typed answer. |
result.quizzes[].questions[].respondent | one of | Who answers a quiz: the viewer, or the viewer playing a cast member ("as Cat"). |
| When kind is “viewer” | ||
| When kind is “character” | ||
result.quizzes[].questions[].respondent.castIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
result.variablesRequired | object[] | |
result.variables[].variableIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
result.variables[].aliasRequired | string | |
result.variables[].typeRequired | string≥ 1 characters | |
result.variables[].valueRequired | boolean | number | string | A story value: a boolean, a number, or a short text (a choice is its key). |
result.itemsRequired | object[] | |
result.items[].resultIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
result.items[].aliasRequired | string | |
result.items[].labelRequired | string | |
result.items[].kindRequired | string≥ 1 characters |
|
result.items[].valueRequired | number | boolean | |
result.totalsRequired | object | |
result.totals.scoreRequired | number≥ 0 | |
result.totals.maxScoreRequired | number≥ 0 | |
result.totals.percentRequired | number0–100 | |
result.totals.passed | boolean | |
result.totals.correctCountRequired | integer0–9007199254740991 | |
result.totals.questionCountRequired | integer0–9007199254740991 | |
result.totals.answeredCountRequired | integer0–9007199254740991 | |
result.totals.beatsCompletedRequired | integer0–9007199254740991 | |
result.totals.beatsTotalRequired | integer0–9007199254740991 | |
result.totals.completionRequired | number0–1 | Completed Beats ÷ all Beats (1 when there are none). |
transcript | object[] | |
transcript[].speakerRequired | string≥ 1 characters |
|
transcript[].speakerNameRequired | string | |
transcript[].addressee | string≥ 1 characters | Who it was said to (the same keys, or |
transcript[].textRequired | string | |
transcript[].atRequired | string (date-time) | An ISO 8601 instant. |
text/html — format=html
text/csv — format=csv
application/vnd.openxmlformats-officedocument.wordprocessingml.document — format=docx
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet — format=xlsx
Errors
400invalid_input401key_invalid403scope_required404not_found