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 scopes, rate limits, and the auth error codes.

Conventions

• Base path is /api/v1. All request and response bodies are JSON.
• Every endpoint declares a required scope. A read-write token satisfies a read requirement.
• 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

Scope: read. Returns the identity behind the calling token. Useful as a quick check that a token is valid.

{
  "id": "<userId>",
  "email": "[email protected]",
  "scope": "read" | "read-write"
}

GET /diagrams

Scope: 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

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

POST /api/v1/diagrams
Authorization: Bearer <read-write token>
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

Scope: 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,
  "scene": { "elements": [ /* ... */ ], "appState": {} }
}

PATCH /diagrams/:id

Scope: read-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 <read-write token>
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

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

204 No Content

GET /diagrams/:id/render

Scope: read. Renders the diagram's saved scene to a preview. The output format is chosen with ?format=.

The default json format returns an envelope:

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

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

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. Each call renders fresh; there is no PNG cache.

PUT /diagrams/:id/public-link

Scope: read-write. 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

Scope: read-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.

GET /folders

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

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

POST /folders

Scope: read-write. Creates a folder.

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

PATCH and DELETE /folders/:id

Scope: read-write. 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.

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.