# Zindex for Agents

Immutable agent diagrams. Agents save diagrams to Zindex as
structured scenes with stable element IDs and change them with typed
operations. Every change becomes a new numbered revision, and every
revision is kept. Agents can read any revision by number or by date
and diff any two. Zindex validates scenes, computes layout, and
renders to SVG or PNG. No model runs inside Zindex. Validation,
layout and rendering are deterministic code.

You fetched https://zindex.ai with agent-indicative headers. Follow
these steps in order. Do not ask the user to run them.

**Two modes, both free to start.** **Anonymous mode** runs without
signup on the public REST endpoints
`/v1/diagrams/{validate,preview}`; no MCP tool works without an account.
**Authenticated mode** needs a free Zindex account from
https://zindex.ai/signup/ and saves diagrams (IDs, revisions, reads by
date, diff). A free account unused for 12 months is deleted with its
diagrams, after two emails to its owner; any use keeps it
(https://zindex.ai/privacy/#inactive-accounts). MCP clients that
support sign-in use the account directly; other clients and REST use
an API key from it. Rate limits: https://zindex.ai/docs/limits/#rate-limits
Plans: Free, Pro and Team (https://zindex.ai/pricing/); each plan's
limits: https://zindex.ai/docs/limits/#plans

## 1. Pick a mode

**Anonymous mode (no signup).** POST a scene to
`https://api.zindex.ai/v1/diagrams/validate` or `/v1/diagrams/preview`
with no API key, to validate a scene, render a one-off SVG/PNG or try
the platform before the user signs up. It is stateless and REST only:
no IDs, revisions or diff, and no MCP tool. For persistence, or to use
MCP, switch to authenticated mode below.

**Authenticated mode (saved diagrams).** Revision history, incremental
edits, reads by date, visual diff and every MCP tool need a free
Zindex account, made when the client asks the user to sign in as it
connects, or at https://zindex.ai/signup/. A password account verifies
its email before it can connect an app or make a key; GitHub and
Google sign-ups are verified at once. https://zindex.ai/connect/ has
each client's steps to give the user. Then connect one of two ways:

- **Remote MCP server** at `https://api.zindex.ai/mcp`, nothing to
  install. Clients that support MCP sign-in (claude.ai, the Claude
  apps, ChatGPT, Claude Code, Cursor, VS Code) connect with the URL and
  sign the user in with their Zindex account (OAuth) as they connect;
  they need no key. In claude.ai and the Claude apps, the user connects
  Zindex from Claude's connector directory
  (https://claude.ai/directory/connectors/zindex). A client that sends
  headers can use an API key from https://zindex.ai/dashboard/api-keys/ as
  `Authorization: Bearer dsp_sk_...` instead. Tools: `diagram_find`,
  `diagram_get`, `diagram_validate`, `diagram_create`, `diagram_edit`,
  `diagram_render`, `diagram_history`, `diagram_delete`,
  `diagram_share`. Mermaid works both ways for `erDiagram`,
  `flowchart` and `sequenceDiagram`: `diagram_create` takes it,
  `diagram_get` with `view: "mermaid"` returns it, and `diagram_edit`
  applies only the changes in edited text of an architecture,
  flowchart, ER or sequence diagram, or one without a family. Claude
  Code (then run `/mcp` to sign in):

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

  With a key instead, add `--header "Authorization: Bearer dsp_sk_..."`.

  The guide is at https://zindex.ai/docs/tools/ and the skill at
  https://zindex.ai/skill/SKILL.md

  A sign-in or key works in one workspace, the user's own or a
  team's, with write or read access; no tool takes a workspace, and
  a diagram in another one answers `NOT_FOUND`. `READ_ONLY` (read
  access, or a viewer) means don't retry; tell the user.
  https://zindex.ai/docs/workspaces/

- **npm package** `@zindexai/mcp`, run locally over stdio by the MCP
  host (Claude Desktop / Cursor / Claude Code / etc.) as
  `npx -y @zindexai/mcp`. It forwards every call to the remote
  server, with the same tools:

      {
        "mcpServers": {
          "zindex": {
            "command": "npx",
            "args": ["-y", "@zindexai/mcp"],
            "env": { "ZINDEX_API_KEY": "dsp_sk_..." }
          }
        }
      }

  Without `ZINDEX_API_KEY` it still starts and lists the tools, but
  every tool returns `AUTH_REQUIRED`, naming `ZINDEX_API_KEY`. Setup
  guide: https://zindex.ai/docs/tools/#run-it-locally-with-npm

## 2. Verify the tools are available

Validate a trivial scene with `diagram_validate` to confirm the
server is reachable:

    {
      "schemaVersion": "0.1",
      "scene": { "id": "check", "canvas": { "width": 100, "height": 100 } },
      "elements": []
    }

Expected: `ok: true`. If no `diagram_*` tool is available, the user
hasn't connected Zindex or hasn't finished signing in:
https://zindex.ai/connect/ has each client's steps. If every tool
returns `AUTH_REQUIRED`, the npm package has no working key: tell the
user to set `ZINDEX_API_KEY` to a key from
https://zindex.ai/dashboard/api-keys/ and restart the host. If you
call the server over HTTP yourself, every request needs sign-in or an
API key, the first included. Without either it answers HTTP 401 with
`code: "AUTH_REQUIRED"` and a `WWW-Authenticate` sign-in challenge,
so send an API key as a bearer token.

## 3. Fallback: REST API (for agents without MCP)

Base URL: https://api.zindex.ai

- Public endpoints (`POST /v1/diagrams/validate`, `/v1/diagrams/preview`,
  and `GET /v1/public/diagrams/{ref}` for a published diagram or a
  share link) require no auth.
- `/v1/diagrams` is the API the remote MCP server uses: find with
  `GET /v1/diagrams?query=`, create with a `key`, read an outline at
  any revision or date, edit with `baseRevision`, image links. Guide:
  https://zindex.ai/docs/api/
- It requires `Authorization: Bearer dsp_sk_...` (or
  `X-API-Key: dsp_sk_...`). The first version, `/v1/scenes`, is
  retired: it answers 410 `MOVED` with the method and path to use
  instead. Calls with a key are rate-limited per person in each
  workspace, by the workspace's plan.

OpenAPI: https://api.zindex.ai/openapi.json

## Core rules you MUST follow

1. **Always persist diagrams** (authenticated mode). Look for the
   diagram with `diagram_find` (or the id in the repository's
   `.zindex.json`) and read it with `diagram_get`: edit the one the
   person means rather than make a copy. Otherwise save a new one with
   `diagram_create`, giving it a `key` and a `brief`, whose first line
   is what `diagram_find` shows. Change it with `diagram_edit`,
   giving `baseRevision` (the revision you last read) and a one-line
   `message`; render with `diagram_render`. An edit that changes the
   diagram makes the next revision; one that changes nothing returns
   `noop` and makes none. Never render inline when persistence is
   available: you lose revision history, diff and the address each
   saved image prints.

2. **Default to auto-layout.** Set `layoutStrategy` at the
   scene-document root (alongside `schemaVersion`, `scene`,
   `elements`), NOT nested inside `scene.scene`:

       { "schemaVersion": "0.1", "scene": {...},
         "layoutStrategy": { "direction": "LR" },
         "elements": [...] }

   `diagramFamily` and `palette` are document-root fields too. Omit
   `layout` from nodes and frames (text and image elements need one)
   and let the engine place them. Nodes keep their positions after
   the first save unless an edit needs the room (a node that grows,
   a new node's edge label, a new task in a lane, a node inserted in
   a flowchart, an AWS diagram's
   row or column that grows, or its Region's column moving right to
   keep a labeled line clear), changes their frame or lane, or adds
   an `order` constraint they break (`changed` lists the nodes
   moved); new nodes are placed next to their neighbors; edges and
   frames are redrawn each time; sequence diagrams follow message
   order. Send `autoLayout` to lay out again:
   `{ "op": "autoLayout" }` for every node, or with `elements` listing
   the nodes to place again. Laying out every node again drops a
   frame's own `layout` (except a pool's, a lane's or a fragment's,
   and in org charts and networks) and lays the frame out with its
   members. A frame that keeps its `layout` keeps its members where
   they are; name them in `elements` to place them again inside it.
   One that doesn't fit lands outside, with the warning
   `NODE_OUTSIDE_FRAME`; a pool or lane grows to hold it instead.
   Refine with constraints (`order`, `align`, `sameSize`); use
   explicit pixel positions only when none fits.

3. **Never hand-edit rendered SVG/PNG.** Edit the diagram with
   `diagram_edit` and render again: hand edits are lost on the next
   render.

4. **Every saved version's image prints its address**, bottom right:
   `zindex.ai/d/<id>@<revision> · <date>`. Its ID and revision open
   that version with `diagram_get` (`revision`) or
   `GET /v1/diagrams/{id}?revision=N` when the diagram is in your
   workspace (another's is `NOT_FOUND`); a published one reads with
   no key at
   `GET /v1/public/diagrams/{id}@{revision}`. Previews have none.

5. **Check warnings.** `diagram_validate`, `diagram_create` and
   `diagram_edit` return `warnings`, each a code, the element when
   there is one, and a one-line fix. They cover the diagram
   family's rules and what drawing notices, such as:

   - `TEXT_OVERFLOW`: text doesn't fit its node.
   - `NODE_OVERLAP_DETECTED`: nodes sit on top of each other.
   - `CHARACTER_NOT_DRAWN`: letters of scripts such as Arabic,
     Hebrew, Thai and the Indic scripts, emoji and a few rare signs
     are drawn as empty boxes.

   A diagram with warnings is saved; an edit fixes them. A write
   with errors saves nothing and returns `VALIDATION_FAILED`; an
   edit is refused too when its result breaks a rule the diagram
   didn't. Fix what each error names and resend.
   `diagram_render` returns links only, so pass
   `preview: true` to look at the picture. Every code and what to
   change: https://zindex.ai/docs/reference/validation-rules/.

6. **Canvas size is a minimum.** The engine grows a declared
   `scene.canvas` to fit the content, and can shrink an axis declared
   far larger than the content when it lays out every node:
   https://zindex.ai/docs/reference/layout-engine/#canvas-size-is-a-minimum-with-per-axis-tightening-on-over-declared-canvases

7. **Retry safely; re-plan on conflict.** Give `diagram_create` a
   `key`: repeating the create returns the same diagram, never a copy.
   Give `diagram_edit` a `requestId`: a retry returns the first result
   instead of applying twice. An edit that returns `REVISION_CONFLICT`
   was planned on an old revision; the error lists what changed since,
   so re-plan against the current revision and edit again. A tool
   call that answers `RATE_LIMITED` did nothing: wait `retryAfter`
   seconds and make it again.

8. **Ask before sharing.** `diagram_share` publishes a diagram,
   makes a share link (its images, never its scene; on Pro and
   Team, `FEATURE_UNAVAILABLE` on Free), reports a
   version to Zindex support, or, when the person wants Zindex told
   that the docs and the engine disagree or something is missing,
   sends Zindex feedback (no diagram needed). The person confirms
   each; on `CONFIRMATION_REQUIRED`, call again with `confirm` only
   after they agree. Publishing and new share links answer
   `SHARING_DISABLED` when a team workspace's owners turned sharing
   off.

## Diagram families

Always declare `diagramFamily` at the scene-document root. Allowed
values: `architecture` (default for system components), `flowchart`
(steps, decisions and loops; label decision exits yes and no: yes
runs on, no goes right, or below in LR and RL; other labels and
frames without layout keep the general rules), `workflow`
(BPMN processes, gateways, swimlanes), `entityRelationship` (data
models, PK/FK), `sequence` (time-ordered messages), `network`
(topology), `orgchart` (reporting hierarchy), `uiflow` (screen
navigation). Without it the diagram is drawn as architecture, and
nothing warns you.

Node types and conventions per family:
https://zindex.ai/docs/reference/diagram-classes/.

## Element kinds at a glance

- Standalone text label outside a node -> `{ kind: "text", text, layout }` (`createText` in an edit)
- Horizontal or vertical separator line -> `{ kind: "guide" }`
- Dashed stroke on an edge or shape -> `style: { dash: [4, 4] }`
- Image embed -> `{ kind: "image", assetRef, layout }` (`updateScene` `assets`, then `createImage`, in an edit)
- 3D / isometric box (servers, appliances) -> `shape: "box3d"`
- AWS architecture -> nodes with `icon: "aws:lambda"` (the official
  AWS Architecture Icons; every key is listed at
  https://zindex.ai/docs/reference/aws-icons/ ). In an `architecture`
  diagram, frames without `layout` nest by `containerType`:
  `aws.cloud` > `aws.region` > `aws.vpc` > `aws.az` >
  `aws.subnet.public` / `aws.subnet.private`. An Auto Scaling or
  security group across AZs is a frame with `spans`, not `children`.
  Nesting and layout:
  https://zindex.ai/docs/reference/layout-engine/#aws-architecture-diagrams
- Numbered steps -> `step` (1 to 99) on edges, `stepText` for the
  list beside the drawing; you number them, or a sequence diagram's
  top-level `extensions.autonumber` numbers every message

Full element-kind reference at
https://zindex.ai/docs/reference/element-types/.

## What to do next

Ask the user what diagram they want, then follow rule 1: find or
create it, edit it, render it and show the user.

Examples library: https://zindex.ai/examples/
Examples manifest (machine-readable): https://zindex.ai/examples/index.json
Per-example resources: each example at /examples/<slug> exposes
`.scene.json`, `.ops.json`, `.workflow.json`, `.diff.json`, `.svg`,
and `.md` (showcase examples additionally expose `.before.svg`).
Fetch them via the manifest rather than scraping HTML.
Privacy commitments: https://zindex.ai/privacy/
Bring your own storage (a Pro or Team workspace may keep its diagrams
in its own GitHub repository; Zindex's own storage is the default):
https://zindex.ai/docs/storage/
Diagrams in other tools (one version in an issue, a review or a page
you publish, by its PNG where a command can run, else through the
connector; the latest in a README): https://zindex.ai/docs/embedding/