Diagrams

Save a diagram

Saves a new diagram from a DSP scene document. Zindex mints the ID (any scene.id sent is ignored). key is your own name for it, unique among the workspace's live diagrams: repeating your own create with the same key and content returns the existing diagram (200, created: false) instead of a copy, so retries are safe. Every version is kept until you delete the diagram or its workspace is deleted. Send Mermaid text as mermaid instead of scene to import it.

post/v1/diagrams

Request

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

Headers

X-Zindex-Clientstring

Your client's name and version, such as my-agent/1.2, kept as the client that made the revision, report or feedback item, as history and outlines show it. The first 100 characters are kept. Without it, the User-Agent's first product token is used.

Request body

keystring

Your stable name for the diagram, e.g. payments-architecture

briefstring

Context for the next agent: what the diagram shows, conventions to keep, decisions made

messagestring

One line on why the diagram was made

mermaidstring

Mermaid text, instead of scene: an erDiagram or a flowchart (graph). Converted deterministically: element IDs come from the Mermaid IDs and the same text always gives the same diagram. Subgraphs, edges to them and styles are left out for now and listed in warnings; other diagram types are refused with UNSUPPORTED_DIAGRAM_TYPE, and syntax errors return PARSE_ERROR with line and column.

Response

A retried create: the existing diagram with the same key and content (created: false)

idstring required

The diagram ID, e.g. dgm_7Q2kD9a1B2c3

keystring nullable
revisioninteger required
hashstring required

sha256: of the RFC 8785 canonical content: the scene as view=dsp and the export return it, without computed, the engine's drawing output. The node positions in each node's layout are content, so they count.

chainstring nullable required

The version's chain hash: sha256: of "zindex-chain/1\n" + the previous kept version's chain hash (empty for the first kept version) + "\n" + this version's content hash + "\n" + its stored image's hash, each as lowercase hex without sha256:. It covers every kept version up to this one. null until Zindex has computed it, normally when the version is saved; a render, an export or the next edit computes a missing one. Reads and the history never compute it. https://zindex.ai/docs/concepts/#verifying

createdboolean

false when a create with the same key and content returned the existing diagram

noopboolean

The edit changed nothing; revision is the current one

replayedboolean

The requestId matched an earlier edit; this is its result

Changes

No recorded changes to this operation across all 1 revision of this API.