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. Billable. 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`. 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

{
  "id": "d_1a2b3c",
  "title": "Serverless image pipeline",
  "cloud_provider": "aws",
  "diagram_type": "architecture",
  "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": 249, "tier": "power" }
}

Generate with streaming

is billable. Same inputs as generate, but streams progress as the diagram is produced, so you can show live status during long generations. When you don’t need progress, use POST /diagrams above.

Get a diagram

Read a diagram by id. Free.

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. Free. 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

is free. Update metadata such as title or visibility.

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. Billable. 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, a refreshed score and warnings, and usage.

Fix a warning

Apply a fix for a specific Well-Architected finding. Billable. Typically takes 10 to 20 seconds. 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 '{"warning_type": "reliability", "component": "S3"}'

Re-layout a diagram

Re-arrange the diagram for readability. Runs as an async job. See Async operations for polling.

Import a draw.io file

Bring an existing draw.io diagram in so you can edit and export it. Free to import.

Delete a diagram

Delete a diagram you own. Free.

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

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

​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

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