Canvas

List, read, write, patch, query, lay out, and generate JSON Canvas files.

Canvases are JSON Canvas documents stored as .canvas.json files in the knowledge base. Every write goes through the normal write pipeline, so each change is a git commit and broadcasts an SSE event. See Canvas for the data model.

Every endpoint that takes a path rejects paths that don’t end in .canvas.json with 400.

List canvases

Return every .canvas.json file in the knowledge base.

GET /api/kiwi/canvases

curl 'http://localhost:3333/api/kiwi/canvases'

canvases · array

One entry per canvas file. Empty array when there are none.

Show properties

path · string

Path relative to the knowledge root.

name · string

File name without the .canvas.json suffix.

{
  "canvases": [
    { "path": "maps/site.canvas.json", "name": "site" },
    { "path": "research/ideas.canvas.json", "name": "ideas" }
  ]
}

Read a canvas

Return the raw canvas document.

GET /api/kiwi/canvas

path · string · required

Canvas file path.

curl 'http://localhost:3333/api/kiwi/canvas?path=maps/site.canvas.json'

Returns the stored JSON as-is with Content-Type: application/json. Returns 404 if the file does not exist and 500 if it is not a valid canvas.

{
  "nodes": [
    { "id": "n1", "type": "file", "file": "concepts/auth.md", "x": 0, "y": 0, "width": 400, "height": 300 },
    { "id": "n2", "type": "text", "text": "Open questions", "x": 480, "y": 0, "width": 240, "height": 120 }
  ],
  "edges": [
    { "id": "e1", "fromNode": "n1", "toNode": "n2", "label": "see" }
  ]
}

Write a canvas

Create or replace a canvas. The body is the full JSON Canvas document.

PUT /api/kiwi/canvas

path · string · required

Canvas file path.

X-Actor · string · default: "system"

Git commit author attribution.

nodes · object[] · required

JSON Canvas nodes. An empty array is allowed.

edges · object[] · required

JSON Canvas edges. An empty array is allowed.

curl -X PUT 'http://localhost:3333/api/kiwi/canvas?path=maps/site.canvas.json' \
  -H "Content-Type: application/json" \
  -H "X-Actor: agent:mapper" \
  -d '{"nodes":[{"id":"n1","type":"file","file":"concepts/auth.md","x":0,"y":0,"width":400,"height":300}],"edges":[]}'

Returns 400 if the body is not JSON with nodes and edges arrays.

path · string

Canvas path that was written.

etag · string

Git blob hash of the new content.

{ "path": "maps/site.canvas.json", "etag": "3f2a9c1e8b7d6a5f4e3d2c1b0a9f8e7d6c5b4a39" }

Patch a canvas

Apply a batch of node and edge operations without sending the whole document. The batch is atomic: if any operation fails, nothing is written. If the canvas does not exist yet, the operations apply to an empty canvas.

PATCH /api/kiwi/canvas

path · string · required

Canvas file path.

X-Actor · string · default: "system"

Git commit author attribution.

operations · object[] · required

Operations, applied in order. Must not be empty.

Show properties

op · string · required

One of add_node, update_node, remove_node, add_edge, update_edge, remove_edge.

id · string

Target ID for update_* and remove_*. For update_* you can omit it and put id inside node or edge instead.

node · object

Full node for add_node, or the fields to merge for update_node.

edge · object

Full edge for add_edge, or the fields to merge for update_edge.

curl -X PATCH 'http://localhost:3333/api/kiwi/canvas?path=maps/site.canvas.json' \
  -H "Content-Type: application/json" \
  -d '{
    "operations": [
      { "op": "add_node", "node": { "id": "n3", "type": "file", "file": "concepts/oauth.md", "x": 0, "y": 400, "width": 400, "height": 300 } },
      { "op": "update_node", "id": "n1", "node": { "x": 120 } },
      { "op": "add_edge", "edge": { "id": "e2", "fromNode": "n1", "toNode": "n3", "label": "depends on" } },
      { "op": "remove_node", "id": "n2" }
    ]
  }'

Returns 400 for an unparseable body or an empty operations array, and 422 when an operation is invalid (unknown op, duplicate ID on add, or unknown ID on update or remove). Removing a node also removes every edge connected to it.

path · string

Canvas path.

etag · string

Git blob hash of the new content.

applied · object

Counts of what changed.

Show properties

nodes_added · integer

Nodes inserted.

nodes_updated · integer

Nodes merged in place.

nodes_removed · integer

Nodes deleted.

edges_added · integer

Edges inserted.

edges_updated · integer

Edges merged in place.

edges_removed · integer

Edges deleted, including edges removed with a node.

{
  "path": "maps/site.canvas.json",
  "etag": "9b8a7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0b",
  "applied": {
    "nodes_added": 1,
    "nodes_updated": 1,
    "nodes_removed": 1,
    "edges_added": 1,
    "edges_updated": 0,
    "edges_removed": 1
  }
}

Delete a canvas

Delete a canvas file and record the deletion as a git commit.

DELETE /api/kiwi/canvas

path · string · required

Canvas file path.

X-Actor · string · default: "system"

Git commit author attribution.

curl -X DELETE 'http://localhost:3333/api/kiwi/canvas?path=maps/site.canvas.json'

Returns 404 if the canvas does not exist.

deleted · string

Path that was deleted.

{ "deleted": "maps/site.canvas.json" }

Query canvas nodes

Filter the nodes and edges of one canvas.

GET /api/kiwi/canvas/query

path · string · required

Canvas file path.

q · string

Case-insensitive substring match against a node’s id, text, file, and url, and an edge’s id and label. Edges touching a matched node are also returned.

type · string

Node type: text, file, link, or group.

connected · string

Node ID. Returns that node and every edge whose fromNode or toNode is that ID.

nodes_only · boolean · default: "false"

Omit edges from the result.

edges_only · boolean · default: "false"

Omit nodes from the result.

curl 'http://localhost:3333/api/kiwi/canvas/query?path=maps/site.canvas.json&connected=n1'

Returns 404 if the canvas does not exist.

nodes · object[]

Matching JSON Canvas nodes.

edges · object[]

Matching JSON Canvas edges.

{
  "nodes": [
    { "id": "n1", "type": "file", "file": "concepts/auth.md", "x": 120, "y": 0, "width": 400, "height": 300 }
  ],
  "edges": [
    { "id": "e2", "fromNode": "n1", "toNode": "n3", "label": "depends on" }
  ]
}

Auto-layout a canvas

Reposition the existing nodes of a canvas with a Graphviz layout engine and save the result. This does not add nodes; use generate to build a canvas from wiki links.

POST /api/kiwi/canvas/auto-layout

path · string · required

Canvas file to lay out in place.

X-Actor · string · default: "system"

Git commit author attribution.

layout · string · default: "dot"

Graphviz engine: dot, neato, fdp, or circo. The body is optional.

curl -X POST 'http://localhost:3333/api/kiwi/canvas/auto-layout?path=maps/site.canvas.json' \
  -H "Content-Type: application/json" \
  -d '{"layout": "neato"}'

Returns 404 if the canvas does not exist.

path · string

Canvas path.

etag · string

Git blob hash of the new content.

node_count · integer

Nodes in the canvas.

edge_count · integer

Edges in the canvas.

{ "path": "maps/site.canvas.json", "etag": "c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5", "node_count": 2, "edge_count": 1 }

Generate a canvas from the link graph

Build a canvas with one file node per page and one edge per wiki link, lay it out, and write it to disk. Existing content at the output path is replaced.

POST /api/kiwi/canvas/generate

X-Actor · string · default: "system"

Git commit author attribution.

path · string · default: "canvas.canvas.json"

Output file. .canvas.json is appended if missing.

layout · string · default: "hierarchical"

hierarchical, radial, force, or circular. Unknown values fall back to hierarchical.

folder · string

Path prefix. Only links whose source and target both start with this prefix become edges.

colorize · boolean · default: "true"

Color nodes by detected link community.

curl -X POST 'http://localhost:3333/api/kiwi/canvas/generate' \
  -H "Content-Type: application/json" \
  -d '{"path": "maps/concepts", "layout": "radial", "folder": "concepts/"}'

Returns 503 if the link index is unavailable.

path · string

Canvas path that was written.

etag · string

Git blob hash of the new content.

node_count · integer

Nodes generated.

edge_count · integer

Edges generated.

{ "path": "maps/concepts.canvas.json", "etag": "0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b", "node_count": 42, "edge_count": 97 }

MCP equivalents

MCP exposes kiwi_canvas_list, kiwi_canvas_read, and kiwi_canvas_write. Patch, query, auto-layout, and generate are REST-only.

Related

Canvas concepts

Node types, edges, and how canvases render in the web UI.

MCP tools

The full list of MCP tools, including the canvas tools.