API Endpoints

The Zindex API is served at https://api.zindex.ai (or http://localhost:3000 for local development).

All endpoints require authentication via Authorization: Bearer <API_KEY> header unless AUTH_DISABLED=true.

Scenes

Create scene

POST /v1/scenes

{
  "schemaVersion": "0.1",
  "scene": {
    "id": "my-diagram",
    "title": "Architecture",
    "units": "px",
    "canvas": { "width": 1200, "height": 800, "background": "#ffffff" }
  },
  "elements": []
}

Response: { "sceneId": "my-diagram", "revision": 1 }

Get scene

GET /v1/scenes/:sceneId
GET /v1/scenes/:sceneId?revision=2

Returns the scene at the latest or specified revision.

Apply operations

POST /v1/scenes/:sceneId/applyOps

{
  "schemaVersion": "0.1",
  "sceneId": "my-diagram",
  "baseRevision": 1,
  "ops": [ ... ]
}

Response: { "sceneId": "...", "revision": 2, "applied": 3, "diagnostics": [] }

Returns 409 if baseRevision doesn’t match the current revision (conflict).

Render scene

POST /v1/scenes/:sceneId/render

{ "format": "svg" }

Formats: svg, png, excalidraw

Response:

• SVG: { "output": { "mimeType": "image/svg+xml", "content": "<svg>..." } }
• PNG: { "output": { "mimeType": "image/png", "contentBase64": "..." } }

Validation

Validate scene (stateless)

POST /v1/scenes/validate

Accepts a full scene document. Returns validation diagnostics without persisting.

{ "valid": true, "diagnostics": [] }

Authentication

Create API key

POST /v1/auth/keys

{ "name": "My Key" }

Response: { "id": "...", "key": "dsp_sk_...", "name": "My Key" }

The key is shown only once in the response.

Health

Health check

GET /health

No authentication required. Returns { "status": "ok" }.