---
title: "Read a diagram"
method: GET
path: "/v1/diagrams/{id}"
tags: ["Diagrams"]
---

# Read a diagram

`GET /v1/diagrams/{id}`

## Request

- Base URL: `https://api.zindex.ai`
- URL: `https://api.zindex.ai/v1/diagrams/{id}`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Returns the outline by default: a header (id, title, revision, time, short hash), key, brief and recent versions, then one element per line nested by container and edges as 'id: from -> to "label"'. view=dsp returns the scene document as written instead: values the engine infers while drawing, such as an ER edge end's cardinality from its column, aren't in it. revision or asOf reads an earlier version. knownRevision returns { unchanged: true } or only the changes since that revision. elements (comma-separated IDs) limits the outline to those elements and their neighbors.

## Path parameters

- `id` string, required

## Query parameters

- `view` 'outline' | 'dsp' | 'mermaid'
- `revision` integer
- `asOf` string
- `knownRevision` integer
- `elements` string
- `cursor` string

## Response `200`

The outline ({ id, revision, text, nextCursor? }), the scene ({ id, key, revision, hash, chain, createdAt, visibility, madePublicAt?, scene }, with madePublicAt while the diagram is public), the Mermaid ({ id, revision, hash, chain, mermaid, notes? }, where notes say what Mermaid can't show), or { unchanged: true, id, revision, hash, chain }. hash and chain are the version's content and chain hashes, as in DiagramWrite.

- object

## Other responses

- `400`: Invalid revision, asOf or knownRevision
- `401`: Missing or invalid API key. Response includes a `code` field that distinguishes the failure mode so clients (dashboard, MCP server) can render actionable copy: `AUTH_REQUIRED` (no key or session was sent), `API_KEY_INVALID` (key not found), `API_KEY_REVOKED` (key was revoked, or its person is no longer in its workspace), `API_KEY_EXPIRED` (key passed its expires_at), and for the site's session cookie `SESSION_EXPIRED` (past its 24 hours), `SESSION_REVOKED` (the account's sessions were ended, for example by a password reset) and `SESSION_INVALID` (not a session this server signed).
- `404`: NOT_FOUND (another workspace's diagram answers the same way) or NO_REVISION_AS_OF
- `422`: VIEW_UNAVAILABLE: this diagram can't be read in that view (sequence diagrams have no Mermaid view yet)
- `429`: RATE_LIMITED: over the request rate limit (see Rate Limiting). Wait retryAfter seconds (also the Retry-After header), then try again.

---

[API](https://skmtc.dev/zindex/apis/zindex-api.md) · [All operations](https://skmtc.dev/zindex/apis/zindex-api/llms.txt) · [OpenAPI document](https://skmtc.dev/zindex/apis/zindex-api/revisions/1d21bd5bbf8e?raw)