> ## Documentation Index
> Fetch the complete documentation index at: https://docs.diagramkit.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/presets.md). |
| `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:

```json theme={null}
{
  "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](/presets.md), 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. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.