REST API: Embeds
Every operation of this group with its parameters, body, answer and errors, as the OpenAPI document states them.
Public reads a page makes before anything plays: a project's card (the SDK's facade), oEmbed, and the keys viewer tokens are signed with.
Read a project's card
GET/v1/projects/{id}/cardNo bearer token
Public and cached a minute. With publishableKey it is also the origin check the SDK makes before mounting the iframe; with cardToken it describes a private or secure-only project (and is never cached).
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idRequired | path | string | The project's id. |
cardToken | query | string | |
publishableKey | query | string | |
locale | query | string | A UI or reply language: a BCP 47 tag ( |
Response 200
GET /v1/projects/{id}/card — EmbedMeta v1: the title, the creator, the poster (renditions, blurhash and dominant colour for the placeholder), the length, and the EU AI Act Art. 50 disclosure the facade shows before anything plays — and, added within v1 (P9), the poster's <picture> sources, the hover preview, who a viewer may talk to and the chapters with their thumbnails. Fields added later are optional: a reader branches on their absence.
| Field | Type | Description |
|---|---|---|
vRequired | integer0–9007199254740991 | |
projectIdRequired | string (uuid) | A server-minted id (sessions, projects, releases, users): a UUID. |
releaseIdRequired | string (uuid) | A server-minted id (sessions, projects, releases, users): a UUID. |
titleRequired | string | |
creatorRequired | object | |
creator.nameRequired | string | |
contentLanguageRequired | string≤ 35 characters | A UI or reply language: a BCP 47 tag ( |
durationMsRequired | integer0–9007199254740991 | The timeline scenes' authored length; interactive scenes add none. |
scenesRequired | integer0–9007199254740991 | |
interactiveRequired | boolean | Viewers act in it: Beats, or an interactive scene. |
poster | object | |
poster.widthRequired | integer0–9007199254740991 | |
poster.heightRequired | integer0–9007199254740991 | |
poster.blurhashRequired | string≥ 1 characters | |
poster.colorRequired | string≥ 1 characters |
|
poster.variantsRequired | object[]≥ 1 items | |
poster.variants[].typeRequired | string≥ 1 characters |
|
poster.variants[].widthRequired | integer0–9007199254740991 | |
poster.variants[].heightRequired | integer0–9007199254740991 | |
poster.variants[].urlRequired | string≥ 1 characters | |
poster.sources | object[]≥ 1 items | The renditions as |
poster.sources[].typeRequired | string≥ 1 characters |
|
poster.sources[].srcsetRequired | string≥ 1 characters | |
poster.fallbackUrl | string≥ 1 characters | One rendition every browser reads (a JPEG), for the |
preview | object | The hover preview (P9): a few silent seconds of the experience, small enough to play on hover (a 640 × 360, 24 fps H.264 MP4 under 1.5 MB). Absent until one is rendered. |
preview.urlRequired | string≥ 1 characters | |
preview.typeRequired | string≥ 1 characters |
|
preview.widthRequired | integer0–9007199254740991 | |
preview.heightRequired | integer0–9007199254740991 | |
preview.durationMsRequired | integer0–9007199254740991 | |
preview.bytesRequired | integer0–9007199254740991 | |
aiRequired | object | EU AI Act Art. 50: who is AI and what is synthetic. Never hidden by a host option. |
ai.aiCharactersRequired | boolean | |
ai.narratorAiRequired | boolean | |
ai.syntheticVoiceRequired | boolean | |
ai.liveAiRequired | boolean | |
ai.characters | object[] | Who a viewer may talk to — the AI characters (and speaking props) that answer, by name, in the release's cast order; empty when the experience has no live conversation (P9). |
ai.characters[].nameRequired | string | |
ai.voice | boolean | A viewer may also talk to them by voice (P9). |
ai.notice | string≥ 1 characters | The disclosure in words, as the facade says it before anything plays ("Made with AI: AI characters and synthetic voices."), in the UI language nearest to the request's |
ai.unknown | boolean | The release's stored disclosure could not be read: the flags keep what could, and |
chapters | object[] | The chapters in play order: each scene, then its named or tagged Beats (P9). |
chapters[].kindRequired | string≥ 1 characters |
|
chapters[].idRequired | string≥ 1 characters | The scene's id, or the Beat's. |
chapters[].sceneIdRequired | string≥ 1 characters | The scene the chapter is in. |
chapters[].titleRequired | string | The scene's name, or the Beat's. |
chapters[].alias | string≥ 1 characters | A Beat's alias: what |
chapters[].tags | string[] | A Beat's chapter tags. |
chapters[].startMsRequired | integer0–9007199254740991 | Where the chapter starts in its scene, in authored milliseconds. |
chapters[].thumbnail | object | A 16:9 frame of the chapter (480 × 270 and narrower); absent until one is rendered. |
chapters[].thumbnail.widthRequired | integer0–9007199254740991 | |
chapters[].thumbnail.heightRequired | integer0–9007199254740991 | |
chapters[].thumbnail.blurhashRequired | string≥ 1 characters | |
chapters[].thumbnail.colorRequired | string≥ 1 characters |
|
chapters[].thumbnail.sourcesRequired | object[]≥ 1 items | |
chapters[].thumbnail.sources[].typeRequired | string≥ 1 characters |
|
chapters[].thumbnail.sources[].srcsetRequired | string≥ 1 characters | |
chapters[].thumbnail.fallbackUrlRequired | string≥ 1 characters | |
aspect | string≥ 1 characters | The frame the experience is authored for ( |
embedUrlRequired | string≥ 1 characters | The embed document ( |
Errors
400invalid_input401key_invalid403origin_not_allowed404release_not_found
Read a listing's card
GET/v1/listings/{slug}/cardNo bearer token
Added within v1 (P8): the card of a marketplace listing, named by its slug (an earlier slug too) — the SDK's listing option, which learns the project its embed document plays (projectId) from it. The same card as the project's, reached the way /w/{slug} reaches the listing: an unlisted listing opens to its slug; a private, removed or unpublished one is the 404 of a slug that never existed.
The project card of a marketplace listing, for createPlayer({ listing }): its projectId names the embed document. An unlisted listing answers to its slug; a private, removed or unpublished one is the same 404 as a slug that never existed. Public and cached a minute; the credentials work as on the project's card.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
slugRequired | path | string | The listing's slug, as in |
cardToken | query | string | |
publishableKey | query | string | |
locale | query | string | A UI or reply language: a BCP 47 tag ( |
Response 200
GET /v1/projects/{id}/card — EmbedMeta v1: the title, the creator, the poster (renditions, blurhash and dominant colour for the placeholder), the length, and the EU AI Act Art. 50 disclosure the facade shows before anything plays — and, added within v1 (P9), the poster's <picture> sources, the hover preview, who a viewer may talk to and the chapters with their thumbnails. Fields added later are optional: a reader branches on their absence.
| Field | Type | Description |
|---|---|---|
vRequired | integer0–9007199254740991 | |
projectIdRequired | string (uuid) | A server-minted id (sessions, projects, releases, users): a UUID. |
releaseIdRequired | string (uuid) | A server-minted id (sessions, projects, releases, users): a UUID. |
titleRequired | string | |
creatorRequired | object | |
creator.nameRequired | string | |
contentLanguageRequired | string≤ 35 characters | A UI or reply language: a BCP 47 tag ( |
durationMsRequired | integer0–9007199254740991 | The timeline scenes' authored length; interactive scenes add none. |
scenesRequired | integer0–9007199254740991 | |
interactiveRequired | boolean | Viewers act in it: Beats, or an interactive scene. |
poster | object | |
poster.widthRequired | integer0–9007199254740991 | |
poster.heightRequired | integer0–9007199254740991 | |
poster.blurhashRequired | string≥ 1 characters | |
poster.colorRequired | string≥ 1 characters |
|
poster.variantsRequired | object[]≥ 1 items | |
poster.variants[].typeRequired | string≥ 1 characters |
|
poster.variants[].widthRequired | integer0–9007199254740991 | |
poster.variants[].heightRequired | integer0–9007199254740991 | |
poster.variants[].urlRequired | string≥ 1 characters | |
poster.sources | object[]≥ 1 items | The renditions as |
poster.sources[].typeRequired | string≥ 1 characters |
|
poster.sources[].srcsetRequired | string≥ 1 characters | |
poster.fallbackUrl | string≥ 1 characters | One rendition every browser reads (a JPEG), for the |
preview | object | The hover preview (P9): a few silent seconds of the experience, small enough to play on hover (a 640 × 360, 24 fps H.264 MP4 under 1.5 MB). Absent until one is rendered. |
preview.urlRequired | string≥ 1 characters | |
preview.typeRequired | string≥ 1 characters |
|
preview.widthRequired | integer0–9007199254740991 | |
preview.heightRequired | integer0–9007199254740991 | |
preview.durationMsRequired | integer0–9007199254740991 | |
preview.bytesRequired | integer0–9007199254740991 | |
aiRequired | object | EU AI Act Art. 50: who is AI and what is synthetic. Never hidden by a host option. |
ai.aiCharactersRequired | boolean | |
ai.narratorAiRequired | boolean | |
ai.syntheticVoiceRequired | boolean | |
ai.liveAiRequired | boolean | |
ai.characters | object[] | Who a viewer may talk to — the AI characters (and speaking props) that answer, by name, in the release's cast order; empty when the experience has no live conversation (P9). |
ai.characters[].nameRequired | string | |
ai.voice | boolean | A viewer may also talk to them by voice (P9). |
ai.notice | string≥ 1 characters | The disclosure in words, as the facade says it before anything plays ("Made with AI: AI characters and synthetic voices."), in the UI language nearest to the request's |
ai.unknown | boolean | The release's stored disclosure could not be read: the flags keep what could, and |
chapters | object[] | The chapters in play order: each scene, then its named or tagged Beats (P9). |
chapters[].kindRequired | string≥ 1 characters |
|
chapters[].idRequired | string≥ 1 characters | The scene's id, or the Beat's. |
chapters[].sceneIdRequired | string≥ 1 characters | The scene the chapter is in. |
chapters[].titleRequired | string | The scene's name, or the Beat's. |
chapters[].alias | string≥ 1 characters | A Beat's alias: what |
chapters[].tags | string[] | A Beat's chapter tags. |
chapters[].startMsRequired | integer0–9007199254740991 | Where the chapter starts in its scene, in authored milliseconds. |
chapters[].thumbnail | object | A 16:9 frame of the chapter (480 × 270 and narrower); absent until one is rendered. |
chapters[].thumbnail.widthRequired | integer0–9007199254740991 | |
chapters[].thumbnail.heightRequired | integer0–9007199254740991 | |
chapters[].thumbnail.blurhashRequired | string≥ 1 characters | |
chapters[].thumbnail.colorRequired | string≥ 1 characters |
|
chapters[].thumbnail.sourcesRequired | object[]≥ 1 items | |
chapters[].thumbnail.sources[].typeRequired | string≥ 1 characters |
|
chapters[].thumbnail.sources[].srcsetRequired | string≥ 1 characters | |
chapters[].thumbnail.fallbackUrlRequired | string≥ 1 characters | |
aspect | string≥ 1 characters | The frame the experience is authored for ( |
embedUrlRequired | string≥ 1 characters | The embed document ( |
Errors
400invalid_input401key_invalid403origin_not_allowed404release_not_found
oEmbed
GET/v1/oembedNo bearer token
oEmbed 1.0 for an experience's embed or watch address: a rich answer with an iframe of the embed document. JSON only.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
urlRequired | query | string | |
maxwidth | query | integer | |
maxheight | query | integer | |
format | query | "json" | "xml"Default "json" |
Response 200
A rich oEmbed answer: an iframe of the embed document.
| Field | Type | Description |
|---|---|---|
versionRequired | "1.0" | |
typeRequired | "rich" | |
provider_nameRequired | string | |
provider_urlRequired | string | |
titleRequired | string | |
author_name | string | |
htmlRequired | string≥ 1 characters | |
widthRequired | integer0–9007199254740991 | |
heightRequired | integer0–9007199254740991 | |
thumbnail_url | string | |
thumbnail_width | integer0–9007199254740991 | |
thumbnail_height | integer0–9007199254740991 | |
cache_age | integer0–9007199254740991 |
Errors
400invalid_input404not_found501format_unsupported
The viewer-token signing keys
GET/.well-known/jwks.jsonNo bearer token
Cached five minutes. A new key is published a rotation ahead of signing with it.
Response 200
GET /.well-known/jwks.json: the keys viewer tokens verify against (the signing key and its predecessor).
| Field | Type | Description |
|---|---|---|
keysRequired | object[]≥ 1 items | |
keys[].ktyRequired | "EC" | |
keys[].crvRequired | "P-256" | |
keys[].xRequired | string≥ 1 characters | |
keys[].yRequired | string≥ 1 characters | |
keys[].kidRequired | string≥ 1 characters | |
keys[].algRequired | "ES256" | |
keys[].useRequired | "sig" |