REST API

Authentication

Every request carries a Personal Access Token in the standard bearer header. Mint a token in your account settings and send it with each call.

Authorization: Bearer <your-token>

See Authentication for token capabilities, rate limits, and the auth error codes.

Conventions

• Base path is /api/v1. All request and response bodies are JSON.
• Every endpoint declares the capability it requires — read, write, publish, or delete. A token without it gets 403 insufficient_scope.
• Access checks return 404 not_found when a target is missing OR is not yours. The two cases are indistinguishable, so the API never leaks whether an id exists.

Every failure shares one envelope shape:

{ "error": "<machine_code>", "message"?: "<human-readable detail>" }

The error value is a stable machine code. The optional message adds human detail and is omitted entirely when there is none.

Endpoints

GET /me

Capability: none — any valid token answers. Returns the identity and grants behind the calling token. Useful as a quick check that a token is valid.

{
  "id": "<userId>",
  "email": "user@example.com",
  "capabilities": ["read", "write", "publish", "delete"],
  "scope": "read" | "read-write"
}

scope is a legacy coarse summary — read-write only when the token holds every capability. New integrations should read capabilities.

GET /diagrams

Capability: read. Lists the diagrams you own, newest first, with cursor pagination. List items do not include the scene; fetch a single diagram to read it.

{
  "items": [
    {
      "id": "<id>",
      "title": "Architecture",
      "folderId": "<id>" | null,
      "starred": false,
      "updatedAt": "2026-06-02T12:00:00.000Z",
      "createdAt": "2026-06-01T09:00:00.000Z"
    }
  ],
  "nextCursor": "<cursor>" | null
}

When nextCursor is non-null, pass it back as the cursor query param to fetch the next page. A null cursor means there are no more pages.

POST /diagrams

Capability: write. Creates a diagram from exactly one of spec or scene. Sending both, or neither, is rejected.

POST /api/v1/diagrams
Authorization: Bearer <token with write capability>
Content-Type: application/json

{
  "title": "Architecture",
  "spec": {
    "version": "1",
    "nodes": [
      { "id": "client", "label": "Client",     "shape": "rectangle" },
      { "id": "api",    "label": "API Server",  "shape": "rectangle" },
      { "id": "db",     "label": "Database",    "shape": "diamond" },
      { "id": "cache",  "label": "Cache",       "shape": "ellipse" }
    ],
    "edges": [
      { "from": "client", "to": "api", "label": "request" },
      { "from": "api",    "to": "db" },
      { "from": "api",    "to": "cache" }
    ],
    "layout": { "direction": "TB" }
  }
}

{
  "id": "<id>",
  "title": "Architecture",
  "folderId": "<id>" | null,
  "ownerId": "<userId>",
  "createdAt": "2026-06-02T12:00:00.000Z",
  "updatedAt": "2026-06-02T12:00:00.000Z",
  "elementCount": 11
}

See the diagram DSL for the full spec grammar, including shorthand edge strings.

GET /diagrams/:id

Capability: read. Returns the full scene. A trashed diagram is still returned, with deletedAt set, so it can be inspected or restored.

{
  "id": "<id>",
  "title": "Architecture",
  "folderId": "<id>" | null,
  "ownerId": "<userId>",
  "createdAt": "2026-06-02T12:00:00.000Z",
  "updatedAt": "2026-06-02T12:00:00.000Z",
  "deletedAt": "2026-06-02T13:00:00.000Z" | null,
  "docUpdatedAt": "2026-06-02T12:30:00.000Z" | null,
  "scene": { "elements": [ /* ... */ ], "appState": {} }
}

docUpdatedAt is the live-doc revision clock. Echo it back as expectedUpdatedAt on regenerate or patch to make the write conditional on nobody else having edited since (see those endpoints).

PATCH /diagrams/:id

Capability: write. Renames and/or moves a diagram. At least one field is required. The response does not include the scene.

PATCH /api/v1/diagrams/<id>
Authorization: Bearer <token with write capability>
Content-Type: application/json

{
  "title": "Architecture v2",
  "folderId": "<folder-id>"
}

{
  "id": "<id>",
  "title": "Architecture v2",
  "folderId": "<folder-id>" | null,
  "ownerId": "<userId>",
  "createdAt": "2026-06-02T12:00:00.000Z",
  "updatedAt": "2026-06-02T14:00:00.000Z",
  "deletedAt": null
}

DELETE /diagrams/:id

Capability: delete. Soft-deletes a diagram to the trash. The call is idempotent: deleting an already-trashed diagram still succeeds. Returns no body.

204 No Content

POST /diagrams/:id/restore

Capability: delete. The inverse of DELETE — brings a trashed diagram back by clearing its deletedAt. Restore is part of the delete lifecycle, so it is owner-only and needs the same delete capability. It is idempotent: restoring an already-active diagram is a harmless no-op. Takes no body and returns none.

204 No Content

GET /diagrams/:id/render

Capability: read. Renders the diagram's saved scene. By default the render is faithful — the editor's own exporter, with real hand-drawn strokes, editor fonts, and embedded images — falling back gracefully to a fast preview if the render service is unavailable. The output format is chosen with ?format= and the fidelity with ?quality=.

The default json format returns an envelope:

{
  "isEmpty": false,
  "elementCount": 11,
  "svg": "<svg ...>",
  "png": "<base64, no data: prefix>" | null,
  "quality": "faithful" | "fast",
  "note"?: "faithful_unavailable" | "images_truncated"
             | "large_diagram_placeholder" | "render_failed"
}

// empty scene
{ "isEmpty": true, "elementCount": 0, "svg": null, "png": null, "quality": "fast" }

quality reports the fidelity you actually got — faithful or, when the render service could not serve it, fast with note: "faithful_unavailable". An agent that needs production-quality bytes should read quality to confirm it. images_truncated means some embedded images were dropped to stay within limits.

The png format returns image/png bytes (the rendered PNG is 1024 pixels wide, roughly 1024 by 640), and svg returns image/svg+xml. For either image format an empty scene returns 204. Raw image responses carry the fidelity in an x-render-quality header (faithful or fast) plus an x-render-note header when a note applies. Faithful renders are served from a content-keyed cache, so re-rendering an unchanged scene returns the cached bytes; any edit changes the key and re-renders.

PUT /diagrams/:id/public-link

Capability: publish. Turns the anonymous public link on or off and optionally sets or clears its password.

{
  "slug": "<slug>",
  "enabled": true,
  "hasPassword": false,
  "version": 1,
  "url": "<absolute public link url>" | null
}

url is an absolute URL when the link is enabled, and null when it is disabled.

POST /diagrams/:id/edit

Capability: write. Additively merges an edit fragment into a diagram. Existing elements are never moved, resized, or deleted; the fragment only adds nodes and edges and patches a small allowlist of node properties. The change is reflected immediately in a subsequent read or render.

{
  "addNodes":    [ /* new nodes, explicit x/y honored, else auto-placed */ ],
  "addEdges":    [ /* from/to resolve against existing or added node ids */ ],
  "updateNodes": [ /* { id } plus the allowed properties below */ ]
}

Only non-reflow properties can be patched on existing nodes: strokeColor, backgroundColor, fillStyle, and label (plus the required id). Geometry fields like x, y, width, height, and shape are rejected, so an already-placed node never starts overlapping a neighbor.

{ "added": ["<id>"], "updated": ["<id>"], "merged": 2 }

See the diagram DSL for the full edit-fragment shape and field rules.

POST /diagrams/:id/regenerate

Capability: write. The destructive sibling of /edit: it replaces the whole scene in place, keeping the same id and URL. Send exactly one of spec or scene (same XOR rule as create), plus an optional title rename and an optional expectedUpdatedAt precondition. Comments bound to elements the new scene no longer contains are system-resolved; comments bound to ids the new spec reuses stay anchored.

POST /api/v1/diagrams/<id>/regenerate
Authorization: Bearer <token with write capability>
Content-Type: application/json

{
  "spec": { "nodes": [ /* ... */ ], "edges": [ /* ... */ ] },
  "title": "Architecture v2",
  "expectedUpdatedAt": "2026-06-02T12:30:00.000Z"
}

{
  "id": "<id>",
  "replaced": 11,
  "orphanedComments": 0,
  "title": "Architecture v2"
}

replaced is the new element count and orphanedComments how many comments were resolved by the swap. title is echoed only when a rename was applied. Content-model failures return the same 422/413 codes as create.

POST /diagrams/:id/patch

Capability: write. The surgical sibling of /edit and /regenerate: it applies an ordered list of element-addressable ops (add, update, move, resize, restyle, delete) in place, keeping the same id and URL. Send only the deltas. An optional expectedUpdatedAt precondition is supported. Comments bound to an element a delete op removes are system-resolved.

POST /api/v1/diagrams/<id>/patch
Authorization: Bearer <token with write capability>
Content-Type: application/json

{
  "ops": [ /* ordered element-addressable operations */ ],
  "expectedUpdatedAt": "2026-06-02T12:30:00.000Z"
}

{
  "id": "<id>",
  "applied": 3,
  "elements": 12,
  "deleted": 1,
  "orphanedComments": 0
}

applied is the number of ops applied, elements the resulting scene element count, and deleted how many elements the patch removed. The full op grammar and update allowlist live in the diagram DSL reference.

GET /folders

Capability: read. Returns a flat list of every folder you own.

{
  "items": [
    { "id": "<id>", "name": "Architecture", "parentId": "<id>" | null }
  ]
}

POST /folders

Capability: write. Creates a folder.

{ "id": "<id>", "name": "Architecture", "parentId": "<id>" | null }

PATCH and DELETE /folders/:id

Capability: write for PATCH, delete for DELETE. PATCH renames a folder with a { "name": "<new name>" } body and returns the updated folder. DELETE removes the folder and returns 204. Member diagrams are not deleted; they become unfiled.

GET /icons

Capability: read. Returns the curated server-side icon catalog. Embed one by adding an image element to a scene with its fileId set to an icon id (e.g. icon-database). Only ids returned here resolve; the response omits the raw bytes.

{
  "items": [
    {
      "id": "icon-database",
      "label": "Database",
      "category": "data",
      "width": 128,
      "height": 128,
      "mimeType": "image/png"
    }
  ]
}

Error codes

Transport and authentication codes, returned by any endpoint:

Content-model codes, returned when a spec, scene, or edit fragment fails validation (422) or exceeds a size cap (413). The accompanying message names the offending element.

Limits and fidelity

Prefer a higher-level client? The CLI and MCP server wrap this same surface.