A text to diagram API, without the ambiguity
Two very different products share this name. One renders diagram syntax you already wrote. The other turns plain English into a diagram. Know which one you need before you wire anything in.
A text to diagram API accepts a written description over HTTP and returns a finished diagram. The term covers two different products, and mixing them up costs an afternoon: syntax renderers like Kroki or mermaid.ink take diagram code you already wrote (Mermaid, PlantUML, Graphviz) and return an image, while a natural-language diagram API takes a plain-English sentence like "three-tier web app on AWS with a read replica" and decides the boxes, the arrows and the layout for you. The second kind is the one people usually mean, and the thing to check before committing is what comes back: an image is a dead end the first time someone needs to move a box, while native .drawio or SVG stays editable after the API call ends.
Two products share this name, and they do different jobs
A syntax renderer takes diagram-as-code you already wrote and rasterises it. Kroki does this for over twenty grammars, mermaid.ink does it for Mermaid, and the PlantUML server does it for PlantUML. They are fast, mostly free, and exactly right when the diagram already exists as code and all you need is a picture in a pipeline. A natural-language diagram API starts one step earlier. The input is prose: a sentence, a paragraph, a pasted Terraform file. The API decides what the components are, how they connect, which icons they get and where they sit. There is no grammar to learn because there is no grammar. That is the job Diagrams.so's API does, and it is the harder half of the problem, which is why the two products are priced and built so differently. If you have Mermaid text and want a PNG, use a renderer and keep your money. If you have a description in a ticket, a README, or a colleague's Slack message, you want the second kind.
The one thing to check before you commit: what comes back
Every diagram API can hand you a picture. The difference that decides whether the integration survives is whether the picture can be worked on afterwards. An API that returns PNG has ended the conversation. The first time an architect says "move the queue behind the gateway", someone regenerates from scratch and hopes the layout lands close to last time. An API that returns an editable format keeps the diagram alive: Diagrams.so returns native .drawio XML, which opens in draw.io, in VS Code, in Confluence, and diffs line by line in git. SVG is available when you need something to embed. On the API the export formats are drawio and svg. PNG and PDF exist in the web app but not on the API, deliberately: the API's job is to produce sources, not screenshots.
A first call, end to end
One POST with a plain-English prompt. The idempotency key means a retried request cannot create or charge twice.
Generate a diagram from a sentence
curl -X POST https://diagrams.so/api/v2/diagrams \
-H "Authorization: Bearer $DIAGRAMS_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: ticket-4231-attempt-1" \
-d '{
"prompt": "Three-tier web app on AWS: ALB, two EC2 app servers, RDS Postgres with a read replica, S3 for assets",
"diagram_type": "architecture",
"cloud_provider": "aws"
}'
# The response carries the diagram id. Fetch the editable source:
curl https://diagrams.so/api/v2/diagrams/$ID/export?format=drawio \
-H "Authorization: Bearer $DIAGRAMS_API_KEY"It is not only architecture diagrams
Prose-to-diagram works for any diagram whose structure lives in the words. The same endpoint takes a diagram_type and draws flowcharts from a described process, sequence diagrams from a described exchange, and entity-relationship diagrams from a described schema. The practical effect: the text sitting in your tickets, runbooks and design docs is already diagram input. A support runbook's escalation steps become a flowchart without anyone opening a canvas tool. A schema sketch in a PR description becomes an ERD the reviewer can open and correct.
When the API is the wrong surface
The API fits pipelines: a script, a CI job, a docs build that regenerates diagrams when the infrastructure code changes. If the caller is an AI agent rather than your code, the MCP server is the better surface, because the agent gets the full toolset (generate, edit, fix, export and the rest of the 23 tools) without you writing any HTTP. Claude Code, Claude Desktop and Cursor all speak it. And if a person just wants one diagram, the web app is faster than either. The API earns its keep on the second diagram, not the first.
Costs and limits, plainly
Calls that create or change a diagram (generate, edit, fix, re-layout) cost credits from the same balance as the web app, on whatever plan the account has. Reads are free: fetching a diagram, exporting it, listing versions. Rate limits are flat: sixty requests a minute on a live key, twenty on a test key, two hundred and forty per IP. A 429 arrives with Retry-After and the standard RateLimit headers, so a well-behaved client backs off without guesswork. Timeouts are the one case to handle deliberately: a generation that times out on your side may still have completed and charged on the server, so recover by listing recent diagrams rather than blindly retrying without an idempotency key.
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 Diagrams with AI, Not Drag-and-Drop
Write what your system does. The AI picks the notation, selects vendor icons, enforces grid alignment, and outputs valid mxGraphModel XML you can open in Draw.io.
Generate Flowcharts from Text with AI
Describe a process in plain English. Get a valid Draw.io flowchart with correct ISO 5807 symbols, decision diamonds, and directional arrows.
Related guides
Frequently asked questions
Does the input have to be structured, or is plain English enough?
Plain English is the point. "Payment service calls the fraud check, then writes to Postgres and emits an event to Kafka" is a complete, working input. You can paste structured sources too, a Terraform file or a docker-compose, and the API reads the structure out of them, but no diagram grammar is required.
Can I get a PNG back?
Not from the API. API exports are drawio and svg, both editable or embeddable sources. The web app exports PNG and PDF for the cases where a flat image is genuinely what you want.
Is there a free way to try it?
API calls draw from the same credit balance as your Diagrams.so account, so the free plan's credits work on the API too. No separate API pricing to learn.
How is this different from Kroki or mermaid.ink?
Kroki and mermaid.ink render diagram code you already wrote into an image. They do not accept plain English, and their output is a picture rather than an editable file. This API starts from prose and returns .drawio XML you can keep editing.
What happens if I retry a slow request?
Send an Idempotency-Key header and retries are safe: the same key returns the original result instead of generating and charging again. Without one, a timeout followed by a retry can produce two diagrams and two charges.
The quickstart mints a key and returns a first diagram in a few minutes, on whatever plan you already have.