# Zindex for Agents
Agent-native diagram state infrastructure. Zindex is a stateful diagram
runtime for AI agents - create architecture diagrams, ERDs, workflows,
sequence diagrams, org charts, and topology maps from structured data,
then patch, validate, diff, and render them as systems change. Not a whiteboard.
Not a Mermaid clone. A database-like backend for diagrams with stable
IDs, typed operations, semantic validation, immutable revisions,
auto-layout, and SVG/PNG rendering.
You are here because 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 (public endpoints `/v1/scenes/{validate,render,normalize}`,
rate-limited 30/min per IP). **Authenticated mode** takes a free API
key from https://zindex.ai/signup and unlocks persisted scenes
(sceneIds, revisions, diff, full MCP tool set). Paid plans are for
production scale. Both modes detailed below.
## 1. Pick a mode
**Anonymous mode (no signup).** POST a scene to
`https://api.zindex.ai/v1/scenes/validate`, `/render`, or `/normalize`
with no API key. Use this to validate a scene, render a one-off
SVG/PNG, or feasibility-test the platform before the user signs up.
Anonymous mode is stateless: no scene IDs, no revisions, no diff.
When the user wants persistence, switch to authenticated mode below.
**Authenticated mode (persisted scenes).** For revision history,
incremental edits, sceneId-based references, visual diff, and the full
MCP tool set, the user needs an API key. Free key takes 30 seconds at
https://zindex.ai/signup. The Zindex MCP server is a thin HTTP client
to https://api.zindex.ai and uses the key for every persisted operation.
Add the key to the user's MCP host config (Claude Desktop / Cursor /
Claude Code / etc.):
{
"mcpServers": {
"zindex": {
"command": "npx",
"args": ["@zindex-ai/mcp"],
"env": {
"ZINDEX_API_KEY": "dsp_sk_..."
}
}
}
}
The MCP server also runs in anonymous mode if installed without
`ZINDEX_API_KEY` - omit the `env` block entirely and the server
starts with the public-endpoint tools only (`dsp_validate_scene`,
`dsp_normalize_scene`, `dsp_render_scene` with inline scenes only).
Same install snippet, same npm package, no signup.
Setup guide: https://zindex.ai/docs/getting-started/mcp-setup/
## 2. Verify the tools are available
Call `dsp_validate_scene` with a trivial scene to confirm the MCP
server is reachable:
{
"schemaVersion": "0.1",
"scene": { "id": "check", "canvas": { "width": 100, "height": 100 } },
"elements": []
}
Expected: `{ "ok": true, "diagnostics": [] }`. Call `tools/list` to
see which mode the server started in: if `dsp_create_scene` appears,
it is in authenticated mode; if you only see the public-endpoint
tools, it is in anonymous mode.
## 3. Fallback: REST API (for agents without MCP)
Base URL: https://api.zindex.ai
- Public endpoints (`POST /v1/scenes/validate`, `/render`,
`/normalize`) require no auth. Rate-limited 30/min per IP. This is
anonymous mode from step 1, exposed over plain HTTP.
- Authenticated endpoints (everything else: scene CRUD, revisions,
diff, applyOps, persisted render) require
`Authorization: Bearer dsp_sk_...` (or `X-API-Key: dsp_sk_...`).
Rate-limited per the user's workspace plan (60/min on the free tier).
Full reference: https://zindex.ai/docs/getting-started/agent-usage/
OpenAPI: https://api.zindex.ai/openapi.json
## Core rules you MUST follow
1. **Always persist scenes** (authenticated mode). Call
`dsp_create_scene` first, then `dsp_apply_ops` for edits (each call
creates a new revision), then `dsp_render_scene({ sceneId })` to
render. Never render inline when persistence is available - you
lose revision history, diff, and watermark traceability.
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": { "algorithm": "hierarchical", "direction": "LR" },
"elements": [...] }
Same convention for `diagramFamily` and `palette` - all three are
document-root fields. Omit `layout` from elements and let the
engine place them. Use constraints (`order`, `align`, `sameSize`)
to refine; do not fall back to explicit pixel positions unless a
constraint genuinely does not fit.
3. **Never hand-edit rendered SVG/PNG.** Edit the scene with
`dsp_apply_ops` and re-render. Hand edits are lost on the next
render and break the scene/revision model.
4. **Keep watermarks on during iteration.** `showRevision: true` is
the default. Stamps scene-id, revision, and date on every render
so output is traceable back to the source.
5. **Check diagnostics after every render.** The response's
`diagnostics` array reports issues with structured `data` fields
you can act on programmatically. Categories: text overflow
(resize element), canvas sizing (auto-extended / auto-tightened /
content-offset), edge-label auto-promotion or fan-in suppression
(preserve via `style.forceLabel: true`), missing column / family
declaration. For per-code recovery prose, payload shape, and
severity, see https://zindex.ai/docs/reference/rendering/#render-diagnostics.
6. **Canvas size is a minimum, with one aspect-ratio guard.**
Declared `scene.canvas` dimensions act as a lower bound; the
engine auto-extends to fit content (and auto-tightens height when
wide-and-flat content with excess vertical slack would otherwise
render with 60-70% whitespace). Bigger declared canvas = more
breathing room (engine spreads to fill); smaller declared canvas
= tighter layout up to the auto-extension floor. Full mechanism
at https://zindex.ai/docs/reference/layout-engine/.
## Diagram families
Always declare `diagramFamily` at the scene-document root. Allowed
values: `architecture` (default for system components), `workflow`
(BPMN processes, gateways, swimlanes), `entityRelationship` (data
models with PK/FK), `sequence` (time-ordered messages), `network`
(topology), `orgchart` (reporting hierarchy), `uiflow` (screen
navigation). Omitting it triggers a `MISSING_DIAGRAM_FAMILY` info
diagnostic and forces the generic-flowchart base case.
For the family-selection decision tree (when to reach for which
family based on scene structure), family-specific node/edge types,
and BPMN/UML conventions, see
https://zindex.ai/docs/reference/diagram-classes/.
## Element kinds at a glance
- Standalone text label outside a node -> `{ kind: "text" }`
- Horizontal or vertical separator line -> `{ kind: "guide" }`
- Dashed stroke on an edge or shape -> `style: { dash: [4, 4] }`
- Image embed -> `{ kind: "image" }`
- 3D / isometric box (servers, appliances) -> `shape: "box3d"`
- Cloud-provider service icon -> `icon: "aws:lambda"` (or `gcp:*`,
`azure:*`) - renders icon-only, composites cleanly inside colored
network-boundary frames
Full element-kind reference (properties, families, examples) at
https://zindex.ai/docs/reference/element-types/.
## What to do next
Ask the user what diagram they want. Always declare `diagramFamily`
at the scene-document root. Create the scene, render it, show the
user, and iterate with ops.
Full long-form guide: https://zindex.ai/docs/getting-started/agent-usage/
Examples library (executable patterns + agent resources): https://zindex.ai/examples/
Examples manifest (machine-readable, for programmatic discovery): https://zindex.ai/examples/index.json
Per-example resources: each example at /examples/<slug> exposes
`.scene.json`, `.ops.json`, `.workflow.json`, `.diff.json`,
`.github-actions.yml`, `.svg`, and `.md` (showcase examples
additionally expose `.before.svg`). Fetch directly via the manifest
rather than scraping HTML.
Privacy commitments: https://zindex.ai/privacy (scene content
encrypted at rest, no LLM subprocessors, anonymize before sharing
with support, atomic deletion).