Create a new canvas from mermaid text or an excalidraw scene JSON. Returns the stored record, including the minted stable id and, for mermaid, the diagram family derived from the source.
formatany of
Diagram format: `mermaid` or `freeform`. Defaults to `mermaid`.
any of (2)
variant 1
one of (2)
variant 1
valuestringenum: mermaid
variant 2
valuestringenum: freeform
namestring
Human-readable canvas name. Omit for a name derived from the detected diagram family (`Untitled flowchart`, `Untitled whiteboard`, …).
sourcestring*required
The editable source: mermaid text for `mermaid`, an excalidraw scene JSON string for `freeform`.
created_atinteger· int64*required
Creation time, unix seconds.
familystring
Mermaid diagram family (`flowchart`, `sequenceDiagram`, …), derived from the source. `null` for a freeform canvas.
formatall of*required
Diagram format: `mermaid` or `freeform`.
all of (1)
variant 1
one of (2)
variant 1
valuestringenum: mermaid
variant 2
valuestringenum: freeform
idstring*required
Stable 8-character slug identifying this canvas. Never changes across updates.
namestring*required
Human-readable canvas name.
sourcestring*required
The editable source of truth: mermaid text for `mermaid`, the excalidraw scene JSON for `freeform`.
updated_atinteger· int64*required
Last update time, unix seconds.
Delete a stored canvas by its stable 8-character id. Deleting an unknown id is not an error: the response reports deleted=false instead.
idstring*required
Stable 8-character canvas id.
deletedboolean*required
`true` when a record existed and was removed; `false` for an unknown id.
idstring*required
The id the call asked to delete.
canvas::element::add
functionAdd elements to a freeform canvas, one call per drawing step. Each element is an excalidraw-style object ({type, x, y, width?, height?, text?, label?, start?, end?, ...}); skeleton shorthand is accepted and converted at render time. Elements without an id get a stable generated one. The open console canvas streams every call, so shapes appear as they are added. Returns the assigned ids and the new element count.
elementsunknown[]*required
Elements to append, in z-order. Objects with at least a `type` string; unknown fields pass through to the scene untouched.
idstring*required
Stable 8-character canvas id (format must be freeform).
element_countinteger· uint*requiredmin 0
Total elements in the scene after the add.
element_idsstring[]*required
Assigned element ids, in the order the elements were given.
idstring*required
The canvas the elements were added to.
canvas::element::delete
functionRemove elements from a freeform canvas by element id. Unknown ids are ignored; the response reports how many were actually removed. The open console canvas streams the change live.
element_idsstring[]*required
Element ids to remove.
idstring*required
Stable 8-character canvas id (format must be freeform).
element_countinteger· uint*requiredmin 0
Total elements left in the scene.
removedinteger· uint*requiredmin 0
How many of the given ids existed and were removed.
canvas::element::list
functionList the elements of a freeform canvas: id, type, position and size per element — the map an agent reads before updating or connecting shapes. Full element bodies are in the record source via canvas::get.
idstring*required
Stable 8-character canvas id (format must be freeform).
elementsobject[]*required
textstring
The element's own `text`, or its `label.text` shorthand.
typestring*required
Element type (`rectangle`, `ellipse`, `arrow`, `text`, ...).
canvas::element::update
functionMerge properties into one element of a freeform canvas by element id (move it, recolor it, change its text). Unknown ids error and name the canvas. The open console canvas streams the change live.
element_idstring*required
Element id to update (from element::add or element::list).
idstring*required
Stable 8-character canvas id (format must be freeform).
propsobject*required
Properties to merge into the element. `null` values remove the key.
elementunknown*required
The element after the merge.
element_idstring*required
Read one canvas by its stable 8-character id. Returns the full stored record, including the editable source. Errors when the id is unknown.
idstring*required
Stable 8-character canvas id, as returned by `canvas::create` and `canvas::list`.
created_atinteger· int64*required
Creation time, unix seconds.
familystring
Mermaid diagram family (`flowchart`, `sequenceDiagram`, …), derived from the source. `null` for a freeform canvas.
formatall of*required
Diagram format: `mermaid` or `freeform`.
all of (1)
variant 1
one of (2)
variant 1
valuestringenum: mermaid
variant 2
valuestringenum: freeform
idstring*required
Stable 8-character slug identifying this canvas. Never changes across updates.
namestring*required
Human-readable canvas name.
sourcestring*required
The editable source of truth: mermaid text for `mermaid`, the excalidraw scene JSON for `freeform`.
updated_atinteger· int64*required
Last update time, unix seconds.
List stored canvases, newest first, optionally filtered by format. Each entry is the full record including its source; the response is capped by the configured max_list.
formatany of
Only return canvases of this format. Omit for every canvas.
any of (2)
variant 1
one of (2)
variant 1
valuestringenum: mermaid
variant 2
valuestringenum: freeform
canvasesobject[]*required
The stored records, newest first.
created_atinteger· int64*required
Creation time, unix seconds.
familystring
Mermaid diagram family (`flowchart`, `sequenceDiagram`, …), derived from the source. `null` for a freeform canvas.
formatall of*required
Diagram format: `mermaid` or `freeform`.
all of (1)
variant 1
one of (2)
variant 1
valuestringenum: mermaid
variant 2
valuestringenum: freeform
idstring*required
Stable 8-character slug identifying this canvas. Never changes across updates.
namestring*required
Human-readable canvas name.
sourcestring*required
The editable source of truth: mermaid text for `mermaid`, the excalidraw scene JSON for `freeform`.
updated_atinteger· int64*required
Last update time, unix seconds.
countinteger· uint*requiredmin 0
How many records this response carries.
canvas::on-config-change
functionInternal: hot-reload the canvas worker from the authoritative configuration when it changes, swapping the per-call snapshot.
idstring
Configuration id that changed (advisory; the handler re-fetches).
Return the mermaid syntax reference: every supported diagram family with a short summary and a working example, or — narrowed to one family — a compact syntax primer. Call this before writing mermaid source.
familystring
Diagram family to return (`flowchart`, `sequenceDiagram`, …; aliases like `graph` accepted); omit for the overview of every family.
familiesobject[]*required
The reference entries — every family for the overview, exactly one when the request named a family.
examplestring*required
A minimal, valid mermaid example of this family.
familystring*required
Canonical family name (`flowchart`, `sequenceDiagram`, …) — the same string `canvas::validate` reports and `canvas::create` stores.
summarystring*required
One-line description of what this family is for.
syntaxstring*required
The reference as readable text: one line per family for the overview, or the named family's syntax primer with its example.
canvas::ui-content
functionServe the canvas worker's injected console UI assets (content function for its console:script / console:style triggers).
pathstring*required
The asset path from the trigger config (e.g. `state/page.js`).
contentstring*required
The asset source, verbatim.
content_typestring*required
MIME type the console should serve the asset with.
Update a stored canvas's name and/or source by id. The id never changes; updated_at is stamped and, for mermaid, the diagram family is re-derived from the new source. Returns the full updated record.
idstring*required
Stable 8-character canvas id.
namestring
New canvas name. Omit to keep the current one.
sourcestring
New source (mermaid text or excalidraw scene JSON, matching the canvas's format). Omit to keep the current one.
created_atinteger· int64*required
Creation time, unix seconds.
familystring
Mermaid diagram family (`flowchart`, `sequenceDiagram`, …), derived from the source. `null` for a freeform canvas.
formatall of*required
Diagram format: `mermaid` or `freeform`.
all of (1)
variant 1
one of (2)
variant 1
valuestringenum: mermaid
variant 2
valuestringenum: freeform
idstring*required
Stable 8-character slug identifying this canvas. Never changes across updates.
namestring*required
Human-readable canvas name.
sourcestring*required
The editable source of truth: mermaid text for `mermaid`, the excalidraw scene JSON for `freeform`.
updated_atinteger· int64*required
Last update time, unix seconds.
Validate canvas source without storing it: detect the mermaid diagram family, check the size cap, balanced fences and per-family lints, or check an excalidraw scene JSON's shape. A cheap pre-flight — full parsing happens at render time in the console.
formatany of
Source format, `mermaid` or `freeform`; omit to auto-detect (a source starting with `{` is an excalidraw scene, anything else mermaid).
any of (2)
variant 1
one of (2)
variant 1
valuestringenum: mermaid
variant 2
valuestringenum: freeform
sourcestring*required
The source to validate: mermaid text, or an excalidraw scene JSON string.
familystring
The mermaid diagram family derived from the source (`flowchart`, `sequenceDiagram`, …). `null` for freeform or when the first meaningful line names no supported family.
issuesobject[]*required
Every issue found; empty when `valid` is `true`.
lineinteger· uint32min 0
1-indexed source line the issue points at, when known.
messagestring*required
Human-readable description of the issue.
validboolean*required
`true` when every cheap check passed. This is a pre-flight verdict, not a render guarantee — full parsing happens in the console.
