Diagram image API
Diagrams as images, from a single URL
Describe a diagram as JSON, encode it into a URL, and get back a crisp SVG or PNG — laid out automatically by the same engine behind the ChartCraft studio. Free, no auth, cached forever. Made for READMEs, wikis, and docs.
How it works
Author a spec
A small JSON object: nodes, edges, and a diagram family — flowchart, ERD, class, state, activity, sequence, or BPMN.
Encode it
deflate-raw + base64url (or plain base64url for quick tests). The builder below does it in your browser.
Embed the URL
Use it anywhere an image tag works. Same URL, same image, forever — responses are content-addressed and cached immutably.
Build a URL — right here
Edit the spec; the URL and preview update as you type. Encoding runs entirely in your browser.
Image URL (SVG)
Markdown embed
Live preview
The spec
One JSON object per diagram. diagramFamily picks the grammar; everything is laid out automatically — you never supply coordinates.
{
"title": "string — rendered as the diagram caption",
"diagramFamily": "flowchart | erd | class | state | activity | sequence | bpmn",
"layoutDirection": "TB | LR",
"nodes": [ { "id", "type", "label", "description?",
"attributes?": [], "methods?": [], "columns?": [] } ],
"edges": [ { "id", "source", "target", "label?", "type?" } ]
}
| Field | Values |
|---|---|
| node.type | start, end, process, decision, data, database, entity (ERD), class, interface (UML), state |
| edge.type | default, dashed, association, inheritance, realization, aggregation, composition, one-to-one, one-to-many, many-to-many, zero-to-one, zero-to-many |
| entity columns | ERD entities list columns as strings, e.g. "columns": ["id PK", "email", "created_at"] |
| class members | UML classes use "attributes": ["name: string"] and "methods": ["save()"] |
Sequence diagrams use participants (actor, system, database, component) and messages (sync, async, return, self) instead of nodes/edges. Limits: 150 nodes, 300 edges, 24,000-character URLs — send larger specs via POST.
From the terminal
Quick test — plain base64url, no compression
SPEC=$(echo -n '{"diagramFamily":"flowchart","nodes":[
{"id":"a","type":"start","label":"Start"},
{"id":"b","type":"end","label":"End"}],
"edges":[{"id":"e","source":"a","target":"b"}]}' \
| basenc --base64url -w0)
curl -o diagram.png \
"https://www.chartcraft.dev/api/v1/diagram.png?spec=$SPEC"
Large diagrams — POST
curl -X POST https://www.chartcraft.dev/api/v1/diagram \
-H "Content-Type: application/json" \
-o diagram.svg \
-d '{"format":"svg","spec":{"diagramFamily":"sequence",
"participants":[{"id":"u","name":"User","type":"actor"},
{"id":"s","name":"API","type":"system"}],
"messages":[{"id":"m1","from":"u","to":"s","label":"GET /data"},
{"id":"m2","from":"s","to":"u","label":"200 OK","type":"return"}]}}'
Questions
Is the diagram image API free?
Yes — no account, no API key. GET responses are content-addressed and cached immutably at the CDN, so embedding the same image a million times costs nothing. Rendered images carry a small chartcraft.dev credit.
Can I embed the images in a GitHub README?
Yes — that's the primary use case. Standard markdown image syntax works. SVG stays crisp at every zoom level; use .png where SVG isn't accepted.
Will my embedded URLs keep working?
The /v1/ prefix is a compatibility promise: specs that render today keep rendering. Breaking changes would ship under /v2/ — existing URLs are never invalidated.
What if I'd rather not write JSON?
Describe the diagram in plain English in the ChartCraft studio — or from your AI assistant via the MCP server — and export or embed from there.