> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kiwifs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Canvas files

> JSON Canvas diagrams of cards, pages, links, and groups that you edit in the web UI or build from the wiki link graph.

A canvas is a spatial diagram stored as a **`.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](https://jsoncanvas.org) 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.

```json canvases/auth-flow.canvas.json theme={null}
{
  "nodes": [
    { "id": "n1", "type": "text", "x": 0, "y": 0, "width": 260, "height": 120,
      "text": "## Login\nUser submits credentials" },
    { "id": "n2", "type": "file", "x": 360, "y": 0, "width": 260, "height": 120,
      "file": "concepts/auth.md", "color": "4" },
    { "id": "n3", "type": "link", "x": 360, "y": 200, "width": 260, "height": 80,
      "url": "https://datatracker.ietf.org/doc/html/rfc6749" },
    { "id": "g1", "type": "group", "x": -40, "y": -60, "width": 700, "height": 380,
      "text": "Auth" }
  ],
  "edges": [
    { "id": "e1", "fromNode": "n1", "toNode": "n2", "fromSide": "right", "toSide": "left",
      "label": "validates with" }
  ]
}
```

| Node `type` | Content field | Renders as |
| - | - | - |
| `text` | `text` (markdown) | An editable card |
| `file` | `file` (path in the knowledge base) | A card that opens the page |
| `link` | `url` | A card for an external URL |
| `group` | `text` (title) | A region that visually groups other nodes |

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.

Changes save automatically about 1.5 seconds after you stop editing. You can also press `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

> [accordion] 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](https://docs.kiwifs.com/concepts/wiki-links.md). 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`.
>
> ```bash Terminal theme={null}
> curl -X POST 'http://localhost:3333/api/kiwi/canvas/generate' \
>   -H 'Content-Type: application/json' \
>   -d '{"path": "canvases/concepts-map.canvas.json", "layout": "radial", "folder": "concepts/"}'
> ```

> [accordion] 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.
>
> ```bash Terminal theme={null}
> curl -X PATCH 'http://localhost:3333/api/kiwi/canvas?path=canvases/auth-flow.canvas.json' \
>   -H 'Content-Type: application/json' \
>   -H 'X-Actor: agent:architect' \
>   -d '{"operations": [
>     {"op": "add_node", "node": {"id": "n4", "type": "text", "x": 0, "y": 200, "width": 260, "height": 80, "text": "MFA challenge"}},
>     {"op": "add_edge", "edge": {"id": "e2", "fromNode": "n1", "toNode": "n4"}}
>   ]}'
> ```

> [accordion] 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.

> [accordion] 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.

Agents connected over MCP use `kiwi_canvas_list`, `kiwi_canvas_read`, and `kiwi_canvas_write`.

## Canvas or whiteboard

| | Canvas | [Whiteboard](https://docs.kiwifs.com/concepts/whiteboard.md) |
| - | - | - |
| File | `.canvas.json` | `.excalidraw.md` |
| Content | Structured cards, page references, and edges | Freeform shapes, arrows, and sketches |
| Agent-friendly | Yes: typed nodes, patch and query endpoints | Read and write as a markdown file |
| Best for | Concept maps, architecture, link-graph views | Brainstorming and hand-drawn diagrams |

## Related

> [card] [Canvas REST API](https://docs.kiwifs.com/api/canvas.md)
>
> List, read, write, patch, query, generate, and auto-layout.

> [card] [Whiteboard](https://docs.kiwifs.com/concepts/whiteboard.md)
>
> Excalidraw drawings stored as markdown.

> [card] [Wiki links](https://docs.kiwifs.com/concepts/wiki-links.md)
>
> The link graph that canvas generation reads.

> [card] [Web UI](https://docs.kiwifs.com/guides/web-ui.md)
>
> Toolbar views, including Canvas and Whiteboard.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.