Developers · REST API v1

The diagram APIbuilt for code & agents.

One POST turns Mermaid or PlantUML source into a presentation-ready SVG or PNG. Drop it into CI, commit the output next to your code, or wire it into agent pipelines — same engine that powers the editor.

Create API key Quick start Endpoint reference

<2s: render budget
4: input formats
SVG / PNG: outputs

bash · ~/project

$ curl -X POST https://www.beauty-diagram.com/api/v1/beautify \
  -H "authorization: Bearer bd_live_..." \
  -d '{"source":"flowchart TD\nA-->B", "sourceFormat":"mermaid"}'

# → 200 OK application/json
{
  "ok": true,
  "diagramType": "flowchart",
  "svg": "<svg xmlns=...>...</svg>",
  "usage": { used: 7, limit: 100 }
}

Same engine the editor uses · no separate API quota

MermaidPlantUMLdraw.ioSVG

Overview

What you can build

The Beauty Diagram API takes diagram source (Mermaid, PlantUML, draw.io, or SVG), applies the same beautify pipeline as the editor, and returns a clean, deck-ready vector. Three things people typically wire it into:

CI / docs pipelines

Commit .mmd, regenerate the SVG on push, never hand-edit a diagram again.

Agents & LLM tools

Let an agent emit Mermaid, get a polished image back in one round trip.

Internal tools

Render architecture / runbook diagrams from your own data on demand.

01

Quick start

Authenticated request. Replace bd_live_... with your key from /account/api-keys. Or skip the header for a watermarked anonymous demo (rate limited by IP).

curl -X POST https://www.beauty-diagram.com/api/v1/beautify \
  -H "authorization: Bearer bd_live_..." \
  -H "content-type: application/json" \
  -d '{
    "source": "flowchart TD\nA-->B",
    "sourceFormat": "mermaid",
    "theme": "modern"
  }'

💡 Pair the API with the bd CLI to keep diagrams checked-in next to your code — see CLI section.

02

Authentication

Three identities are accepted. Pick the smallest one that covers your use case.

Recommended

Personal access token

Create at /account/api-keys. Pick scopes; the raw key shows once. Pass as Authorization: Bearer bd_live_....

Browser

Web session

Front-end code in your own app can hit /api/v1/* directly using the user's Supabase session cookie. No extra setup.

No key

Anonymous demo

Skip the Authorization header — falls through to the demo bucket. Watermarked output, capped at 20 beautify requests / minute / IP and 1 export / 24h / IP. Denials include a hints block with sign-up / sign-in URLs so agents can self-onboard.

03

Scopes

Tokens are issued with explicit scopes. Request only what you need.

Scope	Capability
`render:write`	Beautify diagrams
`export:write`	Export SVG and PNG files
`share:write`	Create public share links
`usage:read`	Inspect quota: used vs limit, reset time

Reference

Endpoint matrix

Every /api/v1/* route at a glance — auth, plan-gated capabilities, monthly quota, and the limits applied to each.

Endpoint	Auth	Scope	Quota	Limits
POST`/api/v1/beautify`	Optional	`render:write`	Not metered	120/min/keyIP-rate-limited (anon)
POST`/api/v1/export`	Optional	`export:write`	Free 3 · Pro 100 · Premium ∞ /mo	120/min/keyIP-rate-limited (anon)1 export / IP / 24h trial
POST`/api/v1/share`	Required	`share:write`	Plan diagram cap (free 5 · pro 100 · premium ∞)	120/min/key
GET`/api/v1/themes`	None	—	—	120/min/keyIP-rate-limited (anon)
GET`/api/v1/usage`	Required	`usage:read`	—	120/min/key

PNG scaleis plan-gated separately: anonymous & free 1×, pro 2×, premium 4×. Higher requests are silently clamped — see X-BD-Scale-Clamped in the response headers reference below.

Reference

Endpoints

Base URL is https://www.beauty-diagram.com. All endpoints return JSON unless explicitly noted.

POST/api/v1/beautifyRender a diagram, return inline SVG

Beautify and render a diagram. Returns the SVG inline so you can preview it immediately or persist it yourself.

POST /api/v1/beautify
{
  "source": "...",
  "sourceFormat": "mermaid" | "plantuml",
  "theme": "modern"
}

→ {
  "ok": true,
  "diagramType": "flowchart",
  "svg": "<svg ...>",
  "meta": { "theme": "modern", "width": 720, "height": 480, "hasWatermark": false },
  "usage": { "used": 7, "limit": 100, "resetsAt": "2026-05-01T00:00:00Z" }
}

POST/api/v1/exportBinary file download (SVG or PNG)

Returns the rendered file as a binary download (Content-Type: image/svg+xml) so curl -o file.svg just works. Metadata travels in response headers so the body stays a clean SVG. Pass Accept: application/json or ?response=json to opt into the legacy JSON wrapper.

PNG output is supported via format: "png". Pass scale: 1 | 2 | 4to control resolution; the server clamps to your plan's cap (anonymous / free = 1×, pro = 2×, premium = 4×) and reports clamping via X-BD-Scale-Clamped: true.

POST /api/v1/export
{ "source": "...", "sourceFormat": "mermaid", "format": "svg" }

→ HTTP/1.1 200 OK
   Content-Type: image/svg+xml; charset=utf-8
   Content-Disposition: attachment; filename="diagram-flowchart.svg"
   X-BD-Diagram-Type: flowchart
   X-BD-Theme: modern
   X-BD-Quota-Used: 7
   X-BD-Quota-Limit: 100
   X-BD-Quota-Resets-At: 2026-05-01T00:00:00Z

   <svg xmlns="..."> ... </svg>

More examples (filename auto-pick, PNG @ 4×)

Let the server pick the filename via curl's -OJ:

curl -OJ -X POST https://www.beauty-diagram.com/api/v1/export \
  -H "authorization: Bearer bd_live_..." \
  -H "content-type: application/json" \
  -d '{ "source": "...", "sourceFormat": "mermaid", "format": "svg" }'

# saves ./diagram-flowchart-a3f9k2.svg

PNG @ 4× for premium plan:

curl -OJ -X POST https://www.beauty-diagram.com/api/v1/export \
  -H "authorization: Bearer bd_live_..." \
  -H "content-type: application/json" \
  -d '{ "source": "...", "sourceFormat": "mermaid", "format": "png", "scale": 4 }'

Filenames default to diagram-<type>-<sourceHash6>.<ext> so two different sources never collide and the same source is idempotent. Override with ?filename=my-name.

POST/api/v1/shareSave source, return public URL

Save the source as a shared diagram and return a public URL. Authenticated only (free plan or above).

POST /api/v1/share
{ "source": "...", "sourceFormat": "mermaid", "title": "Release flow" }

→ {
  "ok": true,
  "diagramId": "uuid",
  "shareToken": "...",
  "sharePath": "/s/release-flow-xxxx",
  "shareUrl": "https://www.beauty-diagram.com/s/release-flow-xxxx"
}

GET/api/v1/themesList available themes

Returns each theme's id, name, tone, and short description so you can build a theme picker that always reflects what the engine actually supports.

GET/api/v1/usagePlan, quota, AI counter

Returns the actor's plan, AI quota and export counter. Use this before running expensive batches so you can pre-empt quota_exhausted.

Operations

Limits, rate limiting & headers

The web app and the API share a single export counter — there is no separate "API quota". Rate limits are enforced cross-instance for API keys and IP-based for anonymous demo traffic.

Anonymous

Rate · Rate-limited per IP

1 export / IP / 24h trial

Free

Rate · 120 req/min/key

3 exports / month

Popular

Pro

Rate · 120 req/min/key

100 exports / month

Premium

Rate · 120 req/min/key

Unlimited exports

Rate limiting

Authenticated (API key or session)

120 requests / minute / key, fixed window. The counter is shared across the entire /v1/* namespace and persists across function instances.

Over-budget calls get 429 rate_limited with a Retry-After header and a rateLimit object describing window state.

Anonymous demo

Rate-limited per IP — exact ceiling is intentionally undocumented to discourage abuse. Sign in or use an API key for higher allowances.

A 1-export-per-IP-per-24h trial budget on /v1/export lets agents and evaluators verify the toolchain end-to-end before registering. Denials carry a hints block with signUpUrl / signInUrl / apiDocsUrl.

Sample 429 response

HTTP/1.1 429 Too Many Requests
Retry-After: 47
Content-Type: application/json

{
  "ok": false,
  "error": "rate_limited",
  "message": "API key rate limit (120 requests / 60s) reached. Retry after 2026-04-27T04:31:12Z.",
  "retryAfterMs": 47000,
  "rateLimit": {
    "limit": 120,
    "windowSeconds": 60,
    "used": 121,
    "resetsAt": "2026-04-27T04:31:12Z"
  }
}

Response headers

Metadata that does not fit in the JSON body — useful for CLI / batch pipelines that need to read state without parsing the response.

Header	Where	Meaning
`X-BD-Diagram-Type`	/v1/export	Detected type — flowchart, sequence, etc.
`X-BD-Theme`	/v1/export	Theme that produced the output.
`X-BD-Watermark`	/v1/export	true when the badge is baked in.
`X-BD-Scale`	/v1/export (PNG)	Effective scale (1, 2, or 4).
`X-BD-Scale-Clamped`	/v1/export (PNG)	true when scale was lowered to plan cap.
`X-BD-Quota-Plan`	/v1/export	Plan tier of the actor.
`X-BD-Quota-Used`	/v1/export	Exports used in the current month.
`X-BD-Quota-Limit`	/v1/export	Plan limit, or unlimited.
`X-BD-Quota-Resets-At`	/v1/export	ISO timestamp when the counter resets.
`Retry-After`	Any 429	Seconds until the next attempt is safe.

Body limits

source on render endpoints: 100 KB (UTF-8 bytes). Oversize → source_too_large (HTTP 413).

Encoding

UTF-8 only; CJK and emoji labels supported in SVG. PNG raster ships Latin glyphs only — CJK falls back to tofu boxes. Newlines must be JSON-escaped as \n.

Timeouts

POST routes carry maxDuration = 60s; render aims for <2s. PNG worst case (4× composite) is ~1.1s plus ~1.5s cold start.

Operations

Errors

Every error is JSON of the shape { ok: false, error, message }. Anonymous-actor denials additionally carry hints: { signUpUrl, signInUrl, apiDocsUrl } so CLIs and agents can guide the user to register without scraping these docs. Codes you should handle:

Code	Meaning
`invalid_input`	Malformed body or wrong types.
`not_authenticated`	No key, no session.
`scope_missing`	Key lacks the required scope.
`plan_not_allowed`	Plan does not include this capability.
`parse_failed`	Source did not parse as the declared format.
`quota_exhausted`	Limit reached for this period.
`rate_limited`	Anonymous IP bucket is full.
`output_too_large`	Rasterized PNG exceeds the 8192 px ceiling — lower scale or simplify.

Operations

Privacy

We do not persist your source or AI instruction unless you explicitly call /api/v1/share.
Logs store a hash, length, format, and diagram type — never the raw input.
You can revoke any API key from /account/api-keys. Revocation takes effect immediately.

Tooling

CLI

The bd CLI wraps the API for repo-friendly use — same auth, same quotas, same engine.

# zero-install
npx @beauty-diagram/cli beautify flow.mmd --out flow.svg

# global install
npm install -g @beauty-diagram/cli
bd beautify flow.mmd --out flow.svg
bd export flow.mmd --format svg --out flow-hd.svg
bd share flow.mmd --title "Release flow"

Ready to ship?

Create a key, paste the curl from above, and you'll have your first rendered SVG inside a minute. Free plan includes 3 watermark-free exports a month — enough to wire up CI.

Create API key See pricing