Make a diagram

POST /api/v1/diagrams. Making one takes about a minute, sometimes two.

Parameter	In	Values	Default	What it does
`prompt`	body	text, 1 to 4,000 characters	required	What to draw. Paste notes, data or a passage from your text into it.
`images`	body	up to 4 objects: `{"name", "mime", "data_base64"}`	`[]`	Pictures to work from: a sketch, a photo of a whiteboard, an existing figure, a logo. `mime` is `image/png`, `image/jpeg`, `image/webp` or `image/gif`; `data_base64` is the file’s bytes in standard base64, without a `data:` prefix. Up to 6 MB and 25 megapixels each.
`animate`	body	`true`, `false`	`false`, or `true` for the `ad` and `explainer_video` presets	Make it animated in the same request.
`preset`	body	`docs`, `blog`, `social`, `carousel`, `ad`, `data_story`, `explainer_video`, or null	none	Where the diagram will be used. See Presets.
`max_pages`	body	1 to 100	30	The most pages a set may draw. A set with more fails with `too_many_pages` before anything is drawn or charged. Also on revisions and `animate`.
`wait`	body	whole seconds, 0 to 300	`0`	Hold the request open until the diagram is done or this time passes. With 0 you get `202` and the job at once.
`Idempotency-Key`	header	any text, up to 200 characters	none	Name each figure (`book-7-figure-3.2`). A request with a key this account has used before returns that job, whatever its body, instead of making another. Keys do not expire.

Write the prompt the way you would brief an illustrator: what the figure must show, who it is for, the labels and numbers it needs, and the size it will be seen at (“for a phone screen”, “a full textbook page”). The API never stops to ask questions: when something is ambiguous it makes a reasonable choice and says so in description.

Wait for it

Send wait to hold the request open, up to 300 seconds. If the diagram is not done by then you get 202 with the job; call GET /api/v1/diagrams/:id?wait=60 until status is succeeded or failed. Set your HTTP client’s timeout above wait (wait plus 30 seconds). A job that runs longer than 15 minutes fails; a set of pages has more time, about 6 minutes for every 4 pages after the first 4. A failed request leaves the diagram as it was (a new one has no version); send it again with a new Idempotency-Key.

Parameter	On	Values	Default	What it does
`wait`	`GET /api/v1/diagrams/:id`	whole seconds, 0 to 300	`0`	Answer when the job finishes or after this long, whichever is first.
`limit`	`GET /api/v1/diagrams`	1 to 100	`20`	How many recent diagrams to list.

A finished job:

{
  "id": "c73141db-d6c0-4e4b-94ee-0aa757886498",
  "status": "succeeded",
  "title": "How the water cycle works",
  "description": "The sun drives evaporation from the ocean; vapour condenses into clouds, falls as rain and collects in rivers. It assumes a simplified cycle without groundwater.",
  "version": 1,
  "animated": false,
  "progress": null,
  "image_url": "https://app.diagramkit.ai/api/v1/diagrams/c73141db-…/image.png",
  "downloads": {
    "png": "https://app.diagramkit.ai/api/v1/diagrams/c73141db-…/image.png",
    "jpg": "…/image.jpg", "svg": "…/image.svg", "pdf": "…/image.pdf"
  },
  "error": null,
  "created_at": "2026-10-15T14:49:58.000Z"
}

Field	Type	Meaning
`id`	string (UUID)	The diagram. Use it in every other call.
`status`	`queued`, `running`, `succeeded`, `failed`	The latest request on this diagram: the first one or the latest change.
`title`	string or null	The diagram’s title, once it has one.
`description`	string or null	What the diagram shows and any assumptions it made. Read it: it says when something was ambiguous.
`version`	number	How many versions it has. 0 until the first is made; each change adds one.
`animated`	`true`, `false`	Whether the latest version is animated, so `animation.mp4` and `.gif` work.
`preset`	string or null	The diagram’s preset, or null.
`progress`	string or null	While queued or running, what is happening (“Drawing the diagram”).
`image_url`	string or null	The PNG of the latest version, once the job has succeeded.
`downloads`	object or null	Links to every format of the latest version: `png`, `jpg`, `svg`, `pdf`, and `mp4` and `gif` when animated. null until there is a version. Send your key with them.
`recommended_download`	`{"format", "url", "options"}`	With a preset, once there is a version: the download it offers first (`options` are the query parameters in `url`). Left out without a preset.
`error`	`{"type", "message"}` or null	Why a failed job failed. `type` is `no_credits` (the balance cannot pay for the planned pages), `too_many_pages` (a set longer than `max_pages`, or than 100 pages), or `generation_failed`. The first two are refused before anything is drawn or charged; `message` says how many pages were planned and what they cost.
`created_at`	ISO 8601 time	When the diagram was first requested.

Get started

Diagrams

Guides

More

Wait for it

​Wait for it

Wait for it