Docs — DiagramZu

On this page

Concepts

Three workflows this is built for

Review AI proposals

Your AI proposes an architecture. It drops a diagram here. You approve in seconds instead of reading 600 lines of prose.

Hand off to your team

Share architecture through one link. Version history records what changed and when — readable now, and by future AI agents.

Reuse in presentations

The diagram your engineers reviewed is the one your CEO or CPO drops into the deck. One source, not three.

Diagram types

The four ideas behind DiagramZu. Skim these before pointing your agent at it.

Descriptions are the agent brief

Diagrams round-trip a written purpose. Viewers see it on the public share; the next agent sees it on get_diagram.

When your AI creates or updates a diagram, ask it to write a 1–2 sentence description first. That description shows to anyone who opens the public share link as the page subhead, and it's what the next agent reads when it fetches the diagram. Treat it as the brief — the why and the what, not the how. The code is the how.

first-class

round-trip

1000-char limit

Public share links

Mint a public URL that renders the diagram view-only for anyone with the link.

Share links are how an AI-authored diagram leaves DiagramZu. The link is unguessable (22 characters), works without sign-in, shows only the rendered diagram — no editor, no code. Revoke any link at any time from the diagram's Share menu; the URL stops working immediately. Use these for team onboarding docs, architecture review threads, or as the "see an example" link in a README.

view-only

revocable

no sign-in

Version history

Snapshots are manual. Your AI passes createVersion: true on update_diagram; you click Save version in the toolbar.

There is no automatic versioning on every keystroke — that would bury you in noise. Versions are captured intentionally: by a human checkpoint, or by an agent that just made a meaningful change. Restoring a past version writes a safety snapshot of the current state first, so you never lose work. Fork as new copies a version into a separate diagram, leaving the original untouched.

manual

safety snapshot on restore

fork as new diagram

layout: "auto"

Set layout: "auto" and a deterministic classifier picks one of six concrete layouts based on the graph shape.

Tree diagrams resolve to elk.mrtree, dense cyclic graphs to elk.force, clean DAGs to dagre, and so on. The classifier runs once on save and persists the resolved value — the diagram never stores "auto", so the picture you see is reproducible. You can always override by picking a layout explicitly from the toolbar.

one-shot

6 layouts

server-resolved

Quickstart

Three steps to get your AI talking to DiagramZu.

STEP 01

Sign up

Create your space and invite teammates.

STEP 02

Create an API token

Open /app/settings/tokens and generate one. Copy it immediately — you won't see it again.

STEP 03

Add to your AI tool

Drop the snippet below into your Claude / Cursor / ChatGPT config.

MCP setup

DiagramZu exposes 8 tools over HTTP transport. Install once, then your agent has read, write, and analysis primitives across diagrams, folders, and version history.

Install

Claude Code

Run this in your terminal. Replace dz_live_xxx with your API token.

Bash

claude mcp add --transport http diagramzu https://mcp.diagramzu.ai/mcp \
  --header "Authorization: Bearer dz_live_xxx"

Claude Desktop

Edit your Claude config (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json, Windows: %APPDATA%\Claude\claude_desktop_config.json) and restart the app.

JSON

{
  "mcpServers": {
    "diagramzu": {
      "type": "http",
      "url": "https://mcp.diagramzu.ai/mcp",
      "headers": {
        "Authorization": "Bearer dz_live_xxx"
      }
    }
  }
}

Cursor

Edit ~/.cursor/mcp.json and restart Cursor.

JSON

{
  "mcpServers": {
    "diagramzu": {
      "type": "http",
      "url": "https://mcp.diagramzu.ai/mcp",
      "headers": {
        "Authorization": "Bearer dz_live_xxx"
      }
    }
  }
}

Tool reference

READ TOOLS

list_diagrams

Find diagrams in the Space.

When Call before create_diagram to avoid duplicating an existing named diagram, or after to land on the latest match.

Example

{
  "query": "DB schema",
  "sortBy": "updatedAt",
  "sortDir": "desc"
}

list_folders

List folders in the Space.

When Call when you might place a new diagram somewhere specific. If a folder named "Infra" or "Schema" exists, prefer it over the root.

Example

{}

get_diagram

Fetch one diagram by id, including the description.

When Read the description as the brief before deciding what to change.

Example

{
  "id": "dgm_abc123"
}

list_versions

List a diagram's manual snapshots, newest first.

When Use before a risky overwrite to know what restore points exist.

Example

{
  "id": "dgm_abc123"
}

get_version

Fetch one historical version of a diagram.

When Read a past snapshot to understand how the diagram evolved or to recover content the live version no longer has.

Example

{
  "id": "dgm_abc123",
  "versionId": "ver_xyz789"
}

WRITE TOOLS

create_diagram

Create a diagram in the Space.

When Always write a description first — it becomes the agent brief for future calls. Set folderId to file the diagram under a human-managed folder.

Example

{
  "title": "User signup flow",
  "description": "Auth path from /signup → verify → first login.",
  "code": "graph TD; A-->B-->C",
  "folderId": "fld_..."
}

update_diagram

Update an existing diagram's title, description, code, or styleOptions.

When Pass createVersion: true when the change is meaningful — your future self will want a restore point. versionLabel is shown in the history drawer.

Example

{
  "id": "dgm_abc123",
  "code": "graph LR; A-->B-->C-->D",
  "createVersion": true,
  "versionLabel": "added retry path"
}

ANALYSIS

analyze_diagram

Return a structural critique of a diagram — orphan nodes, high-degree hubs, cycles, disconnected components.

When Use before simplifying a complex diagram, or as a sanity check that your generated code produces a clean graph.

Example

{
  "id": "dgm_abc123"
}

REST API

Every request authenticates with a Bearer token. The base URL is https://diagramzu.ai. Replace $SPACE_ID with your space's ID (visible in the URL when you're inside the app).

Endpoints

curl · list

# List diagrams in your Space
curl -H "Authorization: Bearer $DIAGRAMZU_TOKEN" \
  https://diagramzu.ai/api/spaces/$SPACE_ID/diagrams

curl · create

# Create a new diagram
curl -X POST -H "Authorization: Bearer $DIAGRAMZU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"My diagram","code":"graph TD; A-->B"}' \
  https://diagramzu.ai/api/spaces/$SPACE_ID/diagrams

curl · update

# Update a diagram
curl -X PATCH -H "Authorization: Bearer $DIAGRAMZU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"code":"graph LR; A-->B-->C"}' \
  https://diagramzu.ai/api/spaces/$SPACE_ID/diagrams/<DIAGRAM_ID>

DIAGRAMS

Method	Path	Description
GET	`/api/spaces/[spaceId]/diagrams`	List diagrams. Same filters as list_diagrams.
POST	`/api/spaces/[spaceId]/diagrams`	Create a diagram.
GET	`/api/spaces/[spaceId]/diagrams/[id]`	Fetch one diagram.
PATCH	`/api/spaces/[spaceId]/diagrams/[id]`	Update title, code, description, or styleOptions.
DELETE	`/api/spaces/[spaceId]/diagrams/[id]`	Delete a diagram.
GET	`/api/spaces/[spaceId]/diagrams/[id]/thumbnail`	Rendered thumbnail.
GET	`/api/spaces/[spaceId]/diagrams/[id]/analysis`	Structural analysis (same as analyze_diagram).
POST	`/api/spaces/[spaceId]/diagrams/export/png`	Render arbitrary Mermaid code to PNG.

FOLDERS

Method	Path	Description
GET	`/api/spaces/[spaceId]/folders`	List folders.
POST	`/api/spaces/[spaceId]/folders`	Create a folder.
PATCH	`/api/spaces/[spaceId]/folders/[id]`	Rename or reparent a folder.
DELETE	`/api/spaces/[spaceId]/folders/[id]`	Delete a folder.

VERSIONS

Method	Path	Description
GET	`/api/spaces/[spaceId]/diagrams/[id]/versions`	List versions, newest first.
POST	`/api/spaces/[spaceId]/diagrams/[id]/versions`	Snapshot the current state.
GET	`/api/spaces/[spaceId]/diagrams/[id]/versions/[vid]`	Fetch one version.
POST	`/api/spaces/[spaceId]/diagrams/[id]/versions/[vid]/restore`	Restore a version (auto-snapshots first).
POST	`/api/spaces/[spaceId]/diagrams/[id]/versions/[vid]/fork`	Fork a version into a new diagram.

Method	Path	Description
GET	`/api/spaces/[spaceId]/diagrams/[id]/shares`	List active share links.
POST	`/api/spaces/[spaceId]/diagrams/[id]/shares`	Mint a new share link.
DELETE	`/api/spaces/[spaceId]/diagrams/[id]/shares/[shareId]`	Revoke a share link.
GET	`/public/share/[slug]`	Public read endpoint (no auth).

TOKENS

Method	Path	Description
GET	`/api/spaces/[spaceId]/tokens`	List API tokens (no secrets).
POST	`/api/spaces/[spaceId]/tokens`	Create a token. Secret returned ONCE.
DELETE	`/api/spaces/[spaceId]/tokens/[id]`	Revoke a token.

Find your Space ID

Open the API tokens page once you've signed in — your active space's ID appears next to the heading, ready to copy.