API reference

Six endpoints, one of which does the work

A key's whole authority is the daily conversion quota set on the account that issued it. It cannot raise that quota, touch billing, or read another account.

Authentication

Send the key as a bearer token. Issue one on the agents page — it is shown once, and only a hash is stored.

Authorization: Bearer rdg_...

A key with no daily quota is read-only: it can call /api/me and read conversions it owns, and gets 403 on anything that converts.

Endpoints

POST /api/agent/convert needs quota

Redraw an existing diagram on your brand.

source: string — the raw file contents. One of source, file or image is required. Max 2 MB.
file: upload — the file itself, or a PNG, JPEG or WebP of a diagram. Max 8 MB.
image: string — a PNG, JPEG or WebP of a diagram, base64, for a caller posting JSON. A model reads the picture rather than parsing it: the result says so in its ledger, lists what it could not read, and costs a credit. Paid plans, or purchased credits.
prompt: string — context for an image only: what it is of, or a label the picture renders too small to read.
filename: string — disambiguates the format when sniffing is uncertain.
brand: string — slug of one of your brand profiles. Omit for the shipped default.
fidelity: complete or editorial. Complete keeps everything; editorial is willing to drop.
lang: en or ar. Arabic mirrors the flow and takes its own type scale.
twin: boolean — also render the mirrored-language twin.
colors: object — hex by role: brand, ink, ground, surface, muted, link. Outranks brand.
typeface: editorial, neutral or technical.
animate: none, reveal, flow or both. The SVG carries the motion and every static consumer still gets the finished drawing. A reveal also becomes a real PowerPoint build, and produces an MP4 on a plan that includes video.

POST /api/agent/author needs quota

Draw a diagram from a description, when there is no file to convert. Any of the 53 kinds, including the four engineering drawings — a network in tiers with ports and addresses, a single-line electrical distribution, a placed schematic, a floor plan.

prompt: string — what to draw. 8 to 4000 characters. Required.
brand: string — slug of one of your brand profiles.
lang: en or ar.
twin: boolean — also render the mirrored-language twin.
colors: object — hex by role: brand, ink, ground, surface, muted, link. Outranks brand.
typeface: editorial, neutral or technical.
animate: none, reveal, flow or both. The SVG carries the motion and every static consumer still gets the finished drawing. A reveal also becomes a real PowerPoint build, and produces an MP4 on a plan that includes video.

POST /api/agent/brands needs quota

Save a palette and type pairing to reuse by slug. Give a site to read one from, or the colours outright for a brand that lives as hex codes in a slide master rather than on a website.

url: string — a public site to sample. Required unless you send colors.
colors: object — hex by role. Required unless you send url, and outranks it when both are given.
name: string — what to call it. The slug comes from this.
typeface: editorial, neutral or technical.

POST /mcp

The same tools over MCP, for an agent rather than a program — add https://rediagram.app/mcp as a custom connector in Claude or ChatGPT. Every drawing tool returns the picture and the .dgm behind it. Converting works with no account at all; drawing from a description needs one, either an agent token or the OAuth flow the connector runs for you.

GET /api/agent/conversions/{id}

One conversion by id, in the same shape the convert call returned. 404 if it is not yours.

GET /api/me

What this key is, what it may do, which brands it can reach, and which formats the server actually parses.

POST /api/agent/brands needs quota

Create a brand profile from a URL, so later conversions can name it by slug.

POST /api/agent/brands/{slug}/verify needs quota

Prove you own the site a brand was read from.

.dgm — as input and as output

.dgm is our own format: semantic rather than geometric, so an agent writes meaning and never invents coordinates. Post it as source like any other format, and every conversion returns one in artifacts.dgm — the only artifact you can re-import. Full rules and versioning are in the .dgm specification.

curl -X POST https://rediagram.app/api/agent/convert   -H "Authorization: Bearer rdg_..."   -H "Content-Type: application/json"   -d '{"filename":"site.dgm","source":"dgm: 1.0
nodes:
  a: Client
  b: {label: DB, role: store}
flow:
  - a ~> b: query
"}'

What comes back

Every conversion carries a fidelity ledger. It is never optional and never quiet about a loss — you know your own source and would notice anyway.

{
  "id": 41,
  "status": "done",
  "error": null,
  "source": { "format": "vsdx", "name": "network.vsdx", "nodes": 24 },
  "result": { "type": "architecture", "nodes": 24, "fidelity": "complete", "lang": "en" },
  "ledger": { "kept": ["24 nodes, 31 connections, 3 grouped"], "notes": [] },
  "artifacts": {
    "dgm": "https://...",
    "en": { "svg": "https://...", "png": "https://...", "pptx": "https://...", "mp4": "https://..." }
  }
}

Errors

401: No key, or a key that has been revoked.
403: A read-only key tried to convert, or the daily quota is spent.
404: That conversion belongs to another account.
422: The file could not be read as a diagram. The message says why, in a sentence.