Local Squig API reference

One command model

The companion exposes POST /api/v1/tools/{name}; MCP uses squig_{name} with the same JSON input. Session discovery uses squig_local_session over MCP or GET /api/local/session over HTTP. Use the loopback origin returned by your running session. The public squig.sh server does not accept new canvas writes. /openapi.json describes the local API shapes; tools are discovered from the running MCP server.

Connect to the selected file

Start pnpm squig serve with an absolute .squig.json path. Local HTTP requests require the session token as Authorization: Bearer. Get the address and credential from Connect agent in the local editor. There is no workspace signup: documents lists only the selected file, and get_document reads it with revision and structured comments. GET /api/local/session returns local session information.

curl "http://127.0.0.1:PORT/api/v1/documents" -H "Authorization: Bearer LOCAL_SESSION_TOKEN"

Read and discover

GET /api/v1/documents lists the selected document; GET /api/v1/documents/{id} reads it. GET /api/v1/catalog returns a compact component index. A catalog query or kind adds defaults, dimensions and controls. The get_document tool returns the complete document; edit_document returns the new revision and the nodes created, changed or deleted, keeping edit responses small.

Atomic canvas edits

Read the current revision before editing and send it unchanged with the mutation. All operations validate together and save together. A stale revision returns 409 even if your payload would otherwise be unchanged. Identical current content returns the same revision without another history snapshot. After a timeout, read the file before retrying; do not assume the save failed.

{
  "documentId": "DOCUMENT_ID",
  "revision": 12345,
  "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."
    }
  ]
}

Persistence and limits

The companion writes atomically to the selected file and detects external edits. It preserves variation and comment metadata when the browser saves editable fields. Limits include 5000 nodes, 100 operations per batch, 1000 nodes per add and 16 MiB for the portable file including comments. HTTP and stdio request envelopes allow an additional 64 KiB. MCP responses have a separate 8 MiB cap: larger tool results or validation errors return a bounded error with the selected filePath and revision when available. If the error says the operation completed, the edit remains saved; inspect the file before retrying a mutation. History keeps at most 50 entries and 16 MiB per file; expired revisions cannot be restored. Use separate backups for permanent history. Invalid inputs, filesystem failures and revision conflicts return actionable tool errors.

Recovering an old online canvas

Public hosted collaboration is retired. Existing credentials can still read and export old documents through the temporary recovery path; they cannot create workspaces or save edits online. Recover the drawing, download its .squig.json, then continue with a local companion. Local session tokens and old hosted keys are separate credentials.

Command reference