You will need a Diagrams.so account first. API keys are created in the app, so step 1 is a quick hop to diagrams.so before you write any code.

​
1. Connect

Using the MCP server or an SDK? Connect once and you are done. Nothing to copy, nothing to paste:
A browser opens, you press Approve, and the client is connected. See Authentication for how it works. Calling the API directly with curl or from CI? Create a key instead. Sign in at diagrams.so and open Settings → AI Provider → Create key.
  • The plaintext key is shown once at creation. Store it in a secret manager.
  • Keys are prefixed dgz_live_ (production) or dgz_test_ (test mode).
  • You can scope a key to read-only, write, or read & write, and set an expiry.
Never commit a key to source control or paste it into a client-side app. Treat it like a password.

​
2. Confirm your key works

A 200 with your account, plan, and scopes means you are set. A 401 means the key is missing, malformed, or revoked.

​
3. Generate a diagram

Generation is AI-backed and can take 30 seconds or more. On a plain curl there is no progress until it completes, so for live progress use POST /diagrams/stream. For reference: edits and fixes typically take 10 to 20 seconds, and re-layout runs as an async job you poll. The SDKs and MCP server default to a 180-second timeout.
The response contains:

​
4. Iterate

Edit with a prompt

POST /diagrams/{id}/edit, for example “add a CloudFront distribution in front of the ALB”.

Fix a warning

POST /diagrams/{id}/fix applies a recommended change.

Export

GET /diagrams/{id}/export?format=svg returns draw.io or SVG.

Prefer an agent?

Do all of the above from Claude or Cursor via MCP.

​
Prefer not to write HTTP?

Python SDK

pip install diagrams-so

TypeScript SDK

npm i @diagrams-so/sdk