Architecture diagram APIs, compared
The things that decide whether a diagram API survives contact with a real pipeline.
An architecture diagram API takes a description over HTTP and returns a diagram. Most diagram tools are a canvas with a login, a few will render from text you POST to them, and far fewer hand back something a person can open and edit afterwards. That last part is what decides whether the diagram survives contact with a real team, so it is the first thing to check, ahead of layout quality, billing model, rate limits and whether retries are safe.
What to check before you commit
Does the output stay editable? Rendering to PNG is easy. The trouble starts the first time someone needs to move a box. Native .drawio opens in draw.io, in VS Code, in Confluence, and diffs in git as XML. Who does the layout? Diagram-as-code tools hand layout to a renderer. Some renderers are excellent at it, Graphviz especially. Others produce a technically-correct tangle, and if a person has to untangle every output then the API saved you nothing. How does it bill? Per call, per seat, or per token. Per-call pricing is easiest to reason about in a pipeline that might run a hundred times a day. Does it have idempotency? A pipeline retries. Without an idempotency key, a retry means a second charge and a duplicate diagram. This is the most common way people get surprised by an API bill. What happens under load? Ask what the rate limit is, and ask what the API returns when its own dependencies are down. An API that silently does free work when its rate limiter is unavailable is one you will find out about later.
What the API surface looks like
Thirty operations across twenty-seven paths. These are the ones that carry the work.
POST /api/v2/diagrams generate from a prompt
POST /api/v2/diagrams/stream same, streamed
PATCH /api/v2/diagrams/{id} rename, visibility
POST /api/v2/diagrams/{id}/edit change it in place
POST /api/v2/diagrams/{id}/fix fix one flagged warning
POST /api/v2/diagrams/import bring an existing .drawio in
GET /api/v2/diagrams/{id}/warnings what is wrong with the design
GET /api/v2/diagrams/{id}/export?format= drawio or svg
GET /api/v2/diagrams/{id}/versions history
POST /api/v2/diagrams/{id}/revert go back
POST /api/v2/diagrams/{id}/relayout async, returns a job id
GET /api/v2/gallery search public diagrams
GET /api/v2/usage what you have spentTwo things the spec will tell you and old snippets will not
Export takes drawio or svg. There is no PNG and no PDF on the API, even though the web app offers more. The generate parameter is cloud_provider. Older snippets floating around say provider and will fail validation.
A first call, end to end
One POST, with an idempotency key so a retry cannot charge twice.
curl -X POST https://api.diagrams.so/api/v2/diagrams \
-H "Authorization: Bearer $DIAGRAMS_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"prompt": "three-tier web app on AWS: ALB, three EC2 in private subnets, RDS Postgres with a read replica",
"cloud_provider": "aws"
}'Billing, plainly
Generate, edit, fix and re-layout cost credits. Reads cost nothing: fetching, listing versions, pulling warnings, exporting and gallery search are all free. Re-layout has no free allowance. Every one is billed by the tokens it uses, the same way edit and fix are, and the endpoint refuses to start without ?confirm=true so a pipeline cannot run one by accident. Keys draw on the same credit balance as the web app, on every plan including Free. There is no separate developer tier and no metered overage. When the balance runs out, calls return 402 rather than continuing and billing. Test keys starting dgz_test_ draw on that same balance. There is no free sandbox, so treat a leaked test key exactly like a leaked live key.
Rate limits and failure
Sixty requests a minute on a live key, twenty on a test key, and two hundred and forty a minute per IP address. A 429 comes back with Retry-After and the RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset headers. When the rate limiter itself is unreachable, billable calls return 503. They do not fall through and run for free. That is deliberate, and it is worth handling, because a 503 here means retry rather than something is broken.
SDKs
Python and TypeScript, both wrapping the same surface. Install with pip install diagrams-so or npm install @diagrams-so/sdk.
from diagrams_so import DiagramsClient
client = DiagramsClient(api_key="dgz_live_...")
d = client.generate(
"EKS cluster with an ALB ingress and RDS in two AZs",
cloud_provider="aws",
)
open("architecture.drawio", "w").write(client.export(d["id"], "drawio"))The options
Diagram-as-code is genuinely the right answer for a lot of cases, and it is free. Reach for an API when the input is prose or infrastructure rather than a DSL you already know, when you want cloud icons without curating them, or when a person has to edit the result later.
| What to check | Diagrams.so API | Diagram-as-code renderers | Canvas tools with an API | Cloud vendor tools |
|---|---|---|---|---|
| Input | Plain English, or an existing .drawio | DSL you write | Shapes you construct | Live cloud account |
| Output | .drawio, SVG | SVG, PNG | Proprietary, sometimes PNG | Proprietary |
| Layout | Automatic, re-runnable | Renderer decides | You place everything | Automatic |
| Cloud icons | AWS, Azure, GCP, OCI, Kubernetes, 30+ packs | Add your own | Some | The vendor's own |
| Editable by a person after | Yes | Yes, as code | Yes, in that tool | In that tool |
| Design review | Warnings, with a fix call | No | No | Some |
| Billing | Credits per generate or edit | Free, self-hosted | Per seat | Per account |
| Idempotency keys | Yes | Not applicable | Rare | Rare |
Real-world examples
Generate these diagrams with AI
Turn Plain Text into Draw.io Diagrams
Write what you want in English. Skip Mermaid syntax, PlantUML code, and manual drawing. Get a grid-aligned, icon-accurate .drawio file in seconds.
Generate AWS architecture diagrams from text
Describe your AWS infrastructure in plain English. Get a valid Draw.io diagram with official AWS icons, VPC boundaries, and Multi-AZ placement.
Build Architecture Diagrams from Text Descriptions
Describe your cloud infrastructure or system design. Get a Draw.io architecture diagram with official vendor icons, VPC boundaries, and architecture warnings.
Related guides
Frequently asked questions
Can I diagram my infrastructure code?
Yes. Send the Terraform, the compose file or the Kubernetes manifests as the prompt. Say how you want it grouped, because that is the difference between a readable diagram and a resource list.
Is there a free tier for the API?
The API, MCP server and SDKs are on every plan including Free, and they draw on the same credit balance the web app uses. A Free account's credits work on the API, so the first call costs nothing extra. There is no separate developer allowance on top of that. One thing to know: diagrams created on the Free plan are public and appear in the community gallery; private diagrams are a paid-plan feature.
What happens on a timeout?
A long generate can time out at the gateway while still completing on the server, and it is still charged. Fetch GET /api/v2/diagrams to find the result rather than retrying blind, and use /api/v2/diagrams/stream for long prompts.
Are re-layouts free?
No. Every re-layout is billed by the tokens it uses, like edit and fix. The endpoint returns a confirmation instead of starting until you re-POST with ?confirm=true, which mirrors the dialog the web app shows.
Does the API version break?
The v2 contract is checked in CI against the published OpenAPI spec on every change, so breaking changes are caught before merge. The spec is public at api.diagrams.so/api/v2/openapi.json.
Wiring this into a pipeline? The API reference indexes every endpoint with what it costs.