Squig API reference

One command model

REST and MCP call the same validated command layer. REST uses POST /api/v1/tools/{name}; MCP uses squig_{name}. The complete machine-readable schema lives at /openapi.json. A tool input that works through REST works unchanged through MCP.

Create a workspace

POST /api/v1/workspaces with a name returns an id and key once. The public signup endpoint allows five workspaces per day per trusted client address on Vercel. Self-hosted instances use a shared limit unless a trusted reverse proxy policy is added. Workspace keys are stored as SHA-256 hashes. Keep the returned key private.

curl -X POST https://squig.sh/api/v1/workspaces \
  -H "Content-Type: application/json" \
  -d '{"name":"My wireframes"}'

Create a document

Creating a document requires a workspace key. It returns canvasUrl and canvasKey: an editable invitation opening the normal canvas, and a bearer key scoped to that document. Share the full canvasUrl before drawing. Existing canvases accept their canvas key through the same API and MCP tools. GET does not reveal keys; rotate_canvas_link requires the workspace key and replaces the previous canvas invitation.

curl https://squig.sh/api/v1/documents \
  -H "Authorization: Bearer $SQUIG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Book club homepage"}'

Read and discover

GET /api/v1/documents lists the newest 100 documents in the workspace, or only the connected document for a canvas key. GET /api/v1/documents/{id} reads one with its revision and comments. GET /api/v1/catalog with no parameters returns a compact index: kind, name, category, group and size for every component. GET /api/v1/catalog?q=hero searches all components and ?kind=button returns one definition; both add defaults, dimensions and controls.

Atomic canvas editing

Send the current revision with every canvas mutation. All operations succeed together or none are saved. Explicit node IDs make a batch easy to reference. A successful edit returns the new revision, createdIds, the changed nodes it created or updated, deletedIds, the node count and the current variations, rather than the whole document; read GET /api/v1/documents/{id} when you need everything. If a request times out, read the document before retrying: do not assume it failed.

{
  "documentId": "DOCUMENT_ID",
  "revision": 1,
  "operations": [
    {"op":"add","nodes":[
      {"id":"title","type":"text","x":80,"y":60,"w":520,"h":64,"fontSize":36,"text":"A good book. Better company."},
      {"id":"join","type":"component","kind":"button","x":80,"y":160,"props":{"label":"Join the next meeting"}}
    ]},
    {"op":"variation","id":"meeting-first","title":"Meeting first","description":"Make the next gathering easy to find.","nodeIds":["title","join"]},
    {"op":"note","x":660,"y":60,"text":"This direction puts attending ahead of browsing."}
  ]
}

Limits and errors

Limits: 240 authenticated requests per workspace per minute or 600 per canvas key, 100 documents per workspace, 5000 nodes per document, 100 operations per batch, 1000 nodes per add, 4 MB document JSON and 4.5 MB request bytes. History returns the latest 50 revisions; older revisions remain restorable by number. Errors are JSON with error and optional validation details. Status codes include 400, 401, 403, 404, 409, 413, 415, 429 and 503. No cross-origin browser API access is enabled.

Workspace and canvas keys

POST /api/v1/workspace/rotate-key replaces the workspace key. Canvas keys remain independently revocable with rotate_canvas_link. A canvas key can read and edit its document, inspect the catalog, render and export. It cannot create or delete canvases, rotate keys or access other documents. Anyone holding the editable canvas link can edit it.

Command reference