Skip to main content

Excalidraw REST API · runnable workflow

A hosted Excalidraw API workflow with Founding Free access

Create a persistent diagram from JSON, render it for automation, hand the same canvas to a person in the browser, then make an optimistic-concurrency update after review.

01

Source

Bounded input

02

REST

Create + render

03

Canvas

Stable URL

04

Human

Review + edit

05

REST

Guarded patch

Editable workflow example

Editable OAuth PKCE sequence showing browser redirects, state validation, server-side verifier exchange, session creation, and a rejected state-mismatch path
Faithful SVG render from the editable v2 proof spec. The runnable REST sample is intentionally smaller; both preserve the state-validation decision for review.Open full-size SVG

A useful diagram API needs more than image output. The create response should lead to a stable artifact that code can update and a person can inspect without rebuilding it elsewhere.

Product boundary: Excaliwow is not affiliated with or endorsed by Excalidraw. Excalidraw+ has its own REST API in public beta for Plus workspaces. Choose Excalidraw+ when your diagrams already live in that workspace or its workspace surface is the better fit; choose Excaliwow when its Founding Free, persistent REST + CLI + MCP workflow fits your project.

Reproduce it

Copy setup

01

Create the narrow token

Verify an Excaliwow account and mint a Personal Access Token with read + write only. Publish and delete are unnecessary for this create, render, patch, and browser-review loop.

02

Create, render, and print the editor URL

This compact cross-platform request is runnable with curl and jq. It creates one persistent diagram, downloads an SVG render, and prints its editor URL for browser review.

Terminal · create + render

export EXCALIWOW_TOKEN=excw_pat_…

CREATE_RESPONSE=$(curl -fsS https://excaliwow.com/api/v1/diagrams \
  -H "Authorization: Bearer $EXCALIWOW_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
    "title": "OAuth PKCE review",
    "spec": {
      "version": "1",
      "layout": { "direction": "LR" },
      "nodes": [
        { "id": "browser", "label": "Browser redirect" },
        { "id": "app-validate", "label": "Validate state" },
        { "id": "token", "label": "Code + verifier exchange" },
        { "id": "session", "label": "Opaque session cookie" }
      ],
      "edges": [
        { "from": "browser", "to": "app-validate", "label": "code + state" },
        { "from": "app-validate", "to": "token", "label": "state matches" },
        { "from": "token", "to": "session", "label": "server to server" }
      ]
    }
  }')

DIAGRAM_ID=$(printf '%s' "$CREATE_RESPONSE" | jq -r .id)
curl -fsS "https://excaliwow.com/api/v1/diagrams/$DIAGRAM_ID/render?format=svg" \
  -H "Authorization: Bearer $EXCALIWOW_TOKEN" \
  -o oauth-pkce.svg

printf 'Open for review: https://excaliwow.com/c/%s\n' "$DIAGRAM_ID"

03

Guard the post-review update

After the editor has loaded the collaborative document, read its live revision and send it back as expectedUpdatedAt. A concurrent browser edit produces stale_read instead of being silently overwritten. A newly created, never-opened diagram reports a null revision because no live collaborative document exists yet.

Terminal · post-review guarded patch

READ_RESPONSE=$(curl -fsS \
  "https://excaliwow.com/api/v1/diagrams/$DIAGRAM_ID" \
  -H "Authorization: Bearer $EXCALIWOW_TOKEN")
REVISION=$(printf '%s' "$READ_RESPONSE" | jq -r .docUpdatedAt)

jq -n --arg revision "$REVISION" '{
  ops: [{
    op: "update",
    id: "app-validate",
    set: { strokeColor: "#c92a2a", backgroundColor: "#ffe3e3" }
  }],
  expectedUpdatedAt: $revision
}' | curl -fsS \
  "https://excaliwow.com/api/v1/diagrams/$DIAGRAM_ID/patch" \
  -H "Authorization: Bearer $EXCALIWOW_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @-

Human review

Change what the agent misunderstood

  1. Highlight state validation as the trust-boundary decision and change the failure node to a strong red treatment.
  2. Add a reviewer note that the verifier stays server-side and tokens never appear in the browser URL.

Same-canvas follow-up

Send the correction back

Update the same diagram in place: add the explicit state-mismatch rejection and secure cookie flags without moving the human-highlighted trust boundary.

Review the critical path, not the pixels

  • The browser carries the authorization code and state, never the PKCE verifier or tokens.
  • State is rejected before any back-channel token request.
  • The post-review update includes expectedUpdatedAt so a concurrent human edit fails safely.
  • The API render and browser editor refer to the same persistent diagram id.

Common questions

Is this the official Excalidraw API?
No. This is Excaliwow’s API for its hosted workspace built on the open-source Excalidraw editor. Excalidraw+ provides a separate official API in public beta. Excaliwow is not affiliated with or endorsed by Excalidraw.
Is the Excaliwow REST API free?
The first 10,000 verified accounts keep the current core workspace and developer platform free while Excaliwow operates. Accounts start with 3 diagrams and can earn more capacity. Normal API, capacity, abuse, security, and availability limits apply; optional future add-ons may be paid.
Can I prevent an API update from overwriting a browser edit?
Yes. After the diagram has opened as a collaborative document, read docUpdatedAt and send it as expectedUpdatedAt on a patch or regeneration. If the live document changed, the API returns stale_read so your integration can re-read and decide how to reconcile. A never-opened diagram has no live revision yet and returns null.
Does the API only return image files?
No. It creates persistent diagrams with stable ids, returns scene data, renders PNG or SVG, and supports in-place edits. People can open the same id in the browser for direct Excalidraw editing and collaboration.

Run the API-to-browser loop

Start free—no credit card. First 10,000 verified accounts keep the core workspace free; 3 diagrams to start and earn more capacity.

Start free