API pipeline: Draw boards, keep docs and sheets

Index: API pipelines — index

Goal: draw a board (a free canvas, or cards laid out on a canvas) and keep doc and sheet cards whose body you store yourself.

Boards, docs and sheets are cards with a title, text and a scene: the body as one string, saved with a revision number. Docs and sheets take the same calls as boards; paths below say boards, use docs or sheets for those.

Steps

1. Create.

POST /v0/my/boards
Idempotency-Key: board-2b7c…
{"title": "Shop floor plan", "kind": "flow", "content": "Where each service sits.",
 "language": "en", "project": "470000000000000001"}
→ {"nonce": "470000000000000060", "card_type": "board", "kind": "flow", "visibility": "Private", "scene_rev": 0, …}

• Only title is required. Boards take kind: excalidraw (default, free drawing) or flow (cards on a canvas). Docs and sheets have no kind.
• Same optional fields as an article: content, language, handle, project, workspaces, rubrics, location, translate_mode, translate_langs. API pipeline: Write articles and posts

2. Save the scene.

PUT /v0/my/boards/470000000000000060/scene
{"scene": "{\"nodes\":[{\"id\":\"n1\",\"type\":\"card\",\"position\":{\"x\":0,\"y\":0},\"data\":{\"card_type\":\"project\",\"nonce\":\"470000000000000001\"}}],\"edges\":[]}",
 "revision": 0}
→ {"scene_rev": 1}

• revision must equal the current scene_rev (from the last read or save); the answer is the new one. A stale revision: 400 stale revision: submitted 0, current 1 — read the card, merge, retry.
• excalidraw: the scene is an Excalidraw scene JSON. flow: {"nodes": […], "edges": […]}; a node {"type": "card", "data": {"card_type": "…", "nonce": "…"}} places a card on the canvas.
• Docs and sheets: the scene is any string you choose (your own format).
• Anyone with write on the card may save the scene.

3. Read. GET /v0/my/boards/{nonce|@handle} → the card with scene and scene_rev. Public: GET /v0/graph/boards, GET /v0/graph/boards/{nonce} (also /v0/graph/docs, /v0/graph/sheets). Yours: GET /v0/my/boards (scope, archived as for articles).

4. Edit, share, delete. PATCH /v0/my/boards/{nonce} (title, content, visibility, project, rubrics, …; same rules as articles); archive with POST /v0/my/archive; DELETE /v0/my/boards/{nonce}.

Behind

• A flow board's card nodes count as mentions: after a save those cards come back in the board's mentioned.

Rules (400)

• title is required; kind must be excalidraw|flow, got ….
• stale revision: submitted <n>, current <m>.
• Visibility, project and rubric rules as for articles. A card you cannot write: 404.

API surface