.canvas.json file. It holds cards, references to pages, web links, and groups, joined by labeled edges. Use a canvas to map a system, plan a project, or lay out how a set of pages relate.
Canvas files follow the open JSON Canvas 1.0 format used by Obsidian, so you can move them between tools. They are ordinary files: every save goes through the write pipeline, gets a git commit, and broadcasts a write event.
File format
The document has two top-level arrays,nodes and edges. Both are required.
canvases/auth-flow.canvas.json
Every node has
id, type, x, y, width, and height. color is optional: a preset "1" through "6" (red, orange, yellow, green, cyan, purple) or a hex value. Edges use fromNode and toNode, plus optional fromSide, toSide (top, right, bottom, left), label, and color. The API checks only that nodes and edges are arrays and keeps any extra fields you add. Saving from the web UI editor keeps only the fields listed here.
Web UI
1
Open the canvas hub
Click Canvas in the toolbar. The hub lists every
.canvas.json file and reopens the last one you used.2
Create or pick a canvas
Click New canvas and enter a name. KiwiFS creates
canvases/{name}.canvas.json. Use the dropdown to switch canvases.3
Edit
Use Add to place a text card, link card, or group, or double-click empty space. Drag a page from the file tree onto the canvas to add a file card. Paste a URL to add a link card. Drag between node handles to connect them.
Ctrl+S (Cmd+S on macOS). Other shortcuts: Ctrl+Z to undo, Ctrl+Shift+Z to redo, Ctrl+A to select all, and Delete or Backspace to remove the selection. Right-click a node to change its color. Auto-layout in the canvas toolbar tidies node positions.
Opening a .canvas.json file from the file tree opens it in the canvas editor. To show a canvas inside a page, embed it with ![[canvases/auth-flow.canvas.json]].
Build canvases with the API
Generate a canvas from the link graph
Generate a canvas from the link graph
POST /api/kiwi/canvas/generate creates a canvas with one file node per page and one edge per wiki link. Choose a layout of hierarchical (default), radial, force, or circular. Set folder to a path prefix to limit the graph. Nodes are colored by link community unless you pass "colorize": false.Terminal
Patch nodes and edges
Patch nodes and edges
PATCH /api/kiwi/canvas?path=... applies a batch of add_node, update_node, remove_node, add_edge, update_edge, and remove_edge operations as one commit, so agents never rewrite the whole document. Patching a missing file starts from an empty canvas.Terminal
Query a canvas
Query a canvas
GET /api/kiwi/canvas/query filters nodes by type, substring q, or nodes connected to a given node ID, without loading the whole document.Auto-layout an existing canvas
Auto-layout an existing canvas
POST /api/kiwi/canvas/auto-layout?path=... repositions nodes with a Graphviz engine: dot (default), neato, fdp, or circo. Only x and y change.kiwi_canvas_list, kiwi_canvas_read, and kiwi_canvas_write.
Canvas or whiteboard
Related
Canvas REST API
List, read, write, patch, query, generate, and auto-layout.
Whiteboard
Excalidraw drawings stored as markdown.
Wiki links
The link graph that canvas generation reads.
Web UI
Toolbar views, including Canvas and Whiteboard.