Revisions and Conflicts

Every persisted scene in zindex has an immutable revision history. Understanding revisions is essential for safe multi-step agent workflows.

For the full agent behavioural guide, fetch the canonical agent front door with Accept: text/markdown for the ready-to-paste system prompt.

How revisions work

The baseRevision field

When applying operations, you must include baseRevision in the request. You can also include an optional message describing what this batch does (like a git commit message):

{
  "schemaVersion": "0.1",
  "sceneId": "my-scene",
  "baseRevision": 3,
  "ops": [ ... ],
  "message": "Added cache layer between API and database"
}

baseRevision declares which revision your ops were planned against. The server checks that baseRevision matches the scene’s current revision before applying.

Conflict detection (409)

If another writer updated the scene between your read and your write, baseRevision won’t match. The server returns 409 Conflict:

{ "error": "Revision conflict", "currentRevision": 5 }

This prevents stale writes from silently overwriting concurrent changes.

Conflict recovery pattern

  1. Read the latest scene: GET /v1/scenes/{id}
  2. Compare your intended change to the current state
  3. Re-plan a fresh minimal patch against the new revision
  4. Apply with the new baseRevision

Do not:

Revision list with metadata

GET /v1/scenes/:id/revisions returns rich metadata per revision:

{
  "sceneId": "my-diagram",
  "currentRevision": 3,
  "revisions": [
    { "revision": 3, "createdAt": "2026-04-01T12:00:00Z", "message": "Added cache layer", "createdByKind": "agent", "createdVia": "mcp", "proposalId": "prop_1c2d...", "approvedByUserId": "user_9f...", "summary": { "added": 1, "removed": 0, "modified": 1 } },
    { "revision": 2, "createdAt": "2026-04-01T11:30:00Z", "message": "Initial structure", "createdByKind": "human", "createdVia": "api", "proposalId": null, "approvedByUserId": null, "summary": { "added": 5, "removed": 0, "modified": 0 } },
    { "revision": 1, "createdAt": "2026-04-01T11:00:00Z", "message": null, "createdByKind": null, "createdVia": null, "proposalId": null, "approvedByUserId": null, "summary": null }
  ]
}

Each revision includes:

Point-in-time reads (“as of”)

Because every revision is timestamped, any instant resolves to a revision. GET /v1/scenes/:id?asOf=2026-06-30 returns the scene as it stood at the END of that date (UTC); a full ISO timestamp is used exactly. The same parameter works on the evidence export, and GET /v1/workspaces/audit?asOf= lists every owned scene with its as-of revision - the data behind the dashboard’s Audit tab. A scene that did not exist yet returns 404 with code NO_REVISION_AS_OF. asOf and revision are mutually exclusive.

Revision watermark on rendered output

When rendering a persisted scene, the output includes metadata in the bottom corners:

zindex.ai                          my-diagram | Rev 5 - 2026-04-01

The watermark is binary - full metadata or nothing:

The watermark color adapts to the canvas background:

The scene ID in the watermark makes every rendered artifact self-identifying. An agent seeing a diagram can read the scene ID and call GET /v1/scenes/:id or dsp_get_scene to retrieve and edit it.

Diffing revisions

Compare any two revisions to see exactly what changed:

GET /v1/scenes/:id/diff?from=1&to=3

The to parameter is optional - defaults to the current (latest) revision.

Response:

{
  "sceneId": "my-diagram",
  "fromRevision": 1,
  "toRevision": 3,
  "summary": { "added": 2, "removed": 1, "modified": 1 },
  "added": ["node-x", "edge-y"],
  "removed": ["node-old"],
  "modified": ["node-a"],
  "changedConstraintIds": []
}

Use diff to:

Visual diff rendering

Render a color-coded diagram showing changes between revisions. Pass diff.fromRevision on the render request:

POST /v1/scenes/my-diagram/render
{ "format": "svg", "diff": { "fromRevision": 1 } }

Added elements render in green, removed as red dashed ghosts, modified in amber, unchanged muted. A color legend is included. See Rendering: Visual diff for details.

Best practices

Retrieving previous revisions

GET /v1/scenes/my-scene?revision=1

Returns the scene as it was at revision 1. Useful for: