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. 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 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 drawio = await client.export(d.id, "drawio"); // native .drawio XML string

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

Authentication and billing

Pass your key from Settings → AI Provider. Reads, enhancePrompt, and clarifyPrompt 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

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

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.usage.credits_charged);
  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 }); // accept the credit charge
}

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); // billable

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

Usage and account

await client.usage();                 // plan, credits remaining
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. QUOTA_EXCEEDED 402 req_abc
  }
}

Idempotency

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

Running out of credits

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

try {
  await client.generate(prompt);
} catch (e) {
  if (e.code === "QUOTA_EXCEEDED") console.log("Out of credits:", e.upgradeUrl);
}

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

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

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

Import, gallery, prompts

Usage and account

Errors

Idempotency

Pagination

Configuration

Full method list

Running out of credits