Quickstart

Zindex is agent-native diagram state infrastructure - a stateful diagram runtime for AI agents. Create architecture diagrams, ERDs, workflows, org charts, and topology maps from structured data, then patch, validate, diff, and render them as systems change. Agents send structured operations through the Diagram Scene Protocol (DSP) and the platform validates, normalizes, and renders durable scene state rather than one-shot output.

Tip: Skip this tutorial and drop in the canonical agent front door as a ready-to-paste system prompt. Works with any LLM or agent framework, and stays in sync with platform changes automatically.

Building an agent integration? Read How AI Agents Should Use Zindex for the recommended workflow for scene creation, incremental edits, revision handling, and rendering.

Choose your integration

If you’re using Claude Desktop, Cursor, or another MCP-compatible environment, see MCP Setup.

Option 2: HTTP API

Create diagrams by calling the Zindex API directly.

1. Create a scene

curl -s https://api.zindex.ai/v1/scenes \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "schemaVersion": "0.1",
    "scene": {
      "id": "my-diagram",
      "title": "My First Diagram",
      "units": "px",
      "canvas": { "width": 800, "height": 400, "background": "#ffffff" }
    },
    "elements": []
  }'

Tip: For automatic positioning, add "layoutStrategy": { "algorithm": "hierarchical", "direction": "TB" } to the scene and omit layout from nodes. The layout engine computes positions, edge routes, and label placement automatically using a Sugiyama-style hierarchical pipeline.

2. Add nodes and edges

curl -s https://api.zindex.ai/v1/scenes/my-diagram/applyOps \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "schemaVersion": "0.1",
    "sceneId": "my-diagram",
    "baseRevision": 1,
    "ops": [
      {
        "op": "createNode",
        "id": "api",
        "nodeType": "service",
        "shape": "roundedRect",
        "label": "API Gateway",
        "layout": { "mode": "absolute", "x": 50, "y": 150, "width": 180, "height": 70 }
      },
      {
        "op": "createNode",
        "id": "db",
        "nodeType": "database",
        "shape": "cylinder",
        "label": "Database",
        "layout": { "mode": "absolute", "x": 350, "y": 140, "width": 150, "height": 90 }
      },
      {
        "op": "createEdge",
        "id": "e1",
        "from": { "elementId": "api" },
        "to": { "elementId": "db" },
        "label": "queries"
      }
    ]
  }'

3. Render to SVG

curl -s https://api.zindex.ai/v1/scenes/my-diagram/render \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "format": "svg" }'

Tip: Add "theme": "dark" to the render request for dark mode output, "theme": "blueprint" for a technical engineering style, or "theme": "sketch" for a hand-drawn whiteboard style. See Rendering and themes for all options.

Automatic validation

Every call to POST /v1/scenes and POST /v1/scenes/:id/applyOps runs semantic validation automatically. If the scene or operations contain errors, the request is rejected with 422 and a list of diagnostics - no need to call the validate endpoint separately.

To skip validation during incremental assembly, add "validate": false to the request body. Only use this for intermediate draft states - always re-enable validation before final render or handoff.

The POST /v1/scenes/validate endpoint remains available for dry-run checks without persistence.

Core concepts

What’s next