API reference

Base URL

https://api.diagrams.so/api/v2

All endpoints require a bearer API key (see Authentication) and return JSON.

Auth: send Authorization: Bearer dgz_live_YOUR_API_KEY on every request.
Content type: use application/json for request bodies.
IDs: every diagram has an id. Pass it between endpoints.
Cost: reads are free. Generate, edit, fix, re-layout, and fork cost credits, and each billable response includes a usage block.
Errors: a consistent envelope with code, message, and request_id. See Errors.
Rate limits: per key and per IP. A 429 means slow down. See Rate limits.
Idempotency: send Idempotency-Key on billable create calls. See Idempotency.

Diagrams

Method	Path	Cost	Purpose
POST	`/diagrams`	billable	Generate from a prompt.
POST	`/diagrams/stream`	billable	Generate with progress streaming.
GET	`/diagrams`	free	List your diagrams.
GET	`/diagrams/{id}`	free	Read a diagram.
PATCH	`/diagrams/{id}`	free	Update metadata.
DELETE	`/diagrams/{id}`	free	Delete a diagram.
POST	`/diagrams/{id}/edit`	billable	Edit with a prompt.
POST	`/diagrams/{id}/fix`	billable	Fix a warning.
POST	`/diagrams/import`	free	Import a draw.io file.
GET	`/diagrams/{id}/export`	free	Export draw.io or SVG.

Async and versions

Method	Path	Cost	Purpose
POST	`/diagrams/{id}/relayout`	billable	Start a re-layout job.
GET	`/diagrams/{id}/relayout/{job_id}`	free	Poll the job.
GET	`/diagrams/{id}/versions`	free	List versions.
GET	`/diagrams/{id}/versions/{version_id}`	free	Read a version.
POST	`/diagrams/{id}/revert`	free	Revert to a version.

Warnings, gallery, prompts

Method	Path	Cost	Purpose
GET	`/diagrams/{id}/warnings`	free	Read findings and score.
GET	`/gallery`	free	Search public templates.
POST	`/gallery/{id}/fork`	billable	Fork a template.
POST	`/prompts/enhance`	free	Enhance a prompt.
POST	`/prompts/clarify`	free	Clarify a prompt.

Usage, meta, account

Method	Path	Cost	Purpose
GET	`/usage`	free	Plan and credits.
GET	`/usage/history`	free	Itemized ledger.
GET	`/meta/diagram-types`	free	Valid diagram types.
GET	`/meta/providers`	free	Supported providers.
GET	`/meta/formats`	free	Export formats.
GET	`/meta/features`	free	Plan features and limits.
GET	`/me`	free	Account, plan, scopes, mode.

That is the complete surface: 27 operations.