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. A browser opens, you 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.drawio", "w").write(client.export(d["id"], "drawio"))

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

Authentication and billing

Pass your key from Settings → AI Provider in your account. Reads, enhance_prompt, and clarify_prompt are free. generate, edit, fix, relayout, and fork cost credits.

dgz_test_ keys run in test mode. They bill the same credits as a live key (drawing your real balance) but apply lower rate limits, so use them to exercise your integration, not to avoid spend. Check your balance with client.usage().

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 XML arrives only in the terminal complete event, after the charge.

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["usage"]["credits_charged"])
    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":   # free re-layouts exhausted
    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)

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

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"])    # billable

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

Usage and account

client.usage()                        # plan, credits remaining
for item in client.iter_usage_history():   # itemized ledger, auto-paginated
    print(item["action"], item["credits"], 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. QUOTA_EXCEEDED 402 req_abc
    if e.status == 402:
        ...  # out of credits; prompt the user to top up

Idempotency

Pass idempotency_key on billable create calls (generate, generate_stream, edit, fix) so a retry replays the stored result for 24 hours instead of charging 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.

Running out of credits

A billable call with no credits left raises DiagramsAPIError with code QUOTA_EXCEEDED. The error carries the top-up link, so you can show it to the user:

try:
    client.generate(prompt)
except diagrams_so.DiagramsAPIError as e:
    if e.code == "QUOTA_EXCEEDED":
        print("Out of credits:", e.upgrade_url)

Getting started

Model Context Protocol (MCP)

SDKs

Guides

Billing

Resources

Install

Connect

CI and servers

Quickstart

Authentication and billing

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

Running out of credits

​Install

​Connect

​CI and servers

​Quickstart

​Authentication and billing

​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

​Running out of credits

Install

Connect

CI and servers

Quickstart

Authentication and billing

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

Running out of credits