Interact with open tldraw desktop canvases via a local HTTP API at localhost:7236. Create, read, update, and delete shapes. Take screenshots. Build diagrams, flowcharts, wireframes, and visual layouts programmatically. Use when the user asks to draw, diagram, sketch, wireframe, create a visual, modify a canvas, add shapes, create a flowchart, create an architecture diagram, or work with tldraw. Also triggers on "draw on canvas", "add to canvas", "update the diagram", "show me on the canvas", or any reference to tldraw files (.tldr).
Local HTTP API at http://localhost:7236 for reading and modifying open tldraw canvases.
For full shape types, actions, colors, and exec API details, read references/api-reference.md.
# List all open docs
curl -s "http://localhost:7236/api/doc" | jq
# Filter by name
curl -s "http://localhost:7236/api/doc?name=my-file" | jq
Extract the id field for subsequent calls. If no docs are open, tell the user to open a .tldr file in tldraw desktop.
# Screenshot (save and view with Read tool)
curl -s "http://localhost:7236/api/doc/DOC_ID/screenshot" --output /tmp/canvas.jpg
# Read all shapes as JSON
curl -s "http://localhost:7236/api/doc/DOC_ID/shapes" | jq
Always take a screenshot first to understand the current state before making changes.
curl -s -X POST "http://localhost:7236/api/doc/DOC_ID/actions" \
-H 'Content-Type: application/json' \
-d '{"actions": [...]}'
All actions in one request form a single undo step. Prefer batching related changes.
After changes, take a screenshot to confirm correctness. Make incremental changes and verify frequently.
{"actions": [{"_type": "create", "shape": {"_type": "rectangle", "shapeId": "box1", "x": 100, "y": 100, "w": 200, "h": 80, "color": "blue", "fill": "solid", "text": "Service A", "note": ""}}]}
{"actions": [{"_type": "create", "shape": {"_type": "arrow", "shapeId": "arr1", "x1": 0, "y1": 0, "x2": 100, "y2": 0, "color": "black", "fromId": "box1", "toId": "box2", "text": "", "note": ""}}]}
Use fromId/toId to bind arrow endpoints to shapes — the arrow stays connected when shapes move.
{"actions": [{"_type": "place", "shapeId": "box2", "referenceShapeId": "box1", "side": "right", "align": "center", "sideOffset": 40}]}
top, center-horizontal, bottom, left, center-vertical, right)horizontal, vertical)For operations not covered by the structured API:
curl -s -X POST "http://localhost:7236/api/doc/DOC_ID/exec" \
-H 'Content-Type: application/json' \
-d '{"code": "return editor.getCurrentPageShapes().length"}'
Note: In exec, text props use richText not text. Use toRichText('...') to set text.
shapeId values (e.g., "auth-service", "db-arrow") for easy reference in updates.place action for relative positioning instead of computing coordinates manually.setMyView to navigate the viewport after placing shapes.