tmdgusya/tldraw-desktop

tldraw Desktop Canvas API

Programmatically create and modify diagrams on the tldraw desktop app via its local HTTP API at http://localhost:7236.

IMPORTANT: Always use curl for all API calls. Do NOT use fetch, wget, or any other HTTP client.

Workflow

1. curl -s http://localhost:7236/api/doc                          → list open docs (get DOC_ID)
2. curl -s http://localhost:7236/api/doc/{id}/shapes              → read current shapes
3. curl -s -X POST http://localhost:7236/api/doc/{id}/actions     → create/modify shapes
4. curl -s http://localhost:7236/api/doc/{id}/screenshot -o f.jpg → verify result visually

Always verify your work with a screenshot after making changes. Prefer small, incremental batches.

Overlap Check — MANDATORY after every batch of changes

After creating or modifying shapes, you MUST:

1. Take a screenshot and visually inspect for overlapping shapes, crossing arrows, or crowded text
2. If overlaps or readability issues are found, fix them using place, move, stack, align, or distribute
3. Take another screenshot to confirm the fix

digraph overlap_check {
    "Make changes" -> "Screenshot";
    "Screenshot" -> "Overlaps or crowding?" [label="inspect"];
    "Overlaps or crowding?" -> "Fix layout" [label="yes"];
    "Fix layout" -> "Screenshot";
    "Overlaps or crowding?" -> "Done" [label="no, clean"];
}

Common overlap fixes:

• Shapes stacked on top of each other → use stack with gap: 80 or place with sideOffset: 80
• Arrows crossing through unrelated shapes → move the blocking shape out of the path, or use kind: "elbow" for right-angle routing
• Text labels overlapping → make shapes wider (resize or update with larger w) or increase gap between shapes
• Dense diagrams → split into rows/columns using stack + align, or increase spacing with distribute

Quick Reference

Endpoints

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /api/doc | List open docs. Filter: ?name= | | GET | /api/doc/:id/shapes | All shapes on current page | | GET | /api/doc/:id/screenshot | JPEG capture. ?size=small\|medium\|large\|full | | POST | /api/doc/:id/actions | Structured actions (see below) | | POST | /api/doc/:id/exec | Run arbitrary JS against tldraw Editor |

Shape Types

| Type | Key Properties | |------|---------------| | rectangle, ellipse, triangle, diamond, hexagon, pill, cloud, star, heart, pentagon, octagon, x-box, check-box, trapezoid, parallelogram-right/left, fat-arrow-right/left/up/down | shapeId, x, y, w, h, color, fill, text, note | | text | shapeId, x, y, anchor, color, fontSize, maxWidth, text | | arrow | shapeId, fromId, toId, color, kind (arc\|elbow), text, bend | | line | shapeId, x1, y1, x2, y2, color | | note | shapeId, x, y, color, text (sticky note) | | pen | shapeId, points:[{x,y}], color, style (smooth\|straight), closed, fill |

Colors: red, light-red, green, light-green, blue, light-blue, orange, yellow, black, violet, light-violet, grey, white Fill: none, tint, background, solid, pattern Anchor (text): top-left, top-center, top-right, center-left, center, center-right, bottom-left, bottom-center, bottom-right

Actions

POST to /api/doc/:id/actions with {"actions": [...]}. All actions in one request = single undo step.

| Action | Payload | |--------|---------| | create | {"_type":"create","shape":{...}} | | update | {"_type":"update","shape":{"shapeId":"id","_type":"rect",...changed props}} | | delete | {"_type":"delete","shapeId":"id"} | | clear | {"_type":"clear"} | | label | {"_type":"label","shapeId":"id","text":"new text"} | | move | {"_type":"move","shapeId":"id","x":N,"y":N,"anchor":"center"} | | place | {"_type":"place","shapeId":"id","referenceShapeId":"ref","side":"right","align":"center","sideOffset":20} | | align | {"_type":"align","shapeIds":[...],"alignment":"center-horizontal"} | | distribute | {"_type":"distribute","shapeIds":[...],"direction":"horizontal"} | | stack | {"_type":"stack","shapeIds":[...],"direction":"vertical","gap":20} | | resize | {"_type":"resize","shapeIds":[...],"scaleX":2,"scaleY":1.5} | | rotate | {"_type":"rotate","shapeIds":[...],"degrees":45} | | bringToFront | {"_type":"bringToFront","shapeIds":[...]} | | sendToBack | {"_type":"sendToBack","shapeIds":[...]} | | pen | {"_type":"pen","shapeId":"id","points":[{"x":0,"y":0},...],"color":"black","style":"smooth"} |

place sides: top, bottom, left, right align options: top, center-vertical, bottom, left, center-horizontal, right

Best Practices

• Always use curl for all HTTP calls — no exceptions
• Default shape size: ~300x200 with ~200 gap between shapes
• Connect shapes with arrows: use fromId/toId — arrows stay attached when shapes move
• Prefer high-level actions (place, stack, align) over manual coordinate math
• Batch actions in a single POST for atomic undo/redo
• Use place to position shapes relative to each other instead of calculating coordinates
• Default styles: black, medium, draw style, centered text, no fill — unless there's a reason to change
• Fill recommendations: none for outlines, solid for tinted backgrounds
• Screenshot after changes to verify layout and check for overlaps
• Assign readable shapeIds (e.g., "auth-box", "db-node") for easier reference
• Large diagrams (7+ shapes): build in stages — create a few shapes, screenshot, adjust layout, then add more

Example: Creating a Flowchart

DOC_ID="your-doc-id"
BASE="http://localhost:7236/api/doc/$DOC_ID"

# Create shapes + connect with arrows in one call
curl -s -X POST "$BASE/actions" \
  -H "Content-Type: application/json" \
  -d '{
    "actions": [
      {"_type":"create","shape":{"_type":"rectangle","shapeId":"start","x":100,"y":100,"w":300,"h":200,"text":"Start"}},
      {"_type":"create","shape":{"_type":"diamond","shapeId":"decision","x":100,"y":400,"w":300,"h":200,"text":"Condition?"}},
      {"_type":"create","shape":{"_type":"rectangle","shapeId":"end","x":100,"y":700,"w":300,"h":200,"text":"End"}},
      {"_type":"create","shape":{"_type":"arrow","shapeId":"a1","fromId":"start","toId":"decision"}},
      {"_type":"create","shape":{"_type":"arrow","shapeId":"a2","fromId":"decision","toId":"end","text":"Yes"}}
    ]
  }'

# MANDATORY: Screenshot to check for overlaps
curl -s "$BASE/screenshot?size=medium" -o screenshot.jpg
# Inspect the screenshot — if shapes overlap or arrows cross, fix with place/move/stack

Exec API

For advanced operations not covered by structured actions:

curl -s -X POST "$BASE/exec" \
  -H "Content-Type: application/json" \
  -d '{"code": "return editor.getCurrentPageShapeIds().size"}'

Full SDK docs available at: curl -s http://localhost:7236/api/llms