Scryboard

Downloads

Publishing either template to the Marketplace? See the scryboard.json manifest reference for the full field list, the vetted package list, and how secrets work.

Scryboard App API

Bring your own app to your campaign's session data. Scryboard's dashboard is one consumer of the ambient table data — this API lets you build your own: spell suggesters, live maps, usage histograms, character-image pinboards, or anything else that reads the session stream and renders something useful.

Before you start

Prerequisites: underneath everything below is a plain REST API (JSON over HTTPS), so any language works, and you can run an app yourself — self-hosted, on your own machine or server — without ever touching the Marketplace. The example apps on the Downloads list are Node.js scripts written this way — Node.js 18+ (for the built-in fetch) is the only thing you need installed to run or adapt them. If you've just installed Node.js and a command like node --version still says it's not recognized, open a new terminal window — Windows in particular won't pick up a PATH change in a window that was already open.

If you want to list on the Marketplace instead, what a buyer's install actually downloads depends on your app's runtime: a browser_sandboxed app is one code file, submitted as a .zip with its scryboard.json — no git clone needed, and there's a ready-to-submit starter template on the Downloads list at the top of the App API docs page. A node_cli app — anything calling an outside API, using a package, or needing a secret — ships as a small .zip (your code plus a scryboard.json manifest) and runs through the Scryboard App Runner, a small desktop app, rather than the buyer's browser. See Choosing a runtime below and the manifest reference before you start writing code — the runtime you pick determines what you can build with.

Trying your app on your own campaign before (or without) publishing: upload it as a personal app. Sign in, open /agents, and under Your Own Apps click Upload your app (.zip). It gets the same automatic checks a Marketplace submission gets, but nobody reviews it and nobody else can see it. To see those checks before uploading, use Check Your App on the Create an app page: it runs them in your browser on your .zip and sends nothing anywhere. Then pick one of your campaigns under Connect to: and click Connect. A browser_sandboxed app then runs whenever you have that campaign's page open. To try a change to a browser app, click Replace code on the app and pick the new .zip. This is the real test for browser_sandboxed apps: before it, you can check their logic against the mock server with dev-runner.mjs (in the node_cli starter template), but plain Node is less strict than the browser sandbox.

A personal node_cli app runs from a folder on your computer, not from the zip. It offers Get Runner link, which hands its token to the App Runner. The Runner then asks where the app is on your computer: point it at the folder holding your scryboard.json and code, and that folder is what runs. Edits there apply on the next run, with no re-upload. The uploaded zip is only what Check Your App and the upload checks looked at, so the two can drift apart: re-upload with Replace code when you change the manifest (scopes, settings, services), and before you submit. A Marketplace install is different: the Runner downloads the approved zip.

Making the zip on Windows. Any of these works: in File Explorer, select scryboard.json and your code files (not the folder around them), right-click, Send to → Compressed (zipped) folder; or in a terminal, tar.exe -a -c -f my-app.zip scryboard.json agent.mjs lib (built into Windows 10 and 11). Run that from PowerShell or Command Prompt: in Git Bash tar is a different program that writes a tar file whatever you name it, and Scryboard will say the file isn't a zip. Windows PowerShell 5.1's Compress-Archive writes paths with backslashes (lib\render.mjs); Scryboard's checks and the App Runner both read those correctly, but other zip tools may not, so prefer the two above. Leave out state/, dev/ and node_modules/: they're dropped anyway.

Testing without touching production: there's currently no separate staging deployment of Scryboard — the only live environment is production. Rather than pointing a new app under development at your real campaign with a real token, use the mock server first: it's a zero-dependency local stand-in for this entire API, backed by fixture data, with a preview page so you can see your pushed widgets rendered without writing anything to a real database. Do one final pass against a real token before publishing, since the mock is a fixture and can drift from actual behavior over time. To test offline against the same campaign as your sample campaign (below), download Sample campaign for the mock from the Downloads list and start the mock with node mock-server.mjs --fixtures=sample-campaign.json. The mock covers everything on this page except voices (501) and the fight's less common changes (death saves, undo, adding and removing combatants). Claude answers 501 too, unless you give it a canned reply: start the mock with --claude-reply=reply.json (or set MOCK_CLAUDE_REPLY), and every scryboard.claude() call gets that file's answer. The file can be a whole Messages API response (anything with a content array) or just the text you want back, which is wrapped as one text block. It's read on every call, so you can edit it between ticks to test how your app parses odd answers. Nothing checks your model or allowance in the mock; on Scryboard your manifest's services block does. To try your own settings boxes on the preview page, add --app=<your app's folder>: the mock reads the settings your scryboard.json declares (without it you get a sample "appearance" box).

A sample campaign to test against: an empty new account has nothing for an app to read. On the Create an app page, Make a sample campaign copies a ready-made campaign into your account, with you as its DM: five played sessions, a live session with a fight in round two, every prep layer reviewed (some World Bible entries still Planned, one with an open conflict, one imported), history from session reviews, events waiting for approval, rules lookups and three players with character sheets. Connect your personal app to it like any campaign; it goes through the real API with the real permission checks. Recording and Scryboard's own AI are switched off there. Its sixth session is the live one; if you end it, it becomes a sixth played session until the next Reset, which brings back five played sessions and a live one. The downloadable Sample campaign for the mock is built from the same source, so it matches a freshly reset sample. Reset refreshes it with fresh data (up to 10 times a day), keeping your apps connected. The three players are placeholder accounts, but you also play a fourth hero, Wren Ashdown, from your own seat: a player-scope app you connect acts as Wren. It reads and writes Wren's sheet with character, and takes Wren's turn in the fight. Its cards show on the player pages. View as Player, on the campaign page and in the live session's toolbar, opens them in a new tab, so your DM screen stays open beside them; they show only what a player sees. Your seat is still the DM's, so a DM-scope party list (character from a DM token) leaves Wren out, and Wren's sheet changes only through an app (the character editor is for players).

Getting a token

DMs: at the bottom of your campaign page, open Advanced (developer), then under App Access Tokens click + New token. Choose a data scope:

  • Player-visible data only — the app sees what a player at the table sees (verified homebrew, combat state with hidden stat blocks masked, rules lookups, session list). Use this for anything players will look at.
  • Full DM data — adds the live transcript, all verified prep layers, and the member roster. Treat this token like a password to your campaign notes.

Players: on your own campaign landing page (/campaigns/{id}/player), open Advanced (developer) at the bottom, then under Your App Tokens click + New token. Player-issued tokens are always player-scoped — same read access a DM-issued player token gets, just self-service, and you can only see/revoke tokens you personally created.

The token (scry_…) is shown once. Store it securely; revoke it any time — revocation takes effect immediately: the token can't read or push anything more, and the widgets it pushed stay on the page showing their last output, marked Disconnected, until someone removes them (or a new token for the same app takes them over — see widget under "Writing widgets"). Uninstalling a Marketplace app, or disconnecting a personal app from a campaign, removes its widgets there as well.

All tokens currently have the observer capability: read anything in scope, and write only what's explicitly documented below (widget output, uploaded media, a player's own character data, or — DM-scope only — proposed canon and proposed campaign events, neither of which bypasses human review, and per-item attributes patches, which can't touch anything a DM reviewed). An observer app cannot alter live session state, combat, or anything a DM hasn't reviewed, so the blast radius of a buggy app stays limited to its own output and to canon that's sitting in the normal verify queue, not published.

Reading data

GET https://<your-scryboard-host>/api/agent/{resource}
Authorization: Bearer scry_...
Resource Scope Params Returns
campaign any — { id, name }
sessions any limit { id, status, starting_scene, synopsis, ended_at, attendance }, the live session (status: "active", ended_at: null) first, then ended ones newest-first. attendance says who was there; see Who was at a session
transcript DM only session_id (required), after_ms, limit Ordered segments { speaker, text, timestamp_ms }
intelligence any session_id (required) Live AI state, or null before the first analysis: current_scene, combat_active, surface_now, new_canon, rules_trigger, … (player scope: rules_trigger only). See Response shapes
combatants any session_id (required) Initiative order; monster_block is null for hidden stat blocks on player-scope tokens. For whose turn it is, which player a row is (member_user_id), temp HP, death saves and the log, read fight instead (Changing the fight)
extractions any layer, include_planned, include_history [{ layer, items }] for verified layers only (player scope: homebrew only). Planned entries are left out unless include_planned=true; each entry's tableHistory is left out unless include_history=true. See Response shapes
extractions_version any layer, include_planned { version }: a short fingerprint of what extractions would return with the same parameters. It changes whenever those layers change, so compare it with the last one you saw and skip the extractions read when it's the same. null means it can't tell, so read
rules_lookups any session_id, since, before, order, limit Append-only history of every rule surfaced at the table. With since: oldest-first after that timestamp. Without: the newest rows, newest-first. See Paging through a feed
members DM only — Roster { id, user_id, role, display_name, character_name, joined_at }, the DM's own row included. See Linking a player to their character
character any — Player scope: own { member_id, user_id, display_name, character_data }. DM scope: every player's, as an array of the same shape — see Importing character data and Linking a player to their character
actions any since, before, order, limit Clicks on this app's own action buttons, oldest-first { id, widget_id, widget, action_id, clicked_by_role, created_at } — see the action node and Paging through a feed
digest any — The campaign's running "story so far": { digest, last_session_id, sessions_count, updated_at }, or null before the first confirmed session review lands
events DM only event_type, session_id, since, before, order, limit Structured campaign events, oldest-first, each with a participants array — confirmed events plus this app's own pending proposals; see Proposing events and Paging through a feed

since and before are ISO 8601 timestamps — normally a created_at you got back earlier, passed through unchanged. limit is 1–1000 (default 200). A malformed parameter (a session_id that isn't a UUID, an unknown layer or event_type, a bad timestamp) is refused with a 400 that names it.

Responses are { "data": … } on success, { "error": "…" } otherwise. The status tells you what kind of problem it was: 401 missing, invalid or revoked token; 403 the token's role or your manifest's scopes don't allow this; 404 no such resource, session or item; 400 the request itself is malformed; 413 the body is too large; 429 rate limited (120 requests a minute per token, 600 a minute across all the tokens one person has issued, and 1500 a minute across every app in one campaign). Notes:

  • extractions items carry type (beat, character, faction, location, item, rule, or history) and an optional subtype for finer classification (e.g. character → pc/npc/monster, item → weapon/spell/consumable/etc.) — subtype is null when not confidently inferable, so don't assume it's always present. Items may also carry an optional attributes object — a free-form bucket for structured data title/description text can't hold well (a monster's stat block, an item's numeric properties). No fixed schema; nothing in Scryboard's own extraction pipeline reads or writes it today, it's yours to use — including writing it per item, without touching the rest of the layer: see Attaching data to confirmed canon. Items that arrived through canon import carry source: { provider, id, url, hash, importedAt, mode } (mode imported = created by the import; merged = a session item an import folded into) — if you sync canon out to that same provider, skip these.
  • Planned entries are hidden unless you ask. A World Bible entry with status: "planned" is the DM's prep or wiki lore that hasn't come up at the table yet: an unrevealed villain, a town the party hasn't reached. It becomes canon (no status) when the DM approves it in a session review. extractions leaves planned entries out unless you pass include_planned=true. Only ask for them if your app is DM-facing: never show a planned entry, its name or its picture where players can see it. When your app writes a whole layer back (POST extractions), planned entries you left out are kept, so an app that never asked for them can't delete them by accident.
  • Player-scope tokens see only homebrew_registry from extractions — every other layer, World Bible included, is DM-only. An app that needs the DM's layers must be installed by the DM with a DM-scope token: read a DM-only resource, write a DM-only one, or set requires_dm_scope: true in the manifest (see the manifest guide), otherwise the Marketplace mints a player token and the app is silently blind.
  • Find the live session by polling sessions and filtering status === "active".
  • transcript + after_ms supports incremental polling: keep the largest timestamp_ms you've processed and pass it as after_ms next time. timestamp_ms is milliseconds since the session's first recorded line and keeps rising across the DM pausing and resuming, so it is a safe cursor within one session. Start from 0 (or omit after_ms) for a new session.
  • rules_lookups + since is the incremental feed for usage analytics (e.g. a spell histogram). With since, results come back oldest-first after that timestamp — keep the newest created_at you've processed as your next since and a burst of lookups is never skipped, just spread over a few ticks. Without since you get the newest rows, newest-first — a snapshot, not a feed.
  • actions + since is the same incremental pattern for button clicks — declare actions under scopes.reads to use it. Clicks are only retained for about 30 days, and only ever on your own app's widgets — two apps in the same campaign can't see each other's. Read Paging through a feed before you write this loop: without since, actions returns the oldest clicks, and a click that happened before your app started (or before it lost its saved state) must not be acted on as if it were new.
  • digest is a single running prose account of the whole campaign, incrementally folded forward by Scryboard after each confirmed session review — built exclusively from DM-confirmed synopses (the same vetted text players see as "Recap"), so any token role may read it. Use it instead of re-summarizing full session history yourself: it's cheaper, stable between reads, and already hallucination-hardened at the source.
  • events is the structured half of the campaign record — encounter, scene, spell_cast, and xp_award events with typed payloads and linked participants, written by Scryboard's own capture points and by apps (see Proposing events). It only ever returns confirmed events plus your own app's still-pending proposals (so you can track what you've proposed) — never another app's unconfirmed proposals, and not Scryboard's own not-yet-reviewed encounter snapshots either. Declare events under scopes.reads; it's DM-only, so declaring it means a DM must be the installer, same as transcript or members. With since and the oldest-first ordering it's the same incremental polling pattern as rules_lookups — and the same warning applies: with no since you get the oldest 200, so on a long-running campaign an app that never pages sees nothing new. Filter by event_type and page as described below.
  • GET /api/agent/info (not a resource — no read scope needed) says what the token belongs to: { source, agent_name, campaign_name, runtime, account }, where source is marketplace (an installed listing) or personal (an app registered from your own machine), and account is an opaque code for the Scryboard account the token was issued to (the same for all of that account's tokens; not its email or user id). The App Runner calls it before fetching anything, and only reuses an app's saved keys between installs with the same account; most apps never need it. It returns 401 for a revoked token, 404 once the app has been uninstalled, and 400 for a token made by hand under App Access Tokens (it isn't tied to any app).
  • Poll politely (every few seconds is fine). There is no push/webhook yet.

Example:

curl -s -H "Authorization: Bearer $SCRY_TOKEN" \
  "https://scryboard.vercel.app/api/agent/rules_lookups?since=2026-07-01T00:00:00Z"

Paging through a feed

actions, events and rules_lookups are feeds: rows only ever get added, each has a created_at, and a read returns at most limit rows (default 200, max 1000). Three parameters control which rows you get:

  • since — only rows created after this timestamp.
  • before — only rows created before this timestamp.
  • order — oldest (oldest-first; the default for actions and events, and for rules_lookups when since is given) or newest.

Every feed response also carries a page block beside data:

{
  "data": [ … ],
  "page": {
    "order": "oldest",
    "limit": 200,
    "has_more": true,
    "next": { "since": "2026-09-30T19:02:11.483912+00:00" },
    "newest_created_at": "2026-09-30T19:02:11.483912+00:00"
  }
}

has_more is true whenever the page came back full, so there may be more (a full page followed by an empty one is possible). next is the parameter to add to your previous ones to get the following page. newest_created_at is the value to save as your since high-water mark. The client libraries' get() returns only data, so there the rule is simply: a page shorter than your limit means you've caught up.

The pattern every polling app should use:

// 1. First run only (nothing saved yet): start from NOW, not from the
//    beginning. Any click that already exists is history -- a DM's
//    old button press must never trigger work (or a charge) again just
//    because your app started, was reinstalled, or lost its state file.
if (!state.actionsSince) {
  const [latest] = await scryboard.get('actions', { order: 'newest', limit: 1 })
  state.actionsSince = latest?.created_at ?? new Date().toISOString()
  saveState()
}

// 2. Every tick: page forward from the saved mark until a short page.
let since = state.actionsSince
for (;;) {
  const clicks = await scryboard.get('actions', { since, limit: 200 })
  for (const click of clicks) {
    handle(click)
    since = click.created_at
  }
  if (clicks.length < 200) break
}
state.actionsSince = since
saveState()

The same loop works for events (add event_type to read one kind at a time) and rules_lookups. To walk backwards through history instead — "the newest 50 encounters" — use order: 'newest' and pass the last row's created_at as before for the next page.

get(resource, { order: 'newest', limit: 1 }) is also the cheap way to ask "has anything happened since I last looked?".

Response shapes

extractions returns one row per verified layer:

{
  "data": [
    {
      "layer": "world_bible",
      "items": [
        {
          "id": "4f6c…",
          "type": "character",
          "subtype": "npc",
          "title": "Marta the Innkeeper",
          "description": "Runs the Thornwatch Inn; knows local rumours.",
          "aliases": ["Old Marta"],
          "now": "Lost the inn in the fire; now sleeps above the stables.",
          "confirmed": true,
          "flagged": false,
          "attributes": null
        }
      ]
    }
  ]
}
  • Only verified layers are returned. A layer the DM hasn't reviewed yet — fresh notes on a new campaign, or a layer an app just proposed changes to — is left out entirely, not returned empty. If your app sees nothing on a campaign that clearly has notes, that's why: the DM needs to review them on the campaign's verify page first.
  • verified (the layer) means the DM reviewed the whole layer. confirmed (an item) means the DM ticked that individual item during review. Saving a review discards the items left unticked, so in practice every item you get back is confirmed: true; if you ever see false, treat that item as not yet approved. flagged marks an item Scryboard wants the DM to look at again (with a flagReason).
  • aliases lists other names the same entity has been called — Scryboard merges "Old Marta" into "Marta the Innkeeper" rather than keeping two entries. Match against aliases as well as title when you de-duplicate, or you'll count the same NPC twice. Optional: treat a missing aliases as []. Items extracted before October 2026 may have no aliases and the nickname in brackets in the title instead ("Marta the Innkeeper (Old Marta)"); if you match names, strip a trailing "(…)" from a character, faction or location title and treat it as an alias too.
  • now (optional, people, places, factions and items) is who or what the entry is as of the last session, written when the DM saves a session review: a curse, a new allegiance, a change of clothes. description is the DM's own notes and can be out of date; when you show or use an entry, put now first. Absent when play hasn't changed anything.
  • tableHistory (only with include_history=true) is the dated record behind now, oldest first: [{ sessionId, date, kind, text, replaces? }], where kind is added (a new detail), changed (it was true and the story moved on) or corrected (the notes were wrong). Ask for it if you copy entries somewhere that should keep the whole story, like a wiki. When you write a layer back (POST extractions), entries keep their now and tableHistory unless you send those fields yourself, so an app that never reads them can't erase them.
  • Also optional: subtype, priority, attributes, source (see below) and conflict (an open disagreement the DM hasn't resolved yet).
  • history items are mostly what happened at the table. When the DM saves a session review, each event they approve becomes a history item ("The party destroyed the crypt keeper") with sourceSessionId, the session it happened in. History can also hold world lore the DM wrote themselves, which has no sourceSessionId. Items from before October 2026 may carry the session's date in the title instead: "[Oct 11, 2026] The party…". Strip a leading […] if you show titles.
  • The same review items are also in events. Saving a review logs each approved item as a confirmed scene event too, with source: "session_review" and payload.source_item_id set to the history item's id. That's deliberate (events are the typed record other features build on), but an app that shows both history and events should skip a scene event whose source_item_id matches a history item it already shows, or each review item appears twice.

Linking a player to their character

A player shows up under three ids. Every resource that names a player gives you a way to the others, so you never have to match names:

Field Where it appears What it is
member_id / members[].id members, character, events participants The player's seat in this campaign
user_id members, character, fight (as member_user_id) The player's account
character_name members The name on their character sheet (character_data.character_meta.name), or null with no sheet

display_name is the name the player gave when they joined. Scryboard asks for their character's name there, so it's usually the same as character_name, but not always: join on the ids.

const members = await scryboard.get('members')            // DM scope
const byUser = new Map(members.map((m) => [m.user_id, m]))
const byMember = new Map(members.map((m) => [m.id, m]))
// a fight combatant -> the seat: byUser.get(c.member_user_id)
// an event participant -> seat: byMember.get(p.member_id)

A player-scope token can't read members, but its own character row carries member_id and user_id, so a player app can find its own character in fight (member_user_id === me.user_id). The plain combatants read doesn't carry member_user_id; read fight when you need to know whose row is whose. The DM's own row is in members (role dm) but not in DM-scope character, which lists players only.

Who was at a session

Each sessions row carries attendance: which player characters were there. It's built for drop-in play (West Marches, a rotating table), where "the party" changes from session to session.

"attendance": {
  "confirmed": true,
  "confirmed_at": "2026-10-20T23:10:00Z",
  "attendees": [
    { "member_id": "…", "user_id": "…", "display_name": "Thugsley",
      "character_name": "Thugsley", "joined_at": "2026-10-20T19:02:00Z" }
  ]
}
  • null: nothing is recorded. Older sessions, and any where no player opened the player screen and the DM never confirmed. Don't assume the whole party was there; show "not recorded".
  • confirmed: false: who opened the session's player screen, which Scryboard notes automatically. Likely but not certain: someone at the table may never have opened it. The live session is always unconfirmed.
  • confirmed: true: what the DM ticked under "Who was here?" when they saved the session review. attendees is exactly who was there, possibly nobody ([]). The DM can change it later by reviewing the session again.
  • joined_at is when they opened the player screen, or null if they were there without opening it.
  • Each attendee carries member_id and user_id, so it joins to members, character and fight (Linking a player to their character). A player who has since left the campaign keeps their user_id and name, with member_id: null.
  • Player-scope tokens see it too: players at the table know who was there.
  • events participants are not attendance. Since attendance is confirmed in the review, that session's review scene events list only the players who were there, but older scenes may list the whole party, and other events list whoever was in them.

The sample campaign covers each case: session 1 was never recorded, sessions 2 to 4 are confirmed with a different party each time, session 5 only has who opened the player screen, and the live session lists who has joined so far.

intelligence is the live analysis for one session. current_scene is a short line (8 words or fewer) saying what the party is doing right now, such as "Drinking at the Thornwatch Inn". It's null until the first analysis names a scene, and it updates about once a minute while the DM has the live session page open and recording. DM scope only.

combat_active says whether Scryboard has heard a fight going on: true once the table talk says so (the word "initiative" triggers a quick check within seconds; the live analysis also flags attack rolls, damage and combat described out loud), false once a check finds the fight over, and null before anything has been heard this session. combat_checked_at is when that was last decided. It only changes while the DM is recording, and it can briefly be a false alarm (a rules question about initiative) until the next check clears it. For "is there an encounter on the tracker", read combatants instead: it's what the DM actually set up, and it works without recording. An app that reacts to fights usually wants both. DM scope only.

Its new_canon array is what Scryboard noticed this session that isn't in the notes yet:

{ "type": "character", "subtype": "npc", "name": "Marta the Innkeeper", "description": "Runs the Thornwatch Inn." }

Note name, not title — these are detections, not reviewed items. They become extraction items (with title) only once the DM accepts them at session review. An app that wants "every NPC so far" should merge the two, matching on name against title and aliases.

Don't re-extract what Scryboard already extracted. If your app needs "the NPCs" or "the locations", read extractions (reviewed) plus intelligence.new_canon (live). Running your own LLM over the transcript to find the same things costs your buyer money and will disagree with what the DM sees elsewhere in Scryboard.

Writing widgets

Your app's output can render inside Scryboard — as a card in the live session's dashboard, on the DM's campaign landing page, or on a player's own campaign landing page. Apps send a layout — a tree of nodes describing structure (grids, sections, fields, tables) and a small set of tokens (spacing, semantic color); Scryboard's own components turn that into the actual page. There is no HTML, CSS, or code in a layout — every prop is either a length-capped string or a value from a closed set. App code never runs in the dashboard.

POST https://<your-scryboard-host>/api/agent/widgets
Authorization: Bearer scry_...
Content-Type: application/json
{
  "widget": "Spell usage",
  "placement": "session_dashboard",
  "visibility": "dm",
  "session_id": "<optional uuid>",
  "preferred_height": 4,
  "layout": {
    "type": "table",
    "columns": ["Spell", "Casts"],
    "rows": [["Fireball", 3], ["Bless", 5]]
  }
}
  • widget — stable name; pushing again with the same name updates the same widget (latest output wins, last 20 kept). Pushing again with the same name but a different placement moves it — it doesn't create a second copy, so correcting a wrong placement just means pushing again correctly. Want the same card in two places (a DM copy on dm_landing and a players' copy on player_landing, say)? Give each its own name, such as "Hall of Fame (DM)" and "Hall of Fame". One name pushed to both would keep moving between them. A widget belongs to the app that pushed it. A new token for the same app — a Marketplace install's re-issued token, a personal app's new Runner link, a browser app's per-page token — takes over that app's existing cards, so the next push updates them instead of adding a second copy (the card's button clicks from before the new token are dropped, so a new token never sees old clicks). Tokens you create by hand under App Access Tokens are each their own app: two of them pushing the same name make two cards, each headed with its token's name.

  • placement — session_dashboard (live session view, either role), dm_landing (the DM's persistent campaign page), or player_landing (a player's own persistent landing page). "Dashboard" always means in-session; "landing" always means the persistent page you'd see between sessions. Always set this explicitly. If omitted it defaults to session_dashboard — fine for something meant to be watched live, but a common mistake for a personal widget (a player's spell log, gold tracker, backstory lookup): leave placement out and it lands in the live session view instead of the player's own landing page, where it's also visible on the DM's session dashboard even at visibility: "dm" — see the note below on why. If your widget is meant to live on a player's landing page, set "placement": "player_landing" every time.

  • visibility — dm (default — for a player-issued token this means "just me," not literally the DM; see below), table (everyone at the campaign sees it, including other players) or players (every player sees it, and the DM's own session page leaves it out). Use players when your DM card already holds what the players' card shows, so the DM is not given the same thing twice. It is for tidiness, not secrecy: the DM can still read the card.

  • Your own widgets are always visible to you, regardless of visibility — a player's personal tracker (their gold, their spell log) set to dm visibility is private to that player, not hidden from them. table is for when you deliberately want to share it with the rest of the group.

  • Who sees a player_landing card, by who pushed it:

    Pushed by visibility: "table" visibility: "dm"
    A DM-scope token Every player's campaign page (the same card for all of them), and the DM under View as Player. Not on the DM's own campaign page, which shows dm_landing cards. Nobody. Players can't see a DM-private card, and the DM's campaign page doesn't show player_landing. Use dm_landing for the DM.
    A player-scope token Every player's campaign page, and the DM's View as Player. Only the player whose token pushed it.

    There's no way to aim a card at one particular player from a DM token: a DM app's player card is the same for everyone, so say on it whose part is whose.

  • preferred_height — optional integer, 1-12 (the dashboard grid's own row units; omit it and the current default is used). This is a hint, not an instruction. It only ever sets the card's height the very first time it's placed, with no saved size yet. The moment anyone drags or resizes it, their size is what's saved from then on — you cannot set a height that overrides a size someone chose, and there's no way to "reclaim" a card's size once a player has picked their own. Use it to say "this one's usually a quick line" (1-2) or "this one wants room" (6+) so the card doesn't open cramped or oversized before anyone's had a chance to adjust it.

  • The DM can disable any widget from their dashboard; you can disable your own from wherever it's shown. Pushes to a disabled widget are rejected with 403.

  • The DM can always see every widget in their own campaign, regardless of who created it or what visibility it's set to — that's deliberate (oversight over anything an app pushes into their campaign), not a privacy leak of your data. Combined with the placement default above, this is why a player widget pushed without an explicit placement shows up on the DM's live session dashboard even though it's visibility: "dm" ("just me") — it's sitting in the shared session_dashboard slot, which the DM's session view always shows regardless of visibility. Setting placement correctly is what actually keeps it off the DM's screen, not visibility.

layout node types

Every node is { "type": "<one of these>", ...props, "children"?: [...] }. Unknown types or prop values outside their allowed set are rejected at push time with a specific error, not silently dropped.

Type Props
container direction: "row"|"column", columns?: 1-6, gap: "xs"|"sm"|"md"|"lg", variant?: "plain"|"panel"|"well"|"card" (give the group a visible surface — panel is an inset box with a hairline border, well a soft fill, card a raised one), align?: "start"|"center"|"between" (how a row packs — between pushes the last child to the right edge), background? (either "tone:<tone>" for a themed surface that follows the player's chosen theme, or a fixed "#rrggbb" hex — see below; wins over variant if both are sent), collapsed_label? (≤60 chars — renders the container closed behind a one-line toggle showing this label, instead of its children)
section title (≤60 chars)
field label (≤40 chars), value (≤120 chars), tone?, emphasis?: "normal"|"large", layout?: "inline"|"stacked" (stacked puts the label above a larger value — the stat-tile shape; pair it with a container's columns and variant for a stat row)
text value (≤500 chars), tone?, size?: "sm"|"md"|"lg", weight?: "normal"|"bold", italic?: boolean
table columns: string[], rows: (string | number)[][] — each cell is shown as text, so numbers are fine (["Fireball", 3]); null, objects and arrays in a cell are not useful, convert them first
badge label (≤24 chars), tone?
divider —
meter value (required, number), max (required, number > 0), label? (≤40 chars), tone?, style?: "bar"|"pips" (pips for a small countable quantity like spell slots — falls back to a bar when max is over 12, since pips stop being countable at a glance), show_value?: boolean (default true — shows value / max)
icon exactly one of name (from the curated set — a typo is rejected at push time, not silently blank) or media_id (your own uploaded artwork, same path as image), plus size?: "sm"|"md"|"lg", tone? (named icons only — see below), alt?
stat value (required, ≤24 chars), label? (≤24 chars), sub? (≤40 chars), trend?: "up"|"down"|"flat", tone?, icon? (a curated icon name). The dashboard tile — built to sit in a row of four and be read across a table.
callout text (required, ≤300 chars), title? (≤60 chars), tone?, icon? (a curated icon name). A toned box for "this one matters" — reads as a callout rather than as ordinary prose.
richtext value (required, ≤2000 chars — plain text with a small markup subset, see below), tone?, size?: "sm"|"md"|"lg". Using a link inside the value requires the widgets:link write scope.
link href (required, https only), label (required, ≤80 chars), tone?. Requires the widgets:link write scope — see below. At most 20 per widget.
gallery columns?: 2-6 (default 4), children = gallery_item nodes. A wrapper — put the thumbnails in children.
gallery_item exactly one of media_id or url (https only), plus caption? (≤60 chars), selected?: boolean (marks the one already chosen), alt?, and action_id? — give it an action_id and the thumbnail becomes the pick control: clicking the image fires a click you poll back from actions, exactly like an action button. At most 24 per widget.
chart points (required, an array of numbers, 1–60), kind?: "bar"|"line"|"donut" (default bar), labels? (must have exactly as many entries as points — a mismatch is refused rather than silently mislabelled), label? (≤40 chars), tone?, show_value?: boolean. You send numbers; Scryboard draws the SVG — there is no way to send a path, a pixel or a color. Deliberately small: one series, no axes, no legend, no tooltips. If you need a real chart, link out to one.
input setting_key (required, a 1–64 char lowercase slug), item_key? (≤64 chars). A bookmark, not an input. It says "the settings box for this goes here" — Scryboard moves a box it was already going to draw into your layout, instead of appending it below everything. You never see or set the value through this node; you read it back with getSettings() as always. setting_key must be a setting your manifest declares, or the push is refused. Marketplace installs and personal apps both have a manifest; a hand-issued token has none, so pushing an input node with one gets 400 "input nodes need an installed app with declared settings" (leave the node out while testing that way). Omit item_key for an app-wide setting; give it for a per-item one. Needs no extra write scope.
panel panel_id (required, a 1–64 char lowercase slug). Prototype. Says "this app's own interface goes here": Scryboard draws the named panel, built from files in your app's zip, in a sealed frame inside the card. panel_id must be one of the panels your manifest declares, or the push is refused. At most one per widget. Panel tokens (the ones a panel's page uses) can't push widgets. Not yet open to Marketplace submissions while the prototype is tested. Partner pages: a panel can instead show one page of an approved partner's own site. Declare "partner_page": { "url": "https://dddice.com/room/{room}", "player_url"?: …, "sound"?: true } on the panel in place of entry, and fill the blanks by saving short codes (letters, digits, -, _) in your app's memory: setState('panel:<panel id>', { room: 'abc123' }). You never send a whole address, the site must be one Scryboard has approved, and the page gets no Scryboard data. Nobody signs in inside the card, so point it at a page that opens without a login.
steps children = step nodes. A progress track for multi-stage work.
step label? (≤40 chars), state?: "todo"|"current"|"done" (default todo).
list variant?: "plain"|"divided"|"boxed", children = list_item nodes. A wrapper — put the rows in children.
list_item title? (≤80 chars), subtitle? (≤120 chars), tone?, state?: "normal"|"active"|"dim" (active marks the row the table is on right now, dim one that's finished), exactly one of icon? (curated name) or media_id? (your own artwork) for the leading image, plus children — nest a meter, a badge, even an action button inside a row and it just works.
image exactly one of url (https only, proxied and validated server-side, 5MB max) or media_id (a UUID from Uploading media — must be live media in the same campaign), plus alt, fit?: "contain"|"cover", size?: "thumb"|"sm"|"md"|"full" (named buckets — Scryboard decides the pixels; there is no way to state a height), shape?: "square"|"rounded"|"circle" (circle gives you an avatar; put one in a direction: "row" container to sit it beside text)
video video_id (an 11-character YouTube video ID — not a URL), title? (≤100 chars). Requires the widgets:video write scope — see below.
action action_id (a 1–64 char slug: lowercase a-z, 0-9, _, ., :, -, starting with a letter or digit), label (required, ≤40 chars), tone?. Renders as a clickable button — see below. At most 40 per widget.

tone? is the only color channel, mapped to Scryboard's own palette — there is no way to send a raw color. It comes in two groups:

  • State — "default", "gold", "muted", "danger", "success". Use these for how something is going: urgent, resolved, secondary.
  • Subject — "arcane", "frost", "ember", "nature". Use these for what something is: a school of magic, a damage type, a faction, a terrain. They carry no good/bad meaning, so a reader doesn't misread "this NPC is fire-aligned" as "this NPC is a problem."

Every tone follows the player's chosen theme, so pick by meaning and it will look right in all of them. A tree may nest up to 6 levels deep and 400 nodes total, within an overall 60KB per push.

Over 400 nodes or 60KB, the card is trimmed rather than refused. Scryboard drops entries from the end of the card's longest list (the node with the most children) until it fits. It then adds a quiet line at the end, "Showing 120 of 300: the rest didn't fit in one card.", and pushes that. The reply carries "warnings": ["The card was trimmed to fit …"], and the same line appears under your app's Recent problems on Your Apps. So put what matters most first in a long list. If you'd rather choose what to leave out yourself, keep the card under the limits: count nodes through children, and measure the layout's JSON with a space after each : and ,, as the database does. A card with no list to shorten (one huge node) is still refused. Nesting deeper than 6 levels is still refused too.

Give each gallery_item its own action_id and the thumbnail is the button — clicking the picture fires a click you read back from the actions resource, the same way an action button does. That's the whole "generate four variants, let them choose one" flow:

{
  "type": "gallery",
  "columns": 4,
  "children": [
    { "type": "gallery_item", "media_id": "…", "caption": "01", "action_id": "pick:01", "selected": true },
    { "type": "gallery_item", "media_id": "…", "caption": "02", "action_id": "pick:02" },
    { "type": "gallery_item", "media_id": "…", "caption": "03", "action_id": "pick:03" },
    { "type": "gallery_item", "media_id": "…", "caption": "04", "action_id": "pick:04" }
  ]
}

Notes:

  • Who may click is enforced server-side, identically to an action button: the campaign's DM, or whoever's token pushed the widget. Nothing about that is the app's to decide.
  • selected marks the item that's already been chosen. It's for showing a decision that's been made, not for making one — the pick still happens through action_id.
  • Leave action_id off and the item is just a picture. That's the right choice for a contact sheet, and better than a click target that does nothing.
  • Re-clicking while a click is still pending is coalesced, not queued — same guard as action (see the action node).

richtext — a small markup subset

richtext takes plain text, and Scryboard recognises four things in it:

Write this Get this
**bold** bold
*italic* or _italic_ italic
lines starting - or * a bulleted list
[label](https://example.com) a link (needs widgets:link)

Everything else is text. This is a parser over those four constructs, not an HTML sanitiser — if you write <script>, your reader sees the literal characters <script>, because nothing you send is ever treated as markup. That also means malformed markers are harmless: an unclosed ** just shows up as asterisks rather than failing your push.

Two consequences worth knowing:

  • Bare URLs are not auto-linked. Mentioning https://example.com in prose stays text. Turning a mention into a click target without being asked is exactly the kind of helpfulness that surprises a reader, so you have to write the [label](url) form deliberately.
  • A non-https link degrades to visible text, not to a silently dropped link. [x](javascript:alert(1)) renders as those literal characters.

Anything clickable that leaves Scryboard needs the widgets:link write scope — whether it's a link node or a link written inside a richtext value. Declare it in scryboard.json alongside widgets:

{ "scopes": { "writes": ["widgets", "widgets:link"] } }

It's gated for the same reason widgets:video is: a clickable third-party destination in front of a whole table is a bigger surface than declarative data, so a buyer sees it on the install screen rather than trusting review alone. widgets:link on its own grants nothing — it must accompany widgets.

Without the scope, links show as plain text. A card from an app that doesn't declare widgets:link still shows: each link node becomes a text node of its label, and each [label](https://…) in richtext becomes just its label. The reply then carries "warnings": ["Links were shown as plain text: …"], and the same sentence appears under your app's Recent problems on Your Apps. This matters for an app that shows text it didn't write, like the DM's notes: one pasted link no longer costs the whole card.

What Scryboard does with every link, regardless of what you ask for:

  • https only. No http:, no javascript:, no data:, no protocol-relative //host, and no embedded whitespace or control characters (the usual way a scheme gets smuggled past a naive check).
  • Opens in a new tab with rel="noopener noreferrer", so a click never navigates a DM away mid-session and the destination can't reach back.
  • Carries a visible ↗ marker and shows the real destination on hover — so a link can't pass itself off as Scryboard's own navigation, whatever its label says.

Icon names

114 curated names, drawn from Lucide. An unknown name is rejected at push time with a specific error, so a typo fails loudly rather than leaving a blank space on a card.

Group Names
Combat & danger sword, swords, shield, shield-check, skull, flame, zap, target, crosshair, bone, ghost
Magic & the arcane sparkles, wand, wand-sparkles, star, moon, sun, atom, orbit, biohazard
People & parley user, users, user-plus, crown, handshake, message-square, footprints
Health & condition heart, heart-crack, heart-pulse, activity, pill, bandage, stethoscope, flask-conical
Items & treasure gem, coins, backpack, package, box, key, key-round, lock, lock-open, vault, scale
Places & travel map, map-pin, compass, tent, mountain, trees, castle, home, building, church, door-open, door-closed
Creatures & nature leaf, bug, rat, bird, fish, cat, dog, rabbit, turtle, shell
Weather & elements snowflake, cloud, cloud-lightning, wind, droplet, waves
Time & tracking clock, hourglass, timer, calendar, bell, gauge
Craft & tools hammer, axe, pickaxe, anvil, wrench, pencil, feather
Lore & knowledge scroll, scroll-text, book, book-open, library, bookmark
Food & rest utensils, beer, wine, coffee, wheat
Status & direction check, check-check, x, plus, minus, arrow-up, arrow-down, trending-up, trending-down, circle-alert, triangle-alert, info, eye
Dice dices, dice-1, dice-6

A named icon takes its colour from tone, like any other node.

Need something outside this set? Use media_id instead — your own uploaded artwork, through the same path image uses. Two honest differences: an uploaded icon is a fixed full-colour image (the media pipeline re-encodes everything to WebP and rejects SVG, so there is no line art to tint, and tone does nothing), and unlike image.media_id it is not checked at push time for being live media in your campaign — a stale id renders as a broken image rather than a rejected push.

container.background — your own surface

Two forms, and nothing else is accepted:

  • "tone:arcane" — you pick the meaning, the player's theme picks the actual colour. The same card renders purple-on-brown in Parchment/Tavern, violet-on-gunmetal in Forged Steel and hot magenta in Arcane Neon, and your app never learns which. Reach for this if you want your card to look like it belongs.
  • "#1a0e2e" — a fixed six-digit hex. You pick the colour and the theme has no say, so it looks the same in every preset. Reach for this if the colour is your app's identity. Be aware it will look foreign to a player who chose a different theme.

Only a hex or a tone: string is accepted — never a CSS value, so there is no url() and therefore no request leaving the page from a background.

Scryboard always picks the text colour. Whatever background you send, we measure its brightness and put our light or dark text on it, so you cannot make a card unreadable by accident. One caveat: an explicit tone on a node inside a coloured container still resolves from the theme and can clash (danger red on a red ground). If you set a strong background, leave the tones inside it alone.

Naming your widget

The widget name is yours, with three rules — all rejected at push time with a specific error, never silently rewritten:

  • 40 characters or fewer.
  • No reserved words: scryboard, official, verified, first-party, built-in, billing, payment, password.
  • Latin letters, digits, spaces and ordinary punctuation only. Accented characters are fine; other scripts are not.

Your card's title bar shows the name of your app from its Marketplace listing — which you can't set from your code — followed by this widget name in quieter type. On a narrow screen the widget name is what gets dropped first, so put the identifying word early.

video — YouTube embeds, gated behind their own scope

A video node renders as a click-to-play YouTube player: a static thumbnail until the viewer clicks, then a sandboxed youtube-nocookie.com embed. Because a playable third-party embed is a bigger capability than a static image, it's opt-in on top of plain widget access:

  • Declare both "widgets" and "widgets:video" under scopes.writes in your manifest. A push containing a video node from a token whose app didn't declare widgets:video is rejected, even if plain widget pushes work fine.
  • video_id is the 11-character ID only — from https://www.youtube.com/watch?v=dQw4w9WgXcQ, send "dQw4w9WgXcQ". URLs of any kind are rejected: your app picks which video plays, never where the embed points.
  • At most 3 video nodes per widget.
  • The embed can't autoplay before the viewer clicks, can't navigate the page, and can't open popups — Scryboard owns the iframe and its sandbox, not your layout.
  • Buyers see widgets:video spelled out on your listing's permissions panel, so say what you play and why in your description.
{ "type": "video", "video_id": "dQw4w9WgXcQ", "title": "How counterspell actually works" }

action — a button your app polls for clicks

The layout schema is deliberately display-only, with one narrow exception: an action node renders as a button — Scryboard's button, not yours. Your app declares a stable action_id and a human-readable label; a click is recorded server-side, and your app reads it back on its next poll via the actions read resource (see the table under Reading data). No callback URLs, no code in the dashboard — a click is just data flowing back the other way. This is the intended replacement for file-based triggers ("drop a file named sync-now next to the app") for anything that needs a human-initiated "do it now."

  • Clicks wake your app. On the App Runner (0.2.7 and later), a click on one of your buttons, or the buyer saving one of your settings boxes, runs your tick within a second or two instead of waiting for your next poll interval. Nothing new to call: the next tick simply finds the click or the new value through the same reads as before. Don't rely on it — older Runners, and any moment the Runner can't reach Scryboard's live connection, fall back to your normal poll — and expect an occasional extra tick, since a few quick clicks may wake you more than once.
  • Declare actions under scopes.reads in your manifest to read clicks back. The node itself needs only plain widgets write access — the button renders either way, but without the read scope you'll never see the clicks.
  • Who can click, deliberately conservative for now: the campaign's DM, or the user who issued the widget's token (its owner). Each click records which of the two it was as clicked_by_role: "dm" | "owner" — no user identities.
  • The clicked action_id must exist in the widget's latest output, or the click is rejected — a click is a response to what your app is currently showing, so keep action_ids stable across pushes for buttons that mean the same thing.
  • Poll with since set to the newest created_at you've already processed, and persist that high-water mark between ticks. On first run, seed it from the newest existing click, so clicks from before your app started are treated as history — see Paging through a feed. Clicks are retained for about 30 days.
  • One pending click per button. While your app hasn't pushed the widget again since a click (for up to 10 minutes), further clicks on the same action_id are folded onto the pending one — nothing new is queued, and the button keeps showing "sent". So an impatient DM never hands you a burst of duplicates; you'll see one row. Still treat a click as "do it (again) now" and keep the handler idempotent — after you re-push, a fresh click is a fresh row.
  • Push the widget again after acting on a click (most apps push every tick anyway). The pushed output is what tells the button — and the pending-click rule above — that the app has caught up.
  • Cap: 40 action nodes per widget (the whole layout is capped at 400 nodes).
  • Client library: scryboard.getActions({ since }) — or the plain scryboard.get('actions', { since }), which is all a node_cli app needs.
{ "type": "action", "action_id": "sync_now", "label": "Sync from your wiki", "tone": "gold" }

Minimal poll loop (works against the mock server as-is — push a widget with the node above, click it on http://localhost:4747, then run this):

if (!state.actionsSince) {                // first run: old clicks are history
  const [latest] = await scryboard.get('actions', { order: 'newest', limit: 1 })
  state.actionsSince = latest?.created_at ?? new Date().toISOString()
}
let since = state.actionsSince            // persisted between ticks
let syncRequested = false
for (;;) {
  const clicks = await scryboard.get('actions', { since, limit: 200 })
  for (const click of clicks) {
    since = click.created_at
    if (click.action_id === 'sync_now') syncRequested = true
  }
  if (clicks.length < 200) break
}
state.actionsSince = since
if (syncRequested) await doTheSync()      // once, however many clicks arrived
await scryboard.pushWidget({ /* ...fresh layout... */ })

Example: a compact stat block, using a grid and semantic color together.

{
  "type": "container", "direction": "column", "gap": "sm",
  "children": [
    { "type": "field", "label": "Elowen", "value": "Ranger 5", "emphasis": "large" },
    { "type": "container", "direction": "row", "columns": 6, "gap": "xs", "children": [
      { "type": "field", "label": "STR", "value": "12 (+1)" },
      { "type": "field", "label": "DEX", "value": "18 (+4)", "tone": "gold" },
      { "type": "field", "label": "HP", "value": "12 / 44", "tone": "danger" }
    ]}
  ]
}

Whole-push content is capped at 60KB.

Reading what the buyer told you

If your manifest declares settings (see the manifest guide), the buyer fills those boxes in on Scryboard's own installed-apps page and you read the answers back here.

GET https://<your-scryboard-host>/api/agent/settings
Authorization: Bearer scry_...

Returns your app-wide answers at the top level, plus an items object holding the per-item ones:

{
  "data": {
    "art_direction": "grim oil painting, muted colours",
    "items": {
      "npc-123": { "portrait_note": "tired, greying, missing a tooth" }
    }
  }
}

items is always present, possibly empty, so you never have to guard for it. It contains only the items you most recently pushed (below) — a value belonging to something you've stopped listing is kept, but not reported, so you can't act on a thing you no longer have.

  • No read scope needed. settings is not a resource on the read table above and takes nothing in scopes.reads — declaring the setting in your manifest is the declaration. A scope gate on values the buyer typed for your app specifically would protect nothing.
  • Declared-but-unanswered keys come back as "", so "not answered" is one case to handle rather than two. An app with no declared settings — or a hand-issued token during local development — gets { "items": {} } rather than an error, so the same code runs in both places.
  • Values are per install. The same person installing your app on two campaigns answers separately.
  • The buyer can edit any value at any time, so read it fresh each tick instead of caching the install-time answer.
  • A change never triggers anything on its own. You see the new value on your next tick and decide. If acting on it spends the buyer's money at a third party, show that the previous result is out of date and wait for a button — don't redo the work automatically.

Client library: scryboard.getSettings().

Asking about each thing in a list

An app with one subject can use one settings box. An app with a list can't: a single shared "extra detail" box would silently apply whatever was typed last to whichever thing you act on next. If acting costs the buyer money, that means paying for the wrong result — with nothing looking wrong until it arrives.

Declare the setting with "scope": "item" in your manifest, then tell Scryboard which things to render a box for:

POST https://<your-scryboard-host>/api/agent/settings/items
Authorization: Bearer scry_...
Content-Type: application/json
{
  "items": [
    {
      "key": "npc-123",
      "label": "Marta the Innkeeper",
      "placeholder": "Runs the Thornwatch Inn; knows local rumours…"
    }
  ]
}
  • This is the only thing you may write about settings — which items exist, never what any value is. The buyer's answer only ever comes from the buyer typing it. That split is what makes settings safe, and it's why placeholder is greyed-out suggestion text shown while a box is empty rather than a value you can set.
  • Replaced wholesale on every call, like a widget's content. Send your full current list each time; a list that only ever grew would fill with things the buyer deleted months ago.
  • You choose how many boxes appear. An app with 300 NPCs should send the one its widget currently has selected — click a character, and the box below becomes that character's box. Limit is 50, as a backstop.
  • key is your own id (≤100 chars, opaque to Scryboard), label is what the buyer reads (≤80), placeholder is optional (≤300).
  • Needs a Marketplace install or a personal app. A hand-issued token gets 404 "Setting items need a Marketplace install or a personal app": there is nothing for the boxes to belong to. (A personal app has one set of settings per campaign it's connected to.) When testing with dev-runner and a hand token, catch that 404 and carry on (getSettings() already returns { "items": {} } there), or test settings through a real install.
  • Rejected with 403 if your manifest declares no "scope": "item" setting — a list with nothing to render against it is a mistake worth hearing about rather than storing silently.

Read the answers back from GET /api/agent/settings above, under items.

Client library: scryboard.setSettingItems([...]).

Uploading media

Apps with the media write scope can upload images for Scryboard to store and serve itself — how you show generated art (a portrait, a map tile, a render preview) in a widget without hosting it anywhere. This is distinct from the image node's external-url path: Scryboard never fetches a URL your app hands it for stored media — the bytes come in the request body, once, and get served from Scryboard's own private storage after that.

POST https://<your-scryboard-host>/api/agent/media
Authorization: Bearer scry_...
Content-Type: multipart/form-data

Send a file field with the raw image bytes, optionally an alt field (≤200 chars) describing the image, and optionally a visibility field.

Who can see an upload:

  • From a DM-scope token, media is DM-only by default — players can't list it or download it, the same as a visibility: "dm" widget. Send visibility: "table" when the image is meant for everyone at the table.

  • Showing a DM-only image on a visibility: "table" widget also puts it on the table: pushing the widget is the reveal. This is one-way. So an image you only ever show on DM widgets stays private, and one you show to the table works for the players without any extra step.

  • From a player-scope token, media is always visible to the whole campaign; visibility is ignored.

  • PNG, JPEG, or WebP in — no SVG. 8MB max, and sources over 8192px on a side are rejected outright.

  • Every upload is decoded and re-encoded server-side (resized to at most 2048px, stored as WebP, EXIF/metadata stripped) — the stored object is never your literal bytes, which is also why an animated upload becomes its first frame.

  • Returns { media_id, campaign_id, tier: "draft", expires_at, visibility }.

  • Uploads start as drafts that expire in 30 days. Once the DM has accepted the asset (e.g. attached it to a confirmed entity), promote it: PATCH /api/agent/media/{media_id} with { "tier": "accepted" } removes the expiry. One-way — there's no demoting back to draft. Drafts are cheap to regenerate; accepted art lives as long as the campaign.

  • Uploads have their own budget — 30/hour per token — on top of the general 120/min API limit, since storage and processing are the expensive path.

To show a stored image in a widget, put its id on an image node:

{ "type": "image", "media_id": "9f4c1e2a-…", "alt": "Portrait of Marta the Innkeeper" }

Exactly one of url / media_id per image node, and the media_id must be live (unexpired) media in the same campaign, or the push is rejected. Scryboard serves it via GET /api/media/{media_id} to the signed-in users allowed to see it (above) — the renderer builds that URL itself, so your layout never controls where an image request goes.

Client library: scryboard.uploadMedia({ data, alt, visibility }) (where data is a Buffer or Uint8Array of image bytes, and visibility is optional) and scryboard.setMediaTier(media_id, 'accepted'). The visibility option needs a current App Runner; an older Runner uploads without it (DM-only), and the table-widget rule above still makes the image visible wherever you show it to the table.

Buyers see media spelled out on your listing's permissions panel, so say what you upload and why in your description.

Importing character data

Player-scope tokens can also write structured character data — stats, inventory, spells known, whatever a source system has — for the token's owner to read back and turn into a widget. This is how you'd build "my character's gold," "my spell list," or "my backstory" from a D&D Beyond export, an OCR'd paper sheet, or anything else: import once, read back, render as a widget.

POST https://<your-scryboard-host>/api/agent/character
Authorization: Bearer scry_...
Content-Type: application/json
{
  "category": "ability_scores",
  "data": { "str": 16, "dex": 12, "con": 14, "int": 10, "wis": 8, "cha": 13 }
}
  • Player-scope tokens only — a DM-scope token isn't tied to a single character, so it can't use this endpoint.
  • category — a free-form key you choose (1–60 chars), e.g. ability_scores, inventory, spells_known, backstory. No fixed schema, since source systems vary wildly — pick names that make sense for what you're importing.
  • data — any JSON, up to 20KB per category. Pushing again with the same category replaces that category's data entirely (not a deep merge); other categories are untouched. 200KB total cap across all categories for one character.
  • Read it back via the character resource on the read API (a different app can read what another one imported, as long as both authenticate as the same player) — see the table above. character_data comes back keyed by category, e.g. { "ability_scores": {...}, "inventory": {...} }.
  • From there, build whatever widget makes sense — a grid of field nodes for ability scores, a table for inventory, a text node for a backstory — and push it to player_landing (see Writing widgets above).

Proposing canon

DM-scope tokens can propose new or updated content for one of a campaign's extraction layers — the same layers a DM's own note uploads land in. This is how you'd build a world-bible sync from an external source (a wiki, a campaign-notes tool, anything with structured lore) without asking the DM to copy-paste it in by hand.

POST https://<your-scryboard-host>/api/agent/extractions
Authorization: Bearer scry_...
Content-Type: application/json
{
  "layer": "world_bible",
  "items": [
    { "id": "...", "type": "location", "title": "The Sunken Archive", "description": "...", "flagged": false, "confirmed": false }
  ]
}
  • DM-scope tokens only — there is no player-write path for canon, anywhere in the API, and this endpoint is no exception.
  • layer — one of session_history, session_notes, world_bible, adventure_structure, pc_notes, homebrew_registry.
  • items — the layer's full array (this replaces the layer's current items, it does not append or merge), up to 500KB. Same item shape as the extractions read resource (type, optional subtype, title, description, …) — see the note on that resource above. If what you're proposing has structured data that doesn't fit title/description text (a monster's stat block, an item's numeric properties), put it in attributes — see the same note.
  • This never publishes anything. However it's called — a Marketplace app, your own script, anything — the write always lands unverified, exactly like a fresh extraction batch the DM hasn't reviewed yet. It only becomes trusted, and player-visible where a layer allows that, once the DM confirms it through Scryboard's own review flow (/campaigns/{id}/verify/{layer}). There is no way for a token to mark its own write verified.
  • Declare extractions under writes in your manifest's scopes to use this. Because it's DM-scope-only, a listing that declares it automatically requires a DM to be the one who installs it, the same as declaring a read on transcript or members does.
  • If all you want is to attach structured data to one item the DM already confirmed — not propose new canon — this is the wrong tool: it replays your possibly-stale copy of every other item and drops the whole layer back to unverified. Use the per-item attributes write below instead.
  • If the material is something the DM already treats as truth — their own wiki, their own world-building tool — and re-approving it item by item is the friction rather than the safeguard, see Importing canon.

Importing canon

DM-scope tokens with the canon_import write scope can import structured items into the World Bible as confirmed canon, each with a visible source tag, without overwriting anything a session already established. This is for material the DM already owns and trusts (their world-building wiki, say), not for scraped or generated content — the review gate the listing goes through will ask.

POST https://<your-scryboard-host>/api/agent/canon-import
Authorization: Bearer scry_...
Content-Type: application/json
{
  "layer": "world_bible",
  "items": [
    {
      "type": "location", "subtype": null,
      "title": "Emon", "description": "Capital of Tal'Dorei …",
      "source": { "provider": "examplewiki", "id": "8650692", "url": "https://wiki.example.com/entities/8650692" }
    }
  ]
}
  • DM-scope tokens only; canon_import must be in the token's granted writes; layer is world_bible, session_notes or adventure_structure. pc_notes and homebrew_registry are never written by an import, whatever it matches.
  • session_notes (Session Prep) and adventure_structure take beats only — type: "beat", optionally with priority (must, should or if_time; beats only, in any layer). session_notes is for a DM's own plan for the next session from a prep tool; adventure_structure is for their longer arc — acts, chapters, villain plans, turning points that span sessions. The arc's people, places and factions go to world_bible in a separate call, like any other entity. Beats never fold into other items: each is inserted, or updated in place by provider+id like any import. Prefer this to the full-layer extractions write for both layers: your token only reads verified layers, so replacing the layer from what you can see could wipe prep the DM hasn't verified yet, and the layer drops back to unverified every time.
  • Up to 100 items per call; title ≤ 200 chars, description ≤ 20 000 chars; source.provider [a-z0-9_-]{1,40}, source.id ≤ 100 chars, source.url an https URL if given; the whole body up to 4 MB.
  • One import call counts as 10 requests against the rate limits (120 a minute per token), because each one checks its items against the whole World Bible. That is 12 calls a minute at most: when importing a large set, send a batch every 5 or 6 seconds, and treat a 429 as "wait half a minute", not as a failure. Smaller batches (50 or so) also answer faster against a large World Bible than full ones. An App Runner app's single run is stopped after 10 minutes, so a very large import should save its progress and carry on in the next run.
  • What happens to each item (the same entity resolution the DM's own review-save runs: names, aliases and the obvious variants of a name are matched, and a description that contradicts the existing one is flagged rather than merged):
    • already imported (same provider+id) → unchanged, or updated in place if the content changed (idempotent — re-send freely);
    • matches an existing item in a DM layer without contradiction → merged: the existing item keeps its text, gains the new text under a "[New details merged in …]" marker, an alias, and the review flag;
    • matches with a contradiction → conflict: an open conflict on the existing item for the DM to resolve; nothing is replaced;
    • matches an item in pc_notes/homebrew_registry, or one that already has an open conflict → skipped (with a reason);
    • genuinely new → imported: inserted into the target layer, confirmed: true, flagged: false, with source: { provider, id, url, hash, importedAt, mode: 'imported' }.
  • Prep the table hasn't met yet: "status": "planned". Add it to a World Bible character, faction, location or item and a new entry is created Planned: the DM's own lore that hasn't come up in play (an unrevealed villain, a town the party hasn't reached). Planned entries are left out of extractions unless an app asks with include_planned=true, so player-facing apps never show them, and they become canon when the DM approves them in a session review. If you import a DM's notes or wiki, this is almost always what you want: without it every entry lands as established canon. It only applies when the entry is created: an update, or a fold into an existing entry, never changes that entry's status. Any other value, or planned on a beat, a rule, a history item or another layer, is refused with a 400.
  • What an import can't do: remove an entry (the DM deletes it in the World Bible), or set aliases (put other names in the description; the matching reads them from there).
  • Response: { imported, updated, unchanged, merged, conflicts, skipped: [{ title, reason }], results: [{ source, title, outcome, reason? }], layers_written, notice? } — results is one entry per input, same order (each carries its source, so you can match on source.id too).
  • notice appears when the duplicate check couldn't use AI: each app has a daily allowance of AI duplicate checks per campaign, paid for by Scryboard, and a sample campaign never uses AI. The import still succeeds: items are matched by exact name instead, and new entries are flagged for the DM to check. notice is a sentence written for the DM, so show it on your card rather than hiding it.
  • If the DM saves something between the resolution and the write, the call fails with 409 … changed during import — retry rather than clobbering; the endpoint retries once itself.
  • Imported and merged items carry source on the extractions read too, so an app that syncs the other way can (and should) leave them alone — a wiki-sync app never pushes an item whose source.provider is its own back to that wiki.
  • On the verify page they show as a small "imported" tag. The tag never names your app: Scryboard's own pages describe what came in, not which product it came from.
  • GET /api/agent/canon-import is a status probe: { role, allowed, reason, layers } — never an error for a valid token, so an app installed with the wrong scope can tell its DM rather than fail quietly.
  • Client: scryboard.importCanon({ layer, items }) and scryboard.canonImportStatus() (agent-runtime; App Runner v0.2.1+). Declaring canon_import forces a DM installer, same as extractions. browser_sandboxed apps have both too.

Attaching data to confirmed canon

DM-scope tokens with the extractions:attributes write scope can merge keys into one extraction item's open-ended attributes object — the free-form bucket described under Reading data — without touching anything else. This is how an app that just produced an artifact for a confirmed entity (a portrait's media_id, an STL file's reference, a computed stat) records the pointer on that entity.

POST https://<your-scryboard-host>/api/agent/item-attributes
Authorization: Bearer scry_...
Content-Type: application/json
{
  "layer": "world_bible",
  "item_id": "...",
  "attributes": { "my_app": { "portrait_media_id": "9f4c1e2a-…" } }
}
  • Deliberately narrower than Proposing canon: it cannot create or delete items, cannot touch title, description, confirmed, or verified, and — unlike the full extractions write — it does not drop the layer back to unverified. The DM's review stays intact; only the opaque attributes bucket changes.
  • DM-scope tokens only, same rule as extractions. Declaring extractions:attributes in your manifest likewise forces a DM to be the installer.
  • The merge is shallow, key by key: existing keys you don't mention are untouched, and a null value deletes that key — so your app can clean up after itself.
  • Caps: 10KB per patch, 20KB per item's attributes after the merge.
  • Every call is logged to the campaign's event log (which keys were touched, attributed to your app by name), so the DM can always see who wrote what.
  • attributes has no fixed schema and no enforcement between apps — namespace your keys (e.g. { "my_app": { ... } }) so apps don't clobber each other. Convention, not enforcement.
  • Client library: scryboard.setItemAttributes(layer, item_id, attributes).

Save to World Bible buttons

An app with the canon_save write scope can put Save to World Bible buttons in its card. The DM types into one of the app's own per-item text boxes (settings with "scope": "item", placed with an input node), then clicks the button. Scryboard copies what the DM typed into the World Bible. Your app never sends the words, so it cannot change them, and nothing is written without the DM's click.

A save button is an ordinary action node with a canon_save object:

{ "type": "action", "action_id": "wb:<item id>", "label": "Add text to \"Bone Dagger\"",
  "canon_save": { "mode": "append", "item_id": "<item id>", "item_key": "<box item_key>", "setting_key": "model_description" } }
  • append: adds the box's text to the end of that World Bible entry's description. Never replaces anything; does nothing if the text is already there.
  • create: adds a new, confirmed World Bible entry. item_key + setting_key is the description box, title_item_key (+ optional title_setting_key, defaulting to setting_key) the name box. Optional type (item, character or location; default item) and subtype. A name already in the World Bible is refused. Every per-item setting appears on every item, so the usual pattern is one declared setting used on two items you push (e.g. new-name, new-desc), with the name box relabelled: an input node may carry a plain-text label (60 characters) that replaces the field's label where you place it.
  • undo: { "mode": "undo", "item_id": "…" } puts back the description from before the last save to that entry, or removes an entry create made, only if nobody has changed it since.

Rules: only the campaign's DM can click one, your token must be DM-scope, and only World Bible entries can be changed. Scryboard saves any unsaved typing in the named boxes before the click goes through. A refused save records no click; a successful one does (your app sees wb:… in actions like any click), so redraw the card to show what changed. Every save and undo is logged in the campaign's event log. Any other button that reads a box can carry "saves_input": { "item_key": "…", "setting_key": "…" } so Scryboard saves the DM's unsaved typing before the click (client-side only; it changes nothing on the server).

Changing the fight

Apps that run combat (an initiative tracker, a character sheet with an HP box) can change the live fight, not just read it. Declare the combat write scope; buyers see it at install.

Read the fight (needs combatants):

GET /api/agent/fight?session_id=<session uuid>&events=50
{ "data": {
  "session_id": "…", "round": 2, "turn_combatant_id": "…",
  "combatants": [ { "id": "…", "name": "Hobgoblin", "initiative": 17, "hp": 6, "max_hp": 11,
    "temp_hp": 0, "ac": 18, "is_player": false, "is_ally": false, "member_user_id": null,
    "conditions": ["Frightened"], "death_save_successes": 0, "death_save_failures": 0,
    "stable": false, "dead": false, "stat_visible_to_players": false, "monster_block": { … } } ],
  "events": [ { "id": "…", "kind": "damage", "combatant_name": "Hobgoblin", "actor_name": "Laszlo",
    "amount": 5, "damage_type": "piercing", "round": 2, "by_app": "Your app", "undone_at": null, "created_at": "…" } ]
} }

Combatants come in turn order (initiative, highest first). member_user_id says which player a row is, so match players by it, not by name. monster_block is null for a player-scope token unless the DM shows that monster's stats. events is the newest changes first (up to 500).

Change the fight (needs combat):

POST /api/agent/fight
{ "session_id": "<session uuid>", "action": { "type": "damage", "target": "<combatant id>", "amount": 5, "damage_type": "piercing", "actor": "<combatant id>" } }
type Fields Who
damage target, amount, damage_type?, actor? DM: anyone; player: own character
heal target, amount, actor? DM: anyone; player: own
temp_hp target, amount (sets it) DM: anyone; player: own
set target, any of hp, max_hp, ac, initiative; DM only: monster_block (a stat block object, at most 50,000 characters, or null to clear it) DM: anyone; player: own
death_save target, result: success / failure / reset DM: anyone; player: own
condition target, condition, on: true/false DM
turn direction: next (default) / previous DM
set_turn target DM
add name, initiative?, hp?, max_hp?, ac?, is_player?, is_ally?, monster_block? DM
remove target DM
undo event_id? (default: your last change) DM: anyone's; player: own

The rules, applied by Scryboard so every app behaves the same:

  • Temp HP soaks damage first. HP never goes below 0.
  • A player character at 0 HP takes damage as a failed death save; three failures is dead, three successes is stable. Healing a dead character is refused until a death_save reset. Healing clears death saves.
  • A monster dropping to 0 is logged with detail.defeated: true.
  • turn follows initiative order and moves the round on past the last combatant (and back with previous).
  • Every change is logged with its values before, so it can be undone. Undo goes newest first: undoing an older change to a combatant who has changed since is refused until the newer ones are undone.

The reply is { "event_id", "combatant" (the row after the change), "fight": { "round", "turn_combatant_id" } }. A player-scope token changing someone else's character gets 403.

From an App Runner app (Runner 0.2.16 or newer): await scryboard.fight.act(session.id, action), with the app's own token, so a DM's copy changes anyone and a player's only their own character. On an older Runner scryboard.fight is undefined, so check for it and ask the user to update. Browser apps that run in the background don't have it yet. Read with scryboard.get('fight', { session_id }).

From a panel: await scryboard.fight.act(sessionId, action), with the viewer's own rights (the DM's copy changes anyone, a player's only their own character). Read with scryboard.subscribe('fight', { session_id }); a change made through the panel refreshes it at once.

Rolling dice

Ask Scryboard for a roll. Your app never talks to another app: Scryboard decides who rolls. No scope is needed, because a roll reads and changes nothing. To save a result to the fight, use fight.act.

POST /api/agent/dice
{ "notation": "1d20+4", "label": "Goblin: attack" }
{ "data": { "notation": "1d20+4", "total": 17, "modifier": 4,
  "dice": [ { "type": "d20", "value": 13 } ], "rolled_by": "scryboard" } }

notation is NdM, optionally plus or minus a number: up to 100 dice of up to 1000 sides, plus or minus up to 1000. Anything else gets a 400. Scryboard rolls for itself unless the DM has chosen a dice app for the campaign, so rolled_by is scryboard or app, and a roll can take a few seconds. dice_app_missed: true means a dice app was asked but Scryboard rolled instead. The app that rolled isn't named. label may go to that app, so keep it to a name and an action.

From an app: await scryboard.dice.roll('1d20+4', { label }), in a panel, a browser app or App Runner 0.2.17 or newer. On an older Runner scryboard.dice is undefined, so check for it and roll locally without it.

Being a dice app

Declare "provides": ["dice"] in scryboard.json (App Runner apps only). A DM can then choose your app on Your Apps, and you answer that campaign's rolls.

for (const r of await scryboard.dice.pending()) {   // also your check-in
  if (r.hidden && !canHide) { await scryboard.dice.decline(r.id); continue }
  if (!await scryboard.dice.claim(r.id)) continue    // false: too late, don't roll
  await scryboard.dice.answer(r.id, [13])            // one value per die
}
  • Export answerDice(scryboard, { secrets }) with this loop. App Runner 0.2.18 or newer calls it apart from tick(): straight away when a roll is waiting, without waiting behind other apps, and every 2.5 seconds during a live session while your app is the campaign's chosen one. Read your keys from secrets, never process.env, which may hold another app's keys at that moment. It can run alongside your tick(), so don't let them write the same file.
  • On a Runner without this, scryboard.dice.lane isn't set. Call your function from tick() instead.
  • pending() returns { id, notation, count, sides, modifier, label, hidden }. If you haven't checked in for 90 seconds, Scryboard stops asking and rolls for itself.
  • active() says whether your app is the campaign's chosen dice app.
  • Claim before you roll. A request must be claimed within 4 seconds, and answered within 12 after that. A late claim returns false: don't roll, because Scryboard already has.
  • hidden rolls must show only to the person who asked. All DM rolls are hidden. If you can't hide one, decline it, and Scryboard rolls instead.
  • Decline what you can't do, such as a die you don't have.
  • Scryboard checks each answer: one value per die, each in range. It adds the modifier itself.

Proposing events

DM-scope tokens with the events write scope can propose structured campaign events — an encounter fought, a scene played out, a notable spell cast, an XP award — for the campaign's permanent event record. This is the write half of the events read resource above: where extractions holds the campaign's lore as prose items, events hold its history as typed payloads with linked participants, queryable across types.

POST https://<your-scryboard-host>/api/agent/events
Authorization: Bearer scry_...
Content-Type: application/json
{
  "event_type": "encounter",
  "session_id": "<optional uuid>",
  "payload": { "outcome": "victory", "rounds": 3 },
  "participants": [
    { "participant_type": "member", "member_id": "...", "display_name": "Thugsley", "role": "pc" },
    { "participant_type": "name", "display_name": "Ghoul", "role": "monster", "detail": { "cr": "1" } }
  ]
}
  • DM-scope tokens only — events can describe DM-private material (an unrevealed monster's CR, an unconfirmed proposal's contents), so both the read and the write require DM scope. Declaring events in your manifest (under reads or writes) forces a DM to be the installer, same as extractions.
  • event_type — exactly one of encounter, scene, spell_cast, xp_award. This is a closed set: Scryboard's own internal event types (rules_lookup and friends) are pipeline records, not app-writable.
  • payload — a JSON object, up to 20KB. No fixed schema per type beyond the xp_award rule below — shape it for what you're recording.
  • participants — optional, up to 50, each { participant_type, member_id?, item_id?, display_name, role?, detail? }:
    • participant_type — member (a campaign member: member_id must be a member of this campaign — ids come from the members read resource), extraction_item (a canon entity: pass its item_id), or name (just a display name — how free-text combatants are recorded).
    • display_name — required, ≤80 chars, always present so the event stays renderable even if the linked record moves on.
    • role — optional, ≤40 chars (e.g. pc, monster, caster).
    • detail — optional JSON object, ≤2KB, for per-participant data like an XP amount.
  • Every proposal lands unconfirmed. However it's called, the write never bypasses review: the DM confirms it, rejects it, or amends the payload (the original stays visible as proposed_payload) on the Approval Queue page (/campaigns/{id}/events) — the same affirm-or-modify trust model as Proposing canon. There is no way for a token to confirm its own event.
  • xp_award events must cite their source: the payload must carry a source_event_id referencing a confirmed encounter or scene event in the same campaign — an award proposed against a still-pending encounter is rejected, so wait for the DM's review before proposing XP for it. Convention for the rest of the payload: total_xp, a per_character map, and per-recipient participants each carrying detail: { "xp": ... }.
  • Scryboard itself writes events through the same record: ending an encounter snapshots the combatants into an unconfirmed encounter event awaiting the same review, and DM-approved items from the post-session review land as already-confirmed scene events. Read those back via the events resource and build on them (an XP suggester citing a confirmed encounter, say) rather than re-deriving what happened yourself.
  • Client library: scryboard.writeEvent({ event_type, payload, session_id, participants }) and scryboard.getEvents(params) — both available to browser_sandboxed apps too.

Claude and voices through Scryboard

Declare a service under services in your manifest (see the manifest doc) and call it through the client library. Scryboard holds your keys (saved on your app's Marketplace page) and adds them on its server: your app never contains a key, buyers never need one, and what your app uses is billed to you.

Claude takes and returns exactly what Anthropic's Messages API does:

const msg = await scryboard.claude({
  model: 'claude-haiku-4-5',       // must be in your declared "models"
  max_tokens: 100,                 // at most your declared "max_output_tokens"
  system: 'You are a goblin heckler.',
  messages: [{ role: 'user', content: 'Insult the bard.' }],
})
const text = msg.content.filter((b) => b.type === 'text').map((b) => b.text).join('')
  • Supported fields: model, max_tokens, messages, system, temperature, top_p, top_k, stop_sequences, thinking, output_config, cache_control. No streaming or tools yet. Images and PDFs go inline as base64 blocks, up to about 4MB per request.
  • Available to browser_sandboxed apps too, within their 60-second tick.
  • Raw HTTP, or the Anthropic SDK pointed at Scryboard (baseURL: 'https://<your-scryboard-host>/api/agent/services/claude', your token as apiKey): POST /api/agent/services/claude/v1/messages.

Voices return MP3 bytes, ready for playAudio:

const { audio, uses } = await scryboard.speak({
  voice_id: '<a voice id from your declared "voices">',
  text: 'Your mother was a kobold.',  // at most your declared "max_characters"
  // optional: model_id ('eleven_multilingual_v2' default, 'eleven_turbo_v2_5',
  // 'eleven_flash_v2_5', 'eleven_v3'), voice_settings { stability,
  // similarity_boost, style, speed, use_speaker_boost }
})
await scryboard.playAudio(audio)
// uses: { used: 12, limit: 25, period: 'month', resetsAt: '2026-11-01T00:00:00.000Z' }
  • Each successful call is one use of the buyer's allowance; failed calls don't count. Show uses on your widget so the buyer knows where they stand.
  • Works in both runtimes. In a browser_sandboxed app audio is a Uint8Array (a Node Buffer is one too), and playAudio(audio) plays it on whatever device has the page open (declare plays_audio).
  • Raw HTTP: POST /api/agent/services/elevenlabs/tts with { voice_id, text, model_id?, voice_settings? }; the allowance comes back in X-Scryboard-Uses, -Uses-Limit, -Uses-Period and -Uses-Reset headers.

Errors are thrown with err.status and a sentence written for the buyer, so you can show err.message on your widget as it is:

Status Means
403 The service isn't declared in the installed version's manifest.
400 The request is outside what you declared (model, voice, length) or malformed. Anthropic's own detail is passed through for Claude.
429 The buyer's allowance is used up ("More on 1 November"; Claude requests are allowed at twice your allowance), the 10-a-minute limit was hit, or the provider is busy.
503 Your key for that service is missing, switched off, out of credit or rejected. The buyer is only told the service is unavailable; the reason shows in your App keys box.

Needs App Runner 0.2.9 or later. On an older Runner scryboard.claude is undefined, so check typeof scryboard.claude === 'function' and tell the buyer to update the Runner.

Remembering things

Your app's own small store, kept by Scryboard: which clicks you've handled, what you've generated, a list you build up. One store per installed app per campaign; a personal app gets one per campaign too. Values are any JSON.

const handled = (await scryboard.getState('handled')) ?? []   // null if never set
await scryboard.setState('handled', [...handled, click.id])
await scryboard.setState('draft', null)                       // deletes the key
const everything = await scryboard.getState()                  // { key: value, ... }
  • No scope to declare: it's your app's data about itself.

  • Limits: keys up to 100 characters, one value up to 64 KB, and 256 KB and 200 keys per app. Over a limit, setState fails with a plain message (HTTP 413) and nothing is saved.

  • Uninstalling clears it. Treat it as a cache you can rebuild, the same rule as a Runner app's files: never let a missing value replay work — or a charge — that already happened. Seed click cursors from getActions({ order: 'newest', limit: 1 }) when it's empty.

  • Save what changed, when it changed, rather than everything every tick.

  • Top-level variables in a browser app last between ticks, but only while the page stays open: your file is loaded once per page, then tick() is called again and again. A reload, a new tab or the app being re-enabled starts them fresh. Fine for a cache (say, the last layout you pushed, to skip identical pushes); anything that matters goes in setState.

  • Browser apps have it, and so does App Runner 0.2.19 and later. On an older Runner scryboard.getState is undefined and calling it throws, and a buyer may not have updated yet. A node_cli app should check typeof scryboard.getState === 'function' and otherwise use a state/ folder.

  • Where a node_cli app's state/ folder goes: next to your own code, found from your file, never from the working directory. The Runner runs every app inside its own process, so process.cwd() is the Runner's folder, shared by all apps:

    import { mkdir, readFile, writeFile } from 'node:fs/promises'
    const STATE_DIR = new URL('./state/', import.meta.url)   // beside agent.mjs
    await mkdir(STATE_DIR, { recursive: true })
    const file = new URL('memory.json', STATE_DIR)
    const memory = JSON.parse(await readFile(file, 'utf8').catch(() => '{}'))
    

    For a personal app that's inside the folder you pointed the Runner at; for a Marketplace install, inside the Runner's copy of the app. An update keeps state/, and a state/ folder inside your zip is never shipped, so a test file can't overwrite a buyer's.

  • Raw HTTP: GET /api/agent/state?key=… (or no key for everything), POST /api/agent/state with { "key": "…", "value": … }.

Showing a file you made

An App Runner app that writes files for the DM (an STL, a PDF, an export) can open File Explorer with one of them selected. The usual pattern is a "Show file" button on your card: on the click, call

await scryboard.showFile('flame-dagger.stl')   // a file in your output/ folder
  • App Runner 0.2.20 or later only. Check first with typeof scryboard.showFile === 'function' and tell the DM to use Open folder on the App Runner when it isn't there. Browser apps have no files, so it never exists there.
  • Only an existing file inside your own output/ folder (a leading output/ is accepted). Full paths, .., folders and links pointing elsewhere are refused.
  • At most once every 5 seconds per app; a call sooner answers { shown: false, reason: 'too_soon' }. Otherwise { shown: true, file }.
  • It opens a folder view on the computer running the App Runner. It never opens or runs the file, and nothing is uploaded.
  • Locally (agent-runtime) it prints the path instead.

Seeing what went wrong

Under each of your own apps on Your Apps (/agents), Recent problems lists what went wrong, newest first, with the campaign, when, and how many times:

  • Everything Scryboard refused, recorded automatically for every app: a card that was too big, a scope you didn't declare, a rate limit, a Claude allowance used up. You see the same sentence your app was sent.
  • A browser app's crashes and console.error lines, reported by the page running it. (console.log and console.error also print in that page's browser console, labelled with your app's name.)
  • A node_cli app's crashed tick(), reported by App Runner 0.2.15 and newer: the error's message only, the same one at most once a minute. dev-runner.mjs does the same, so you can try it against the mock.
  • Anything your app reports itself: scryboard.reportProblem(message, where?), for example reportProblem('Claude gave no names for Marta', 'claude'). It never throws; it resolves false if the report couldn't be sent. Browser apps have it; the App Runner doesn't yet, so a node_cli app should check typeof scryboard.reportProblem === 'function' first (dev-runner leaves it out too, unless --all-methods). The raw call is POST /api/agent/problems with { "message": "what went wrong", "where": "optional, e.g. tick" }, but a Runner app has no token to make it with: the Runner hands your tick() a client already bound to your app and does not set SCRY_TOKEN or SCRY_BASE_URL (those are only for running scryboard.mjs yourself, as dev-runner does). Until the Runner has reportProblem, throw from tick() to get a message listed.

Repeats are counted rather than listed again, and only the latest 50 per app per campaign are kept. Clear empties the list. The mock server accepts /api/agent/problems too and prints what it's sent.

A card Scryboard changed so it could show it (links as plain text, or trimmed to fit) is listed here too, and the push's reply says so: { "data": { "widget_id": "…", "output_id": "…" }, "warnings": ["…"] }, with warnings beside data. widget_id is the id a click names (the mock server takes it in POST /api/widget-action, see its README), and it stays the same for as long as you push that widget name. scryboard.pushWidget() returns data with the warnings array added to it (result.warnings), in both the Node and the browser client, and the Node client also prints them.

Publishing to the Marketplace

Every Marketplace submission ships a scryboard.json manifest next to your code — it declares your entry file, your runtime, the resources you read and write, any package dependencies, and any secrets a buyer needs to supply. Full field-by-field reference: the manifest doc. At submission time, Scryboard scans your code and checks it against what you declared — reading transcript without declaring it is a rejection, not a warning.

Pick a runtime before you write anything — see Choosing a runtime below.

Either way, a buyer's "install" only mints them a scoped token and hands their client (browser or the Runner) your code — it does not run your app by itself, and it has no separate placement setting of its own. Nothing shows up anywhere in their campaign until your tick() actually runs with that token.

Once it does run, where its widgets land is determined entirely by the placement value your own code passes to pushWidget (see Writing widgets above) — the marketplace has no way to override or configure this from outside your code, by design (app code runs on the buyer's own machine, not on Scryboard's servers).

Because of that, say where your widget(s) show up in your listing's setup instructions — "shows up in the live session dashboard," "appears on the DM's landing page," "lands on your own player landing page" — so a buyer knows what to expect before they run something you wrote. This is the same reasoning behind declaring your scopes on the manifest: buyers shouldn't have to read your source to know what they're installing.

Choosing a runtime

Every app declares one runtime in its manifest. Decide first: it fixes what your app can remember, call and install.

browser_sandboxed node_cli
Where it runs In the browser of whoever installed it, only while they have that campaign's page open. If the page is open in two tabs, the newest one runs it and the older one stops. On the buyer's computer, through the Scryboard App Runner — a desktop app (Windows only for now) the buyer installs once and leaves running.
Buyer setup None. Install is one click. Install the Runner once; after that, each app is one click.
How often tick() runs Every 5 seconds while a session is live, every 30 seconds otherwise. poll in the manifest is ignored. On the poll schedule in your manifest.
Code One file, no packages, no import. Any number of files, plus the vetted packages.
Network Scryboard's API only, through scryboard.*. Your code runs in a Web Worker inside a sandboxed frame with its own opaque origin: it can't see the buyer's cookies, storage or page, and the browser refuses any fetch, XHR or socket it tries. Anything — an LLM, an image service, another platform.
Long or stuck runs tick() never runs twice at once — the next tick waits for the last one to finish. A single tick that takes longer than 60 seconds, or code that fails to load, stops the app; Manage apps shows the reason ("Stopped: …") until the buyer disables and re-enables it, or reloads. Up to you and the Runner.
API keys (secrets) No. Yes — the Runner asks the buyer and keeps them in the system keychain.
Remembering things between ticks getState / setState: your app's own small store, kept by Scryboard between page loads. Files in a state/ folder next to your code, found from import.meta.url, not the working directory (how), or getState / setState on App Runner 0.2.19 and later. Either way, treat it as a cache you can rebuild: an update or reinstall can lose it, so never let a missing value replay work — or a charge — that already happened.
Settings boxes (settings) All of it, including per-item boxes (setSettingItems). All of it, including per-item boxes.
Writes Everything in this document: widgets, character data, events, media uploads (pass bytes as a Uint8Array), proposed canon, canon import and item attributes. Everything in this document.
Claude and voices (services) Yes, both. Yes, both.
Sound (plays_audio) Plays on whatever device has the page open: phone, tablet or computer. Browsers only allow sound after someone has tapped the page once, so a sound started by a button click always works; one started on its own before anyone tapped fails with a plain message you can show. Pass bytes, not file paths. Through the App Runner's player, on the Runner's computer.

You can use browser_sandboxed if all of these are true:

  1. Everything your app needs is in Scryboard or reachable through it (no outside service of its own, no buyer API key, no package).
  2. What it needs to remember fits in its own store (256 KB).
  3. It's fine that it only runs while someone has the campaign page open (or, for a DM's app, the live session screen).

A browser app works on phones, iPads and Macs as well as Windows; a node_cli app needs a Windows PC running the App Runner.

Otherwise, build node_cli. The common reasons are a service of your own (another platform's API, an image generator), a package, or a key the buyer has to supply. Remembering things is not one: a browser app keeps a roster or its handled clicks in its own store.

Before reaching for an outside service at all, check whether Scryboard already has the answer: "the NPCs", "the locations" and "what happened" are already in extractions, intelligence.new_canon and events — see Response shapes.

Example: minimal app loop

This is the plain-REST pattern — you own the polling loop, you manage the token yourself. It's how the example apps on the Downloads list work, and it's a fine way to self-host an app outside the Marketplace entirely. If you're publishing a browser_sandboxed or node_cli app, skip setInterval and the token: export an async tick(scryboard) function instead, and the runner (or the buyer's browser) drives the loop and handles the token for you — see the tick convention.

const BASE = 'https://scryboard.vercel.app'
const H = { Authorization: `Bearer ${process.env.SCRY_TOKEN}` }

async function tick() {
  const sessions = (await (await fetch(`${BASE}/api/agent/sessions`, { headers: H })).json()).data
  const live = sessions.find((s) => s.status === 'active')
  if (!live) return

  const lookups = (await (await fetch(
    `${BASE}/api/agent/rules_lookups?session_id=${live.id}`, { headers: H }
  )).json()).data

  const counts = {}
  for (const l of lookups) counts[l.name] = (counts[l.name] ?? 0) + 1

  await fetch(`${BASE}/api/agent/widgets`, {
    method: 'POST',
    headers: { ...H, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      widget: 'Spell usage',
      placement: 'session_dashboard', // watched live, during the session — set explicitly, don't rely on the default
      session_id: live.id,
      layout: {
        type: 'table',
        columns: ['Rule / Spell', 'Times surfaced'],
        rows: Object.entries(counts).sort((a, b) => b[1] - a[1]),
      },
    }),
  })
}

setInterval(tick, 15000)