Python SDK

diagrams-so is a typed Python client that covers every /api/v2 operation with one method per endpoint. It has no hard dependencies (it uses requests if installed, otherwise the standard library), and includes built-in retries, idempotency keys, streaming, and an async re-layout helper.

Install

pip install diagrams-so

Connect

Run this once per machine. You enter your email, we send a one-time code, and a browser opens where you sign in and enter it; press Approve and the credential is stored for you at ~/.diagrams-so/credentials.json, shared with the MCP server and the TypeScript SDK:

import diagrams_so

diagrams_so.login()
client = diagrams_so.DiagramsClient()

Installing the package also puts a diagrams-so command on your PATH, so you can connect from a terminal without writing any code and without needing Node:

diagrams-so login
diagrams-so whoami

CI and servers

Where no browser exists, set an environment variable. It always takes priority over a stored login:

export DIAGRAMS_API_KEY=dgz_live_YOUR_API_KEY

Or pass the key explicitly. The order of resolution is an explicit api_key, then DIAGRAMS_API_KEY, then a stored login. Use diagrams_so.logout() to remove the stored credential.

Quickstart

from diagrams_so import DiagramsClient

client = DiagramsClient(api_key="dgz_live_YOUR_API_KEY")

d = client.generate("AWS 3-tier web app: ALB, EC2, RDS", cloud_provider="aws")
print(d["id"], d["score"]["score"], len(d["warnings"]))

# fix the first Well-Architected warning
w = client.warnings(d["id"])
if w:
    client.fix(d["id"], w[0]["message"], component=w[0].get("component"), warning_type=w[0]["type"])

open("diagram.svg", "w").write(client.export(d["id"], "svg"))   # "drawio" needs Paid

Load the key from an environment variable or secret manager. Never hard-code it or ship it in client-side code.

Authentication and plans

Pass your key from Settings → API Keys in your account. Every method works on both plans, with no usage limit beyond the rate limit.

dgz_test_ keys run in test mode, with a lower rate limit. They are not a sandbox: they run real generations on your account.

Create and change diagrams

# Generate
d = client.generate("Event-driven pipeline on AWS", cloud_provider="aws", diagram_type="architecture")

# Edit with a prompt
d = client.edit(d["id"], "Add a CloudFront distribution in front of the API")

# Fix a specific warning
d = client.fix(d["id"], "Enable versioning on the S3 bucket", component="S3", warning_type="reliability")

# Update metadata, or delete
client.update(d["id"], title="Renamed diagram")
client.delete(d["id"])

Streaming generation

generate_stream yields (event, data) tuples. The diagram arrives only in the terminal complete event. On Free its xml is None (see the Free plan).

for event, data in client.generate_stream("AWS event-driven pipeline"):
    if event == "progress":
        print(data["progress"], data["message"])
    elif event == "complete":
        print(data["id"], data.get("xml_withheld", False))
    elif event == "error":
        raise RuntimeError(data["error"]["message"])

Warnings and score

warnings = client.warnings(d["id"])
for w in warnings:
    print(w["type"], w["component"], w["message"])

Async re-layout

relayout_and_wait starts the job and polls it to completion.

job = client.relayout_and_wait(d["id"])
if job.get("status") == "confirmation_required":   # re-layout moves every element; opt in
    job = client.relayout_and_wait(d["id"], confirm=True)

Prefer to poll yourself? Use client.relayout(d["id"]) then client.relayout_status(d["id"], job_id).

Read, versions, and export

d = client.get(diagram_id)
page = client.list(limit=50)                  # {items, next_cursor, has_more}

vs = client.versions(diagram_id)
v = client.get_version(diagram_id, version_id)
client.revert(diagram_id, version_id=version_id)

svg = client.export(diagram_id, "svg")        # "drawio" needs Paid

Import, gallery, and prompts

d = client.import_diagram(open("existing.drawio").read(), title="Imported")

results = client.search_gallery(q="serverless", limit=20)
d = client.fork(results["items"][0]["id"])

better = client.enhance_prompt("web app on aws")
questions = client.clarify_prompt("a data pipeline")

Usage and account

client.usage()                        # plan and cost estimates
for item in client.iter_usage_history():   # itemized task history, auto-paginated
    print(item["action_type"], item["diagram_id"], item["source"])

client.me()                           # account, plan, scopes, mode
client.meta("providers")              # or "diagram-types", "formats", "features"

Errors

Every non-2xx response raises DiagramsAPIError with code, status, and request_id.

from diagrams_so import DiagramsAPIError

try:
    client.generate("...")
except DiagramsAPIError as e:
    print(e.code, e.status, e.request_id)   # e.g. UPGRADE_REQUIRED 403 req_abc

Idempotency

Pass idempotency_key on create calls (generate, generate_stream, edit, fix) so a retry replays the stored result for 24 hours instead of running twice.

client.generate("...", idempotency_key="order-42")

Pagination

list, search_gallery, and versions return {items, next_cursor, has_more}.

cursor = None
while True:
    page = client.list(limit=50, cursor=cursor)
    for item in page["items"]:
        ...
    if not page.get("has_more"):
        break
    cursor = page["next_cursor"]

Configuration

DiagramsClient(
    api_key="dgz_live_YOUR_API_KEY",
    base_url="https://api.diagrams.so/api/v2",   # default
    timeout=120.0,
    max_retries=3,   # only 429 / 503 are retried; Retry-After is honored
    backoff=0.5,
)

Full method list

generate, generate_stream, list, get, update, delete, edit, fix, warnings, relayout, relayout_status, relayout_and_wait, export, versions, get_version, revert, import_diagram, search_gallery, fork, enhance_prompt, clarify_prompt, usage, usage_history, me, meta. Each maps one-to-one to an endpoint in the API reference.

The Free plan

Nothing runs out on either plan. On Free, the API keeps the draw.io XML on the server: diagram replies have xml set to None, xml_withheld set to True, and an export_url for a watermarked SVG. Asking for a "drawio" export raises DiagramsAPIError with code UPGRADE_REQUIRED (status 403).

d = client.generate(prompt)
if d.get("xml_withheld"):
    svg = client.export(d["id"], "svg")     # watermarked on Free
    print("draw.io file needs Paid:", d["upgrade_url"])
else:
    xml = d["xml"]

See Plans & pricing.

Getting started

Model Context Protocol (MCP)

SDKs

Guides

Billing

Resources

Install

Connect

CI and servers

Quickstart

Authentication and plans

Create and change diagrams

Streaming generation

Warnings and score

Async re-layout

Read, versions, and export

Import, gallery, and prompts

Usage and account

Errors

Idempotency

Configuration

Full method list

The Free plan

​Install

​Connect

​CI and servers

​Quickstart

​Authentication and plans

​Create and change diagrams

​Streaming generation

​Warnings and score

​Async re-layout

​Read, versions, and export

​Import, gallery, and prompts

​Usage and account

​Errors

​Idempotency

​Pagination

​Configuration

​Full method list

​The Free plan

Install

Connect

CI and servers

Quickstart

Authentication and plans

Create and change diagrams

Streaming generation

Warnings and score

Async re-layout

Read, versions, and export

Import, gallery, and prompts

Usage and account

Errors

Idempotency

Pagination

Configuration

Full method list

The Free plan