Docs
arrow_back Embeddables

Screen Builder Build and above

The Screen Builder is an authoring surface for one standalone screen or quiz section: Editor and Preview only. There is no course map, publish, share, translations, or narration chrome.

Two ways to create a screen with a layout: omit screenId so the embed opens on our layout picker (default), or list layouts and create the screen yourself, then embed with the returned id. Agent tools are off unless you set options.ai. Theme comes from themeId.

API Endpoint

POST/v1/headless/embed/screen

Body parameters

FieldTypeExampleDescriptionDemo Value
actionstringedit——
typestringWhen set with no screenId and no layoutId, mints an empty screen of that type (for example blocks or blocksQuiz) instead of opening the picker. Omit both to use the picker.
layoutIdstringCatalog layout id from GET /layouts. When set with no screenId, the embed skips the picker and mints immediately with English placeholder copy.
identifierstringyour-user-id——
clientIdentifierstringyour-tenant-id——
themeIdnumberCustom theme ID to apply to the embeddable.
options.backeventhiddennativeeventBack button behaviour. Use event so cancel on the layout picker posts { type: 'back' } to the host.
options.aibooleanfalseEnable the in-builder agent. Off by default for this embeddable. When on, tools are limited to screen-level block edits.

Create a screen with a layout

After a layout is applied, open or keep the builder on that screen. On either path, listen on the Screen Player for learner start / complete / failed (and score) once the screen is in play.

Our picker (default)Your own picker
HowPOST /v1/headless/embed/screen with action: edit and no screenId. The embed opens on the layout picker; the user chooses; the screen is created and the editor opens. GET /v1/headless/layouts to list, then POST /v1/headless/screen with a layoutId. Open the builder with POST /v1/headless/embed/screen, action: edit, and the returned id.
You get Our picker UI, layout previews, placeholder content localised to the viewer, and new layouts appearing automatically as we ship them. Full control of the picker's look and placement.
You handlescreen / created to attach the screen to your course, and back if the user cancels.
  • Building and maintaining the picker UI, including keeping the layout list current.
  • No thumbnails — the layouts payload is id, name, category, screenType only.
  • English placeholder copy. Layout structure, geometry, and catalog heading/paragraph prompts are applied on mint. Localised picker copy still only happens in our picker.

Passing layoutId (or type) on POST /embed/screen skips the picker and mints immediately — layoutId seeds the same English catalog copy as POST /screen. See the Screens API.

Our picker — POST /v1/headless/embed/screen
{
  "action": "edit",
  "identifier": "your-user-id",
  "clientIdentifier": "your-tenant-id"
}
Your own picker — GET /v1/headless/layouts
[
  {
    "id": "content-title-text",
    "name": "Title Text",
    "category": "content",
    "screenType": "blocks"
  }
]
Your own picker — POST /v1/headless/screen
{
  "layoutId": "content-title-text",
  "identifier": "your-user-id"
}

Emitted Events

How to listen to events
TypeEventDescriptionNotes
sessionreadyFires when the screen builder is mounted and ready.
screencreatedFires when the user chooses a layout and the screen is created.Same host postMessage channel as the player. data.id is the new screen id — attach it to your course.
back—Fires when the user cancels the layout picker or clicks Back.Payload is { type: 'back' } with no event field.
Created
{
  "type": "screen",
  "event": "created",
  "data": { "id": 123 }
}
Cancel
{
  "type": "back"
}

Live Demo