Quickstart

Immutable agent diagrams. Your AI saves a diagram to Zindex and changes it later, from any client. Every change becomes a new numbered version, kept with the image it produced, and any version can be read by number or by date. Concepts explains the model. No model runs inside Zindex.

Saving a diagram, and reading or changing a saved one, needs a free account. Sign up at zindex.ai/signup with an address you’ll keep: disposable inboxes are refused. Without an account or key, diagram_validate and unsaved diagram_render previews work, and so do POST /v1/diagrams/validate and /v1/diagrams/preview.

Connect your AI

Add the MCP server https://api.zindex.ai/mcp to your client. claude.ai, the Claude apps, ChatGPT, Claude Code, Cursor and VS Code sign you in with your Zindex account (OAuth), so they need no API key. In Claude Code:

claude mcp add --transport http zindex https://api.zindex.ai/mcp

Then run /mcp and choose to authenticate. The Zindex page asks whether the client may change diagrams or only read them, and, if you belong to a team workspace, which workspace it works in; to work in two workspaces, connect once for each. Connect your AI has the steps for each client, and MCP tools covers API keys, the npm package for hosts that run servers locally, and every tool.

Ask your AI for a diagram, for example “Save an architecture diagram of an API gateway in front of a Postgres database, key payments-architecture”. The agent saves it with diagram_create, reads it with diagram_get, changes it with diagram_edit and returns image links from diagram_render.

Or use the REST API

Create an API key under Dashboard → API keys (keys start with dsp_sk_) and send it as a bearer token. The key works in the workspace selected in the dashboard when you make it, with read and write access unless you choose read only. The REST API page has every endpoint.

1. Save a diagram

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.",
    "message": "First version",
    "scene": {
      "schemaVersion": "0.1",
      "diagramFamily": "architecture",
      "layoutStrategy": { "direction": "LR" },
      "scene": { "title": "Payments" },
      "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_wjVNCDVawJzT","key":"payments-architecture","revision":1,"hash":"sha256:be1cd7...","chain":"sha256:9c68ef...","warnings":[],"created":true}

Zindex mints the ID. The key is your own name for the diagram, so sending the same create again returns the existing diagram with created: false; the same key with different content is a 409, KEY_EXISTS. The scene leaves layout off every node, so the layout engine places nodes and routes edges. It places them by the graph’s structure: to keep nodes together, put them in a frame, and to put them on a particular side, use order constraints or coordinates. Instead of scene you can send Mermaid text as mermaid (Mermaid scope).

2. Change it

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",
    "ops": [
      { "op": "createNode", "id": "queue", "nodeType": "queue", "label": "Jobs" },
      { "op": "createEdge", "id": "e2", "from": { "elementId": "api" }, "to": { "elementId": "queue" }, "label": "enqueues" }
    ]
  }'
{"id":"dgm_wjVNCDVawJzT","revision":2,"hash":"sha256:182e40...","chain":"sha256:d6d68b...","warnings":[],"changed":{"added":["queue","e2"],"updated":[],"removed":[]}}

baseRevision is the version you last read. If the diagram changed since, the call returns 409 REVISION_CONFLICT with what changed, and you re-plan. An edit that changes nothing returns noop: true and makes no version. Operations lists every operation.

3. Read it

A read answers JSON whose text field holds a compact outline. GET /v1/diagrams/payments-architecture returns this one:

dgm_wjVNCDVawJzT "Payments" r2 2026-10-04T22:55Z sha256:182e406914b7
key: payments-architecture
brief: Checkout payment services, left to right.
recent: r2 curl/8.7.1 "Add the job queue" | r1 curl/8.7.1 "First version"
outline: 3 nodes, 2 edges
  api service "API"
  db database "Ledger"
  queue queue "Jobs"
  e1: api -> db "writes"
  e2: api -> queue "enqueues"

Add ?revision=1, or ?asOf=2026-10-04 for the version current at the end of that day in UTC. ?view=dsp returns the scene JSON, and ?view=mermaid returns Mermaid you can edit and send back (not for sequence diagrams).

4. Render it

curl -s -o payments.svg "https://api.zindex.ai/v1/images/[email protected]" \
  -H "Authorization: Bearer $ZINDEX_API_KEY"

Use .png for a PNG. Any version number works in place of 2. Each version’s image is drawn when it is saved and kept, so it never changes.

Next