---
title: "Diagram Generation"
description: "Prompt briefs, design selection modes, options, and refinement."
---

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

# Diagram Generation

Generate vector SVG diagrams using the `POST /rest/v1/generations` endpoint.

---

## Endpoint Details

- **Method**: `POST`
- **Path**: `/rest/v1/generations`
- **Base URL**: `https://svgdiagram.ai`

> **Note**
>
> **OpenAPI Notice**: The endpoint reference at `https://svgdiagram.ai/openapi.json` currently does not include a request body schema for `POST /rest/v1/generations`. Use the body parameters documented below as the request guide.

---

## Request Body Parameters

```json
{
  "prompt": "Sequence diagram of OAuth2 Authorization Code flow with PKCE",
  "design": "auto",
  "appearance": "light",
  "fontId": "inter",
  "colors": {
    "source": "automatic"
  },
  "options": {}
}
```

| Field | Type | Description |
| :--- | :--- | :--- |
| `prompt` | `string` | **Required**. Natural language brief describing the diagram content, structure, steps, or components. |
| `design` | `string` | Optional. Selection mode or specific design ID: `"auto"` (default), `"creative"`, or a published design ID (e.g. `timeline-zigzag-icon-cards`). |
| `appearance` | `string` | Optional. Neutral appearance mode: `"light"` or `"dark"`. |
| `fontId` | `string` | Optional. Bundled font: `"inter"`, `"source-sans-3"`, `"archivo"`, or `"barlow-condensed"`. |
| `colors` | `object` | Optional. Selects automatic, brand, saved-palette, or custom-palette colors. Each `source` accepts a different object shape; see examples below. |
| `options` | `object` | Optional. Key-value option overrides for specific published designs. |

Valid `colors` examples:

```json
{ "source": "automatic" }
{ "source": "custom", "palette": ["#6366f1", "#10b981"] }
{ "source": "brand", "name": "Product", "palette": ["#6366f1", "#10b981"], "fontId": "inter" }
{ "source": "palette", "paletteId": "<palette-uuid>" }
{ "source": "saved", "palette": ["#6366f1", "#10b981"], "name": "Product" }
```

`brand` accepts optional `name`, `palette`, and `fontId`; `saved` accepts optional `name`. `custom` and `saved` require a palette of 1–8 `#rgb` or `#rrggbb` values.

---

## Design Selection Modes

`svgdiagram.ai` supports two distinct generation paths:

1. **Automatic (`design: "auto"`)**: The model evaluates published stable designs in the catalog. If a published design fits the request, it populates its structural parameters. If no published design fits, it seamlessly routes to the creative sandbox.
2. **Creative Sandbox (`design: "creative"`)**: The model generates custom, free-form vector JSX rendered in an isolated sandbox environment.
3. **Named Design ID (`design: "<id>"`)**: Explicitly names a published design (for example, `timeline-zigzag-icon-cards`). Use an ID returned by `GET /rest/v1/designs`.

Query available published catalog designs using `GET /rest/v1/designs`.

---

## Diagram Refinement & Iteration

Refine a completed creative diagram by passing its ID in `from` and a `refine` instruction:

```json
{
  "from": "e8b21c40-3a52-4f81-8b09-1a052e690f12",
  "refine": {
    "instruction": "Add a Redis caching layer between the API gateway and microservices"
  }
}
```

Alternatively, adjust detail density relatively:

```json
{
  "from": "e8b21c40-3a52-4f81-8b09-1a052e690f12",
  "refine": {
    "detail": "more"
  }
}
```

- Refinements cost **1 credit**.
- Retries and refinements preserve parent context and produce child attempts linked by `rootId`.

Source: https://docs.svgdiagram.ai/generation/index.mdx