Create Board
create_boardCreate a fresh board in ONE call — optionally pre-filled with content, auto-laid-out, and/or PIN-locked at create time. Mirrors the extended POST /api/boards REST body exactly (same server-side implementation). With no arguments it returns a blank draw board; mode: 'todo' (+ optional template) seeds a kanban board. content imports initial items atomically: everything is validated FIRST and the board is created only if every item passes — on any invalid item you get a structured error naming its kind + index and NOTHING is created. autolayout: true (draw mode) fills in x/y for texts/images that omit them (deterministic masonry grid; explicit coordinates are never touched). lock: 'write'|'all' locks the board atomically with creation and returns the plaintext access_key ONCE — there is no recovery. The response's imported counts confirm what was created, ids returns the server-minted item ids per kind in the order you supplied them (index i of ids.texts is the id created for content.texts[i]; ids.columns is empty when the columns came from the template seed, and lanes have no id — they are keyed by board + lane index), and embed_url (the ?embed=1#<id> iframe view) is returned for any board readable without a key — it is omitted for lock:'all' boards, whose embed frame can't read the board anonymously. Prefer this over open_board + N per-item calls when you are building a whole board from scratch.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "create_board"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| lock | No | PIN-lock the board atomically at create time; the plaintext key is returned ONCE as `access_key`. | |
| mode | No | Board mode. Defaults to 'draw'. | |
| name | No | Optional shared board name (max 100 chars, whitespace collapsed); change later with `rename_board`. | |
| author | No | Author tag stamped on every created item (e.g. 'ai:plai'). Defaults to 'ai:import'. | |
| content | No | Initial board content, applied atomically at create time. Draw mode: `texts` [{x?, y?, content, color?, width?, postit?, diagram?, kind?, author?, sourceId?}], `lines` [{points, color?, anchors?, author?}] (alias `strokes`), `images` [{x?, y?, dataUrl, width, height, author?, sourceId?}]. Todo mode: `columns` [{title, lane?, color?, author?}] (array order = sort order), `tasks` [{columnIndex, name, description?, due_date?, priority?, assignee?, done?, color?, author?}] (columnIndex indexes into content.columns, or into the template-seeded columns when content.columns is empty), `lanes` [{lane, title, author?}], `colWidth`. Every item's optional `author` is its CREATOR tag (same 1-80 char [A-Za-z0-9:_-.] rule as elsewhere) and is never rewritten later — omit it to inherit the top-level `author`, or set it per item to preserve the original authorship when restoring somebody else's board. Item ids are ALWAYS minted server-side and returned in `ids`; you cannot choose them. To keep anchored strokes, give a text/image an optional `sourceId` (unique string, <=128 chars, write-only — never stored, never the row id) and reference it from `lines[].anchors.start.id` / `.end.id`: matching ids are rewritten to the minted id, unmatched ids are left as-is and render as a free stroke end. Kanban structures with a non-todo mode (or draw items with mode 'todo') are rejected with `content_mode_mismatch`. The combined input arrays may contain at most 2550 entries. At most 10 lane-title entries are accepted, every title must reference a lane used by a created column, and each lane index may be named AT MOST ONCE — a second entry for the same lane is rejected (naming that second entry's index) instead of collapsing last-write-wins, which would overwrite the first entry's author. `tasks[].done` must be a real boolean (or omitted/null for not-done): a truthy stand-in such as the string "false" is rejected rather than coerced, so a card is never imported as completed by accident. Standard per-board quotas also apply, and the 5 MB request-body cap is the real ceiling for image-heavy imports. A valid X-Import-Token selects higher REST/MCP and board-create rate tiers, but never changes these content limits. | |
| template | No | Starter column set when mode is 'todo' and content.columns is empty/absent. Defaults to 'kanban'. | |
| autolayout | No | Draw mode only: fill x/y for texts/images that omit them (deterministic masonry). Without it, items missing coordinates are rejected. No-op in todo mode. |