TypeScript SDK

@diagrams-so/sdk is a fully typed client that covers every /api/v2 operation with one method per endpoint. It has zero dependencies (it uses the platform fetch), works in Node 18+, browsers, and edge runtimes, and includes built-in retries, idempotency keys, streaming, and a re-layout helper.

Install

npm install @diagrams-so/sdk

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 Python SDK:

import { login, DiagramsClient } from "@diagrams-so/sdk";

await login();
const client = new DiagramsClient();

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 it explicitly. The order of resolution is an explicit apiKey, then DIAGRAMS_API_KEY, then a stored login. Use logout() to remove the stored credential.

Quickstart

import { DiagramsClient } from "@diagrams-so/sdk";

const client = new DiagramsClient({ apiKey: process.env.DIAGRAMS_API_KEY! });

const d = await client.generate("AWS 3-tier web app: ALB, EC2, RDS", { cloudProvider: "aws" });
console.log(d.id, d.score?.score, d.warnings.length);

const w = await client.warnings(d.id);
if (w.length) await client.fix(d.id, w[0].message, { component: w[0].component ?? undefined, warningType: w[0].type });

const svg = await client.export(d.id, "svg"); // "drawio" needs Paid

Use the SDK server-side. Never ship an API key in browser or client-side code.

Authentication and plans

Pass your key from Settings → API Keys. 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

const d = await client.generate("Event-driven pipeline on AWS", { cloudProvider: "aws", diagramType: "architecture" });

await client.edit(d.id, "Add a CloudFront distribution in front of the API");
await client.fix(d.id, "Enable versioning on the S3 bucket", { component: "S3", warningType: "reliability" });

await client.update(d.id, { title: "Renamed diagram" });
await client.delete(d.id);

Streaming generation

generateStream is an async generator that yields { event, data }. The diagram arrives only in the terminal complete event. On Free its xml is null (see the Free plan).

for await (const { event, data } of client.generateStream("AWS event-driven pipeline")) {
  if (event === "progress") console.log(data.progress, data.message);
  else if (event === "complete") console.log(data.id, data.xml_withheld ?? false);
  else if (event === "error") throw new Error(data.error.message);
}

Warnings, re-layout, versions, export

const warnings = await client.warnings(d.id);

let job = await client.relayoutAndWait(d.id);
if ((job as any).status === "confirmation_required") {
  job = await client.relayoutAndWait(d.id, { confirm: true }); // re-layout moves every element; opt in
}

const versions = await client.versions(d.id);
const v = await client.getVersion(d.id, versionId);
await client.revert(d.id, { versionId });

const svg = await client.export(d.id, "svg");

Import, gallery, prompts

const imported = await client.import(drawioXml, { title: "Imported" });

const results = await client.searchGallery({ q: "serverless", limit: 20 });
const forked = await client.fork(results.items[0].id);

const better = await client.enhancePrompt("web app on aws");
const questions = await client.clarifyPrompt("a data pipeline");

Usage and account

await client.usage();                 // plan and cost estimates
await client.usageHistory({ limit: 20 });

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

Errors

Every non-2xx response throws DiagramsAPIError with .code, .status, and .requestId.

import { DiagramsAPIError } from "@diagrams-so/sdk";

try {
  await client.generate("...");
} catch (e) {
  if (e instanceof DiagramsAPIError) {
    console.log(e.code, e.status, e.requestId); // e.g. UPGRADE_REQUIRED 403 req_abc
  }
}

Idempotency

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

await client.generate("...", { idempotencyKey: "order-42" });

Pagination

list, searchGallery, and versions return Page<T> = { items, next_cursor, has_more }.

let cursor: string | undefined;
do {
  const page = await client.list({ limit: 50, cursor });
  page.items.forEach((item) => { /* ... */ });
  cursor = page.next_cursor ?? undefined;
} while (cursor);

Configuration

new DiagramsClient({
  apiKey: process.env.DIAGRAMS_API_KEY!,
  baseUrl: "https://api.diagrams.so/api/v2", // default
  timeoutMs: 120000,
  maxRetries: 3,   // only 429 / 503 are retried; Retry-After is honored
  backoffMs: 500,
});

Full method list

generate, generateStream, list, get, update, delete, edit, fix, warnings, startRelayout, relayoutStatus, relayoutAndWait, export, versions, getVersion, revert, import, searchGallery, fork, enhancePrompt, clarifyPrompt, usage, usageHistory, 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: null, xml_withheld: true, and an export_url for a watermarked SVG. Asking for a "drawio" export throws DiagramsAPIError with code UPGRADE_REQUIRED (status 403). Older published types declare xml as a string, so widen the type when you check:

const d = await client.generate(prompt);
const reply = d as typeof d & { xml: string | null; xml_withheld?: boolean; upgrade_url?: string };
if (reply.xml_withheld) {
  const svg = await client.export(d.id, "svg"); // watermarked on Free
  console.log("draw.io file needs Paid:", reply.upgrade_url);
} else {
  const xml = reply.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, re-layout, versions, export

Import, gallery, 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, re-layout, versions, export

​Import, gallery, 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, re-layout, versions, export

Import, gallery, prompts

Usage and account

Errors

Idempotency

Pagination

Configuration

Full method list

The Free plan