Diagrams

Change a diagram (make the next revision)

Applies an edit and keeps the old version: every change appends a revision and nothing is overwritten. Give exactly one of ops, mermaid, restoreRevision, or brief alone (brief may also accompany ops or mermaid). An edit that changes nothing returns noop: true. A retry with the same requestId returns the first result (replayed: true). A stale baseRevision returns 409 with the current revision and what changed, unless the current content already equals what the edit asked for (then noop).

post/v1/diagrams/{id}/revisions

Request

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

Path parameters

idstring required

The diagram's ID or 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

baseRevisioninteger required

The revision you last read

messagestring

One line on what the edit does and why

requestIdstring

Your ID for this edit, e.g. a UUID

mermaidstring

The whole diagram as Mermaid, usually read with view=mermaid and edited. The server diffs it against baseRevision into operations: nodes and edges are matched by ID, so unchanged elements keep their IDs and history, and nodes and edges left out are deleted. Frames, groups and text are never changed by a Mermaid edit; an edge to a subgraph that shows a frame or group is an edge to that frame or group. Works on architecture and entity-relationship diagrams; not with ops or restoreRevision.

briefstring nullable

Replace the brief; null removes it

Response

The write envelope

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.