REST API

/v1/diagrams does the same work as the MCP tools, through the same code. The full contract, with every field and status code, is in the OpenAPI spec. The first version, /v1/scenes, is retired: every path answers 410 with code: "MOVED" and the method and path that replace it.

Authentication

Send an API key as Authorization: Bearer <key> (or in X-API-Key) on every call except these, which need none: POST /v1/diagrams/validate, POST /v1/diagrams/preview, GET /v1/public/diagrams/{ref} (version links, by a published diagram’s ID or a share link’s token), POST /v1/public/diagrams/{ref}/report, and the signed image links a render returns. Create keys under Dashboard → API keys. A key starts with dsp_sk_ and is shown once, when it is created. It acts in the workspace selected when it was made.

The MCP server also signs people in with their Zindex account (OAuth 2.1), for clients such as claude.ai and ChatGPT that can’t send a key (MCP tools). Those sign-in tokens work only on /mcp.

• Key errors. A key that isn’t accepted gets 401 with a code: API_KEY_INVALID (unknown, or its account was closed), API_KEY_REVOKED (revoked, or its person is no longer in its workspace) or API_KEY_EXPIRED. A request with no key at all gets AUTH_REQUIRED. Retrying the same key won’t help; use another.
• Workspaces. A diagram belongs to a workspace: your personal one, or a team workspace you are in. Each key acts in exactly one workspace, and any key of anyone in that workspace can read its diagrams. A diagram in another workspace answers 404 NOT_FOUND, the same as one that doesn’t exist. No endpoint takes a workspace parameter; to work in two workspaces, use a key for each (Workspaces).
• Write and read keys. A key has scope write or read. A read key finds, reads, renders, compares and exports one diagram. Anything that changes or shares a diagram, or reports a problem with one, answers 403 with code: "READ_ONLY" and reason: credential for a read key, role when the key’s person is a viewer in the workspace, whose keys act read-only whatever their scope.
• Email verification. Until the account has verified its email, saving, editing, deleting, restoring, sharing and reporting a diagram, and sending feedback, return 403 with code: "EMAIL_NOT_VERIFIED"; send the person to https://zindex.ai/verify-email. Reads, renders and the endpoints that need no key are never held back.

To create another key with an existing one:

curl -s https://api.zindex.ai/v1/auth/keys \
  -H "Authorization: Bearer $ZINDEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Production Key" }'

The response holds the new key, which can’t be retrieved again, with its scope and workspaceId. The new key acts in the same workspace as the key that made it. Add "scope": "read" for a read key; the default is write when the caller can write, and read otherwise. Asking for write with a read key, or as a viewer, answers 403 with code: "READ_ONLY". Add "expiresInDays" (a whole number from 1 to 366) for a key that expires; leave it out, or send null, for one that doesn’t. Any other value returns 400 with code: "INVALID_EXPIRES_IN_DAYS". The number of keys a workspace can have depends on its plan (Limits); a viewer can hold 3 in a workspace.

Endpoints

Wherever {id} appears, the diagram’s ID or your key for it works, except under /v1/public, which takes the ID, or a share link’s token, but never a key.

Save

curl -s https://api.zindex.ai/v1/diagrams \
  -H "Authorization: Bearer $ZINDEX_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "key": "payments-architecture",
    "brief": "Checkout payment services, left to right.",
    "scene": {
      "schemaVersion": "0.1",
      "scene": { "title": "Payments" },
      "layoutStrategy": { "direction": "LR" },
      "elements": [
        { "id": "api", "kind": "node", "nodeType": "service", "label": "API" },
        { "id": "db", "kind": "node", "nodeType": "database", "label": "Ledger" },
        { "id": "e1", "kind": "edge", "from": { "elementId": "api" }, "to": { "elementId": "db" }, "label": "writes" }
      ]
    }
  }'

{"id":"dgm_7Q2kD9a1B2c3","key":"payments-architecture","revision":1,"hash":"sha256:3f9a…","chain":"sha256:fdac…","warnings":[],"created":true}

Instead of scene you can send Mermaid text as mermaid, for an erDiagram or a flowchart (graph). Element IDs come from the Mermaid IDs, and the same text always gives the same diagram. What Mermaid leaves out is listed in warnings, and other Mermaid types are refused: see Mermaid scope.

warnings lists what checking the scene and drawing it noticed, each with the element when there is one and a one-line fix: for example TEXT_OVERFLOW when text doesn’t fit its element, or NODE_OVERLAP_DETECTED when two nodes sit on top of each other. The diagram is saved either way; an edit fixes it. POST /v1/diagrams/validate reports the same warnings without saving.

Zindex mints the ID; any scene.id you send is ignored. The key is your own name for the diagram, unique among the workspace’s live diagrams. Sending the same create again, with the same key and content, returns the existing diagram with created: false and status 200 (a new diagram answers 201), so retries are safe. The same key with different content, including after an edit, is a 409, KEY_EXISTS, and so is a teammate’s create with a key the team workspace already has, whatever its content: read and edit that diagram instead. Without a key, every create makes a new diagram.

hash is the version’s content hash, the SHA-256 of the scene that view=dsp returns, in RFC 8785 canonical form. chain is its chain hash. It also covers the version’s stored image and the chain hash of the version before it, so it changes if anything up to that version changes. chain is null until Zindex has computed it, normally when the version is saved; a render, an export or the next edit computes a missing one. Reads and the history never compute it. Verifying shows how to check a whole history with them.

Read

A read answers JSON: { id, revision, text }, with nextCursor when a long outline continues. GET /v1/diagrams/payments-architecture returns this outline as its text:

dgm_7Q2kD9a1B2c3 "Payments" r1 2026-10-05T09:12Z sha256:3f9a0c1d2e4b
key: payments-architecture
brief: Checkout payment services, left to right.
recent: r1 curl/8.7.1
outline: 2 nodes, 1 edges
  api service "API"
  db database "Ledger"
  e1: api -> db "writes"

• view=dsp returns { id, key, revision, hash, chain, createdAt, visibility, scene } instead, where scene is the scene document with defaults filled in and without computed, the engine’s drawing output (element boxes, edge routes, label positions). It holds what was written: what the engine infers while drawing, such as an ER edge end’s cardinality from its column, isn’t in it. The scene is valid input: POST /v1/diagrams with { "scene": ... } saves a copy under a new ID. Each node’s layout holds the position the engine placed it at, which is part of the content and its hash. Later edits keep it unless a node that grows needs the room, a frame added or deleted round it would leave frames overlapping or a frame holding a node that isn’t its member, or an order constraint you add finds its two nodes the wrong way round. The edit’s changed lists the nodes that move. Send autoLayout to have the engine place nodes again. The engine lays sequence diagrams out from their messages, so their nodes stay at x: 0, y: 0, which means not placed.
• view=mermaid returns { id, revision, hash, chain, mermaid, notes }: the diagram as Mermaid you can edit and send back (Edit as Mermaid). Entity-relationship diagrams come back as an erDiagram, every other family as a flowchart, and notes say what Mermaid can’t show. Sequence diagrams have no Mermaid view yet (VIEW_UNAVAILABLE).
• revision=3, or asOf=2026-09-26 (the end of that day in UTC) or an ISO timestamp with an offset, reads an earlier version.
• knownRevision=1, on a read of the latest version, returns { "unchanged": true }, or only what changed since revision 1, one line per element.
• elements=api,db limits the outline to those elements and their neighbors.

Change

curl -s https://api.zindex.ai/v1/diagrams/payments-architecture/revisions \
  -H "Authorization: Bearer $ZINDEX_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "baseRevision": 1,
    "message": "Add the job queue",
    "requestId": "6f1c2e7a-4b0d-4c55-9a51-2f1f8f7c9d10",
    "ops": [{ "op": "createNode", "id": "queue", "nodeType": "queue", "label": "Jobs" }]
  }'

{"id":"dgm_7Q2kD9a1B2c3","revision":2,"hash":"sha256:9b1c…","chain":"sha256:e665…","warnings":[],"changed":{"added":["queue"],"updated":[],"removed":[]}}

Every edit needs baseRevision, the revision you planned it against. Send exactly one of ops (operations, up to 500), mermaid (below), restoreRevision (a revision number, or { "asOf": "2026-09-26" }), or brief on its own. brief may also go with ops or mermaid; null removes it.

• Every change appends a revision; nothing is overwritten.
• An edit that changes nothing returns noop: true and makes no revision.
• An edit with an error saves nothing and returns a 422, VALIDATION_FAILED, with errors. That includes an op that can’t apply, such as moveElement on an edge, and a result that breaks a rule the diagram didn’t.
• A retry with the same requestId returns the first result with replayed: true. The same requestId with a different edit is a 422, REQUEST_ID_REUSED.
• If the diagram moved on since baseRevision, the answer is a 409, REVISION_CONFLICT, with the current revision and, when your base is older than it, changes, the elements that changed since your base. A retry whose result is already the current content returns noop: true instead.

Edit as Mermaid

Send the whole diagram as mermaid instead of ops, usually text you read with view=mermaid and changed. Zindex compares it with the baseRevision version and applies only the differences, as operations, so everything you didn’t change keeps its ID. Nodes and edges missing from the text are deleted, and frames and groups never change this way. It works on architecture and entity-relationship diagrams; Mermaid scope has the rules.

Images

GET /v1/images/[email protected] with your API key returns that version’s SVG; .png returns a PNG. Each version’s image is drawn once, when it is saved, and kept, so it never changes; add ?engine=current to draw it again with today’s engine instead (not stored). Add ?from=1 to draw that version with what changed since revision 1 colored: added in green, removed in red, changed in amber (from must be another revision of the diagram; anything else is a 400). GET /v1/diagrams/{id}/render, like the MCP tool diagram_render, returns links to the same images that a person can open from a chat without a key: a published diagram’s version links, which don’t expire but stop if the diagram is made private or deleted, with url for the version’s page; for any other diagram, signed links that work for 7 days, with expires. Render links draw the plain version: they ignore from, and diagram_render has no from, so an agent connected only through MCP sign-in gets changes as text from diagram_history with compare rather than as a colored image.

Version links

Sharing compares Only you, Anyone with the link and Public. A published diagram, and a diagram shared with a link, has a page and an image for every version that anyone can open without a key:

{ref} is a published diagram’s ID, or a share link’s token. An image is the one Zindex kept for the version, the same picture every other link to it shows. The website answers these links from GET /v1/public/diagrams/{ref}, which you can call directly; add .svg or .png for the image.

Putting a diagram in a doc, issue or README

Pick the link by what the place is for:

Scope:

• These links need a published diagram (every plan) or a share link (Pro and Team). Neither can be made in a team workspace whose owners turned public sharing off.
• A share link in a public repository is as public as the repository: anyone reading the page can open it. Revoking the link breaks every image that uses it (Caching and taking links down covers what other caches keep).
• The signed links from GET /v1/diagrams/{id}/render stop working after 7 days. They suit sending an image to someone, never a page that stays up.
• A diagram’s page in the dashboard writes each of these for the version shown or the latest, under Share: pick where it goes (GitHub, Google Docs, Notion or Confluence, a web page, Slack or email), then Copy.

Share links

A share link shows a diagram’s images and the dates of its versions to anyone who has it, until you revoke it. It never returns the scene JSON, the title or the description, and the diagram stays private. Anyone who has it can report the diagram, and Zindex revokes a link whose diagram breaks the content policy. The token is 22 random characters, so a link can’t be guessed, and it opens only its own diagram. Creating one needs Pro or Team: on Free it returns 403 with code: "FEATURE_UNAVAILABLE" (Limits). In a team workspace whose owners turned public sharing off, creating one, and publishing, return 403 with code: "SHARING_DISABLED" (Workspaces). Listing and revoking links work on every plan.

curl -s -X POST https://api.zindex.ai/v1/diagrams/payments-architecture/links \
  -H "Authorization: Bearer $ZINDEX_API_KEY"

{"id":"dgm_7Q2kD9a1B2c3","linkId":"lnk_4kP9wXr2TmQa","url":"https://zindex.ai/d/9xWqTk4PmZr7Hb2NcVd8Ls","svg":"https://zindex.ai/d/9xWqTk4PmZr7Hb2NcVd8Ls.svg","png":"https://zindex.ai/d/9xWqTk4PmZr7Hb2NcVd8Ls.png","createdAt":"2026-10-08T09:31:00.000Z"}

The link follows the latest version; add @2 for version 2. Its page’s SVG and PNG links do the same, and so does its link preview in Slack, Teams or iMessage, though an app keeps the preview it made. Anyone with the link can read what its page shows:

curl -s https://api.zindex.ai/v1/public/diagrams/9xWqTk4PmZr7Hb2NcVd8Ls

{"id":"dgm_7Q2kD9a1B2c3","access":"link","revision":2,"latest":2,"at":"2026-10-08T09:14:00.000Z","versions":[{"revision":2,"at":"2026-10-08T09:14:00.000Z"},{"revision":1,"at":"2026-10-08T09:12:00.000Z"}]}

GET /v1/diagrams/{id}/links lists the diagram’s links, newest first. DELETE /v1/diagrams/{id}/links/{linkId} revokes one:

curl -s -X DELETE https://api.zindex.ai/v1/diagrams/payments-architecture/links/lnk_4kP9wXr2TmQa \
  -H "Authorization: Bearer $ZINDEX_API_KEY"

{"id":"dgm_7Q2kD9a1B2c3","linkId":"lnk_4kP9wXr2TmQa","revoked":true}

From then on the link opens nothing:

curl -s https://api.zindex.ai/v1/public/diagrams/9xWqTk4PmZr7Hb2NcVd8Ls

{"error":"No public diagram or share link with that ID.","code":"NOT_FOUND"}

Published diagrams

PUT /v1/diagrams/{id}/sharing with { "visibility": "public" } publishes a diagram: anyone can then open its version links by ID, its page also shows its title and description, and GET /v1/public/diagrams/{id} returns its scene JSON.

curl -s -X PUT https://api.zindex.ai/v1/diagrams/payments-architecture/sharing \
  -H "Authorization: Bearer $ZINDEX_API_KEY" -H "Content-Type: application/json" \
  -d '{ "visibility": "public" }'

{"id":"dgm_7Q2kD9a1B2c3","visibility":"public","url":"https://zindex.ai/d/dgm_7Q2kD9a1B2c3","madePublicAt":"2026-10-08T09:32:00.000Z"}

curl -s -o payments-v1.svg https://api.zindex.ai/v1/public/diagrams/[email protected]

GET /v1/public/diagrams/{id} returns { id, access, title, description, revision, latest, at, madePublicAt, versions, scene, svg }: the version’s scene and its kept image. { "visibility": "private" } takes the diagram’s links by ID down again; its share links keep working until you revoke them.

Caching and taking links down

An exact version’s image never changes, so it is served with Cache-Control: public, max-age=31536000, immutable and an ETag of the version’s chain hash (its content hash while chain is null); send If-None-Match and an unchanged image answers 304. A link that follows the latest version, and every page answer, is served with Cache-Control: public, max-age=60. A share link’s answers are private rather than public: the visitor’s own browser may keep them, but no shared cache (a proxy, an image proxy, a chat preview) may, so a revoked link stops for new viewers.

Making a diagram private stops its links by ID at once, revoking a share link stops that link, and deleting the diagram stops both until it is restored; restoring it within 24 hours brings them back. Zindex’s own servers and edge keep nothing that could still answer. Copies people already fetched stay with them, as with any image once shared: a browser, or for a published diagram another cache, may keep an exact version’s image for up to a year, and a page or latest image for up to a minute. A private, deleted or unknown diagram and a revoked or unknown token all answer the same 404, so the answer doesn’t reveal which exist. The website’s page for that answer says the same for each. For a diagram’s ID it also offers to open the diagram in Zindex at the version the link names, /dashboard/diagram?id={id}&revision={revision}, where the people in its workspace see it once signed in. Every saved version’s image prints this address, zindex.ai/d/{id}@{revision}, in its bottom-right corner (The image’s address).

Reporting a diagram

Anyone, signed in or not, can report a diagram they can see that breaks the hosted-content policy with POST /v1/public/diagrams/{ref}/report and { "reason": "spam", "description": "...", "reporterEmail": "..." }. {ref} is the version link’s own: a published diagram’s ID, or a share link’s token, with @{revision} for the version seen (without it, the latest). The page at zindex.ai/d/{ref} sends its ref with the version it shows. reason is spam, hate, violence, abuse, illegal, copyright or other; description is 50 to 2,000 characters; the email is optional and never shown to the diagram’s owner.

A report is kept only when GET /v1/public/diagrams/{ref} would show that version: one by a private diagram’s ID, a revoked or unknown token, a deleted diagram or a version it doesn’t have is dropped. The answer is the same 200 either way, so it doesn’t reveal which IDs or tokens exist. A report through a share link records the link’s ID, never its token. Moderators see what the ref shows: a published diagram’s page, or, while a report through it is open, a share link’s images and version dates, never the scene.

What happens when a diagram breaks the policy:

• A published diagram is made private, every share link to it is revoked, and its owner is emailed the reason. This applies to a report through a share link too, while the diagram is published.
• A diagram shared only with links keeps every link but the reported one, which is revoked. Nothing else about the diagram changes. The person who made the link is emailed the reason; if they are no longer in the diagram’s workspace, its owners are.

A revoked link can’t be restored; the owner can make a new one, which needs Pro or Team.

Report a problem

When a version draws wrong, send it to Zindex support. A report is its own record of one version, with a one-line problem; the diagram stays as private or public as it was.

1. POST /v1/diagrams/{id}/reports/preview with { "revision": 2, "anonymize": true } (both optional; the default is the latest version, anonymized) returns { id, revision, anonymized, svg }, plus a seed when anonymized: the version drawn as support will see it. Nothing is stored.
2. POST /v1/diagrams/{id}/reports with { "problem": "The label sits on the edge", "revision": 2, "anonymize": true, "seed": 123 } returns 201 with { reportId, id, revision, reported: true, anonymized }. Pass the preview’s seed and support sees exactly the copy you previewed; without it, a new random substitution is made. problem is one line of up to 500 characters.
3. GET /v1/diagrams/{id}/reports/{reportId} returns { id, reportId, revision, anonymized, svg }: what support sees, at any time after sending. DELETE on the same path withdraws the report.

An anonymized report keeps that anonymized copy, and staff see only it. With anonymize: false, staff see the version as it is. Deleting the diagram hides its reports from staff at once; they are removed with the diagram 24 hours later.

Feedback

Tell Zindex staff about a bug, a place where the docs and the engine disagree, or something you needed that is missing. Feedback needs an account but no saved diagram. Staff read every item; no model does. An item has:

• kind: bug, docs (the docs and the engine disagree), request or other
• summary: one line, up to 200 characters
• expected and observed: optional, up to 2,000 characters each
• confidence: optional, seen, likely or unsure
• optionally, id (with revision; default the latest) to attach a version of one of the workspace’s diagrams (not with a read key or as a viewer), or snippet: a scene document or Mermaid text of up to 64 KB. Either is anonymized unless anonymize is false, as in a problem report.

The person confirms each item before it is sent. The first request stores nothing: it answers 400 with code: "CONFIRMATION_REQUIRED", a confirm token and preview, the item exactly as staff will see it, with the engine version and client Zindex adds.

curl -s -X POST https://api.zindex.ai/v1/feedback \
  -H "Authorization: Bearer $ZINDEX_API_KEY" -H "Content-Type: application/json" \
  -d '{ "kind": "docs", "summary": "The guide says an edge may end on a frame", "expected": "The edge draws to the frame", "observed": "EDGE_ENDPOINT_KIND_INVALID", "confidence": "seen" }'

{"error":"Nothing was sent. Show the person the preview, and only if they agree, send the same body again with confirm set to the token; it expires in 10 minutes.","code":"CONFIRMATION_REQUIRED","confirm":"1791541440.Qm8rT2vXk9LpZ4nWc7HbYd","preview":{"kind":"docs","summary":"The guide says an edge may end on a frame","expected":"The edge draws to the frame","observed":"EDGE_ENDPOINT_KIND_INVALID","confidence":"seen","engine":"6.0.0+build.1690","client":"curl/8.7.1","diagram":null,"anonymized":null,"snippet":null}}

Show the person the preview. Only if they agree, send the same body again with confirm. The token works for 10 minutes, for that account and that item only:

curl -s -X POST https://api.zindex.ai/v1/feedback \
  -H "Authorization: Bearer $ZINDEX_API_KEY" -H "Content-Type: application/json" \
  -d '{ "kind": "docs", "summary": "The guide says an edge may end on a frame", "expected": "The edge draws to the frame", "observed": "EDGE_ENDPOINT_KIND_INVALID", "confidence": "seen", "confirm": "1791541440.Qm8rT2vXk9LpZ4nWc7HbYd" }'

{"feedbackId":"fb_6tJ3wNq8KxPa","sent":true,"status":"new"}

GET /v1/feedback lists your items newest first (limit up to 50, default 20, and cursor from nextCursor), each with what staff see and its status: new, accepted, fixed, wont-fix or duplicate. note is from Zindex staff, and a fixed item’s fixedIn names the version that fixed it. The dashboard shows the same list under Your feedback.

curl -s https://api.zindex.ai/v1/feedback \
  -H "Authorization: Bearer $ZINDEX_API_KEY"

{"feedback":[{"feedbackId":"fb_6tJ3wNq8KxPa","kind":"docs","summary":"The guide says an edge may end on a frame","expected":"The edge draws to the frame","observed":"EDGE_ENDPOINT_KIND_INVALID","confidence":"seen","engine":"6.0.0+build.1690","client":"curl/8.7.1","diagram":null,"anonymized":null,"snippet":null,"status":"new","note":null,"fixedIn":null,"sentAt":"2026-10-09T10:15:00.000Z","updatedAt":null}]}

An account can send 20 items in any 24 hours; past that, the answer is 429 with code: "RATE_LIMITED" and retryAfter, the seconds until the next can go. Deleting a diagram hides the feedback that carries it from staff at once, and removes it with the diagram 24 hours later; closing the account removes all of it. Over MCP, diagram_share with action: "feedback" takes the same fields and asks the person the same way (MCP tools).

History and compare

GET /v1/diagrams/{id}/revisions lists versions newest first, with the time, who saved each one (by, their name, else their email) and how (credential: session, api_key or oauth, never which key), the client, its message, its chain hash and how many elements it added, changed and removed. GET /v1/diagrams/{id}/compare?from=2026-09-01&to=2026-10-01 returns the element IDs added, changed and removed between two versions, and authors, each distinct { by, client } that saved a version between them.

Export

GET /v1/diagrams/{id}/export downloads one diagram’s whole history as JSON Lines. The first line is a header with the diagram’s id, key, title and revisions. One line per version follows, oldest first, with its scene, its hash and chain, and its stored image. That is all you need to check the history yourself (Verifying).

GET /v1/workspace/export downloads every diagram in the workspace the key acts in, in one file, in the format zindex-account-history/1; GET /v1/account/export is the same download. Settings → Account on zindex.ai downloads the same file for the selected workspace. In a team workspace only its owners can download it, with the dashboard or their own keys; anyone else gets 403 with code: "OWNER_REQUIRED", and can still download each diagram’s history. Its first line names the format and the workspace (kind is personal or team). Each diagram follows in ID order, written exactly as its own export, and the last line counts the diagrams:

{"format":"zindex-account-history/1","workspace":{"id":"0b7e4c1a-…","name":"Personal workspace ([email protected])","kind":"personal"},"exportedAt":"2026-10-13T09:00:00.000Z"}
{"format":"zindex-history/1","chain":"zindex-chain/1","id":"dgm_7Q2kD9a1B2c3","key":"payments-architecture","title":"Payments","revisions":2,"exportedAt":"2026-10-13T09:00:00.004Z"}
{"revision":1,"at":"2026-10-05T09:12:00.000Z","by":"Ana Lima","actor":{"userId":"…","credential":"api_key","credentialId":"…"},"client":"curl/8.7.1","message":null,"hash":"sha256:3f9a…","chain":"sha256:fdac…","scene":{…},"image":{…}}
{"revision":2,…}
{"format":"zindex-history/1","chain":"zindex-chain/1","id":"dgm_Hq3vT8bWm2Xa","key":null,"title":"Orders","revisions":1,"exportedAt":"2026-10-13T09:00:00.019Z"}
{"revision":1,…}
{"end":true,"diagrams":2}

A line with "format": "zindex-history/1" starts the next diagram. A file without the closing line was cut short; download it again. Deleted diagrams are left out, even while they can be restored, and so are share links, problem reports and feedback. Both exports are sent a line at a time as Zindex writes them, so a large workspace starts downloading at once.

Errors

Errors are JSON with error, one sentence, and a code.