Diagrams

All paths are relative to https://api.diagrams.so/api/v2 and require a bearer key.

Generate a diagram

Create a diagram from a prompt. Generation is AI-backed and can take 30 seconds or more; for live progress use streaming, and set a generous client timeout.

Body field	Type	Notes
`prompt`	string (required)	What to draw.
`cloud_provider`	string	`aws`, `azure`, `gcp`, or `general`. See Meta.
`diagram_type`	string	e.g. `architecture`, or `auto` to pick the type from the prompt. Left out, it is `architecture` today; a later server setting may make it `auto`. A type you send is always kept. See Meta.
`opinionated`	boolean	Apply Well-Architected best practices while generating.

curl https://api.diagrams.so/api/v2/diagrams \
  -H "Authorization: Bearer dgz_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7f1c…-unique" \
  -d '{"prompt": "A serverless image pipeline on AWS", "cloud_provider": "aws"}'

Response (Paid)

{
  "id": "d_1a2b3c",
  "title": "Serverless image pipeline",
  "cloud_provider": "aws",
  "diagram_type": "architecture",
  "is_public": false,
  "xml": "<mxGraphModel> … </mxGraphModel>",
  "score": { "score": 78, "tier": "good", "warning_count": 1, "recoverable_points": 22, "breakdown": [] },
  "warnings": [
    { "type": "reliability", "component": "S3", "message": "Enable versioning on the bucket." }
  ],
  "usage": { "credits_charged": 1, "credits_remaining": -1, "tier": "paid" }
}

New diagrams start private (is_public: false) on every plan. Make one public with PATCH /diagrams/{id}. The usage block is kept for compatibility. Nothing is metered: credits_remaining is always -1, and credits_charged is an internal cost figure, not a charge. See Plans & pricing.

Free plan replies

On Free, every reply that would carry the draw.io XML carries xml: null and four extra fields. This applies to generate, the stream’s complete event, get, get version, edit, fix and the re-layout result.

Response (Free)

{
  "id": "d_1a2b3c",
  "title": "Serverless image pipeline",
  "xml": null,
  "xml_withheld": true,
  "xml_withheld_reason": "UPGRADE_REQUIRED",
  "export_url": "/api/v2/diagrams/d_1a2b3c/export?format=svg",
  "upgrade_url": "https://diagrams.so/pricing",
  "warnings": [ … ],
  "score": { … }
}

Field	Type	Meaning
`xml`	string or `null`	The draw.io XML. `null` when the plan does not include the draw.io file.
`xml_withheld`	boolean	`true` when `xml` is `null` for that reason.
`xml_withheld_reason`	string	`UPGRADE_REQUIRED`.
`export_url`	string	Path, relative to the API host, of the watermarked SVG. `GET` it with the same key.
`upgrade_url`	string	`https://diagrams.so/pricing`.

The four extra fields appear only when the XML is withheld. A Paid reply has none of them, so it is the same as before. Test for xml_withheld, and do not treat xml: null as an error. Free keeps everything else: the diagram is stored, you can edit and fix it by id, and you can import a .drawio file. Idempotent replays follow the same rule, so a key replayed after a move to Free gets xml: null.

Generate with streaming

takes the same inputs as generate and streams server-sent events: progress events with stage, progress and message, then one complete event with the same body as POST /diagrams, or an error event. Progress events never carry XML. On Free the complete body has xml: null and the fields above. When you don’t need progress, use POST /diagrams.

Get a diagram

Read a diagram by id. On Free, xml is null (why).

curl https://api.diagrams.so/api/v2/diagrams/d_1a2b3c \
  -H "Authorization: Bearer dgz_live_YOUR_API_KEY"

List diagrams

List your diagrams, newest first. Supports pagination via limit and cursor.

curl "https://api.diagrams.so/api/v2/diagrams?limit=20" \
  -H "Authorization: Bearer dgz_live_YOUR_API_KEY"

Update a diagram

updates title, is_public, or the diagram xml. Diagrams are private until you set is_public to true.

curl -X PATCH https://api.diagrams.so/api/v2/diagrams/d_1a2b3c \
  -H "Authorization: Bearer dgz_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Renamed diagram"}'

Edit a diagram

Apply a natural-language edit. Typically takes 10 to 20 seconds.

curl https://api.diagrams.so/api/v2/diagrams/d_1a2b3c/edit \
  -H "Authorization: Bearer dgz_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"edit_prompt": "Put a CloudFront distribution in front of the API"}'

The response returns the updated xml (null on Free), a refreshed score and warnings, and usage.

Fix a warning

Apply a fix for a specific Well-Architected finding. Typically takes 10 to 20 seconds. The reply has the same shape as edit. See Warnings & score.

curl https://api.diagrams.so/api/v2/diagrams/d_1a2b3c/fix \
  -H "Authorization: Bearer dgz_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Enable versioning on the bucket.", "component": "S3", "warning_type": "reliability"}'

Re-layout a diagram

Re-arrange the diagram for readability. Runs as an async job and needs ?confirm=true. See Async operations for polling.

Import a draw.io file

Bring an existing draw.io diagram in so you can edit and export it. Works on both plans. The reply is a summary (id, title, is_public and so on) with no XML.

Delete a diagram

Delete a diagram you own.

curl -X DELETE https://api.diagrams.so/api/v2/diagrams/d_1a2b3c \
  -H "Authorization: Bearer dgz_live_YOUR_API_KEY"

Versions: every edit/fix creates a version. List, read, and revert via the versions endpoints, documented in the Async & versions section.

Overview

Endpoints

Generate a diagram

Free plan replies

Generate with streaming

Get a diagram

List diagrams

Update a diagram

Edit a diagram

Fix a warning

Re-layout a diagram

Import a draw.io file

Delete a diagram

​Generate a diagram

​Free plan replies

​Generate with streaming

​Get a diagram

​List diagrams

​Update a diagram

​Edit a diagram

​Fix a warning

​Re-layout a diagram

​Import a draw.io file

​Delete a diagram

Generate a diagram

Free plan replies

Generate with streaming

Get a diagram

List diagrams

Update a diagram

Edit a diagram

Fix a warning

Re-layout a diagram

Import a draw.io file

Delete a diagram