Async operations & versions

Re-layout (async)

Re-arranging a complex diagram runs as a background job. POST /diagrams/{id}/relayout?confirm=true starts the job and returns 202 with a job_id. A re-layout moves every element, so the API asks you to opt in. Without confirm=true you get a 200 with status: "confirmation_required" and nothing starts. GET /diagrams/{id}/relayout/{job_id} reports the job. Poll it with the job_id until it finishes.

# start; the response includes a job_id
curl -X POST "https://api.diagrams.so/api/v2/diagrams/d_1a2b3c/relayout?confirm=true" \
  -H "Authorization: Bearer dgz_live_YOUR_API_KEY"

# poll by job_id
curl https://api.diagrams.so/api/v2/diagrams/d_1a2b3c/relayout/job_9f2a \
  -H "Authorization: Bearer dgz_live_YOUR_API_KEY"

Poll with a short backoff, for example every 1 to 2 seconds, until status is done or failed. When it is done and applied, the reply carries the new xml, warnings and score. On Free, xml is null and the reply has xml_withheld, export_url and upgrade_url instead. See Free plan replies.

Versions

Every edit and fix creates a version, so you can review history and roll back.

Endpoint	Purpose
`GET /diagrams/{id}/versions`	List versions, newest first (paginated).
`GET /diagrams/{id}/versions/{version_id}`	Read a specific version. On Free, `xml` is `null` (why).
`POST /diagrams/{id}/revert`	Revert the diagram to a prior version.

Overview

Endpoints

Async operations & versions

Re-layout (async)

Versions

​Re-layout (async)

​Versions

Re-layout (async)

Versions