Skip to main content
Base path: http://localhost:3333/api/kiwi. Canvas paths must end with .canvas.json.

​
List canvases

GET /canvases

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

​
Read canvas

GET /canvas?path=maps/site.canvas.json
Returns the raw JSON document with Content-Type: application/json.

​
Write canvas

PUT /canvas?path=maps/site.canvas.json
Content-Type: application/json
Body must parse as JSON with nodes and edges arrays (empty arrays are allowed). Invalid JSON returns 400.

​
Patch canvas

Apply a batch of atomic operations without replacing the full document. If any operation fails, the whole batch is rejected. 
PATCH /canvas?path=maps/site.canvas.json
Content-Type: application/json

{
  "operations": [
    { "op": "add_node", "node": { "id": "n1", "type": "file", "x": 0, "y": 0, "data": { "path": "concepts/auth.md" } } },
    { "op": "update_node", "id": "n1", "node": { "x": 120 } },
    { "op": "remove_node", "id": "n2" },
    { "op": "add_edge", "edge": { "id": "e1", "fromNode": "n1", "toNode": "n3" } },
    { "op": "update_edge", "id": "e1", "edge": { "label": "depends on" } },
    { "op": "remove_edge", "id": "e1" }
  ]
}
Supported op values: add_node, update_node, remove_node, add_edge, update_edge, remove_edge.
​
nodes_added
integer
Nodes inserted.
​
nodes_updated
integer
Nodes merged in place.
​
nodes_removed
integer
Nodes deleted (connected edges removed too).
​
edges_added
integer
Edges inserted.
​
edges_updated
integer
Edges merged in place.
​
edges_removed
integer
Edges deleted.

​
Delete canvas

DELETE /canvas?path=maps/site.canvas.json

​
Query canvas nodes

GET /canvas/query?path=maps/site.canvas.json&q=auth&type=file&connected=n1&nodes_only=true
​
path
string
required
Canvas file path.
​
q
string
Filter nodes by label or metadata text.
​
type
string
Filter by node type.
​
connected
string
Return nodes connected to the given node ID.
​
nodes_only
boolean
default:"false"
Return only nodes.
​
edges_only
boolean
default:"false"
Return only edges.

​
Auto-layout

Reposition existing nodes in a canvas using a layout algorithm. This operates on the current canvas content only — it does not generate new nodes from the wiki-link graph (use POST /canvas/generate for that). 
POST /canvas/auto-layout?path=maps/site.canvas.json
Content-Type: application/json

{ "layout": "dot" }
​
path
string
required
Canvas file to update in place.
​
layout
string
default:"dot"
Graphviz engine: dot, neato, fdp, or circo.
POST /canvas/generate
Content-Type: application/json

{
  "path": "auto/graph.canvas.json",
  "layout": "hierarchical",
  "folder": "concepts/",
  "colorize": true
}
  • path — output file; default canvas.canvas.json. A .canvas.json suffix is added if missing.
  • layout — hierarchical (default), radial, force, or circular.
  • folder — optional prefix; only edges whose endpoints live under this folder are included.
  • colorize — boolean, default true.
Returns 503 if the link index is unavailable.
POST /canvas/generate and PATCH /canvas are REST-only. MCP exposes kiwi_canvas_list, kiwi_canvas_read, and kiwi_canvas_write — not generate or patch.

​
MCP parity

kiwi_canvas_list, kiwi_canvas_read, kiwi_canvas_write — see MCP.
Last modified on May 31, 2026