# Render diagram

> Page: https://docs.plotwork.dev/api/post-v1-diagrams-render. Index of every page: https://docs.plotwork.dev/llms.txt

Render diagram source to SVG.

`POST /v1/diagrams/render`

## TL;DR

| Question | Answer |
|---|---|
| What does it do? | Render diagram source to SVG. |
| Which tool does the same? | [`render_diagram`](https://docs.plotwork.dev/mcp/tools/render-diagram.md) |
| What does it take? | A JSON body of type [`RenderInput`](https://docs.plotwork.dev/api/schemas.md#renderinput). |
| What does it return? | Status 200 with a body of type [`RenderResponse`](https://docs.plotwork.dev/api/schemas.md#renderresponse). |
| What can go wrong? | `400` the body failed schema validation; `401` the api key is missing or not valid; `403` the account is on the free plan, which does not include the rest drawing and checking routes (plan.rest_not_included); `413` the body is larger than the size cap; `422` the diagram source has errors; the diagnostics are in details; `429` too many requests. Every failure uses the one error envelope. |

## What it does

Renders valid source to a self-contained SVG string in the light or dark theme and returns its pixel size and quality warnings. Source with errors is refused with 422 and the same diagnostics the validate route returns, in details.

## Request body

The body has the type [`RenderInput`](https://docs.plotwork.dev/api/schemas.md#renderinput).

| Field | Type | Required | Description |
|---|---|---|---|
| `source` | `string` | yes | Diagram source; the first line is the header, such as flow "Title" (draw_diagram lists every kind). at least 1 character; at most 50000 characters. |
| `theme` | `"light" \| "dark" \| "auto"` | no | Color scheme to paint with: light, dark, or auto for one picture that follows the reader's light or dark setting. default "light". |
| `idPrefix` | `string` | no | Prefix for element ids; set it when inlining several diagrams into one page. at most 32 characters; pattern `^[A-Za-z][A-Za-z0-9_-]*$`. |
| `embedSource` | `boolean` | no | Write the source into the SVG metadata so read_diagram can give it back. Set it true when you save the SVG into a repository; anyone with the file can then read the source. Default false. default false. |
| `settings` | `object` | no | The repo's plotwork.config.json, if any. Schema: https://docs.plotwork.dev/schemas/plotwork.config.json. |

## Responses

| Status | Meaning | Body |
|---|---|---|
| 200 | The rendered diagram. | [`RenderResponse`](https://docs.plotwork.dev/api/schemas.md#renderresponse) |
| 400 | The body failed schema validation. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 401 | The API key is missing or not valid. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 403 | The account is on the Free plan, which does not include the REST drawing and checking routes (plan.rest_not_included). | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 413 | The body is larger than the size cap. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 422 | The diagram source has errors; the diagnostics are in details. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 429 | Too many requests. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |

## Response body

A 200 answer has the type [`RenderResponse`](https://docs.plotwork.dev/api/schemas.md#renderresponse).

| Field | Type | Required | Description |
|---|---|---|---|
| `svg` | `string` | yes | Self-contained SVG markup with an accessible title and description. |
| `theme` | `"light" \| "dark" \| "auto"` | yes | The color scheme used. |
| `size` | `Size` | yes | Natural size of a rendered diagram in px. |
| `size.width` | `integer` | yes | Width in px. minimum 1. |
| `size.height` | `integer` | yes | Height in px. minimum 1. |
| `warnings` | `Diagnostic[]` | yes |  |
| `warnings[].code` | `"E100" \| "E101" \| "E110" \| "E111" \| "E120" \| "E121" \| "E122" \| "E123" \| "E124" \| "E125" \| "E130" \| "E131" \| "E132" \| "E133" \| "E134" \| "E135" \| "E136" \| "E137" \| "E138" \| "E139" \| "E140" \| "W200" \| "W201" \| "W202" \| "W203" \| "W204" \| "W205" \| "W206" \| "W207" \| "W500" \| "M100" \| "M101" \| "M102" \| "M103" \| "M104" \| "M110" \| "M200" \| "M201" \| "M202" \| "M203" \| "M204" \| "M205" \| "M206" \| "M207" \| "M208" \| "M209" \| "M210" \| "M211" \| "M212" \| "M213" \| "M214" \| "M215" \| "M216" \| "M217" \| "M218" \| "E300" \| "E301" \| "E302" \| "E303" \| "E304" \| "W300" \| "W301" \| "W302" \| "W303" \| "M120" \| "M220" \| "M221" \| "M222" \| "E340" \| "E341" \| "E342" \| "E343" \| "E344" \| "E345" \| "W320" \| "W321" \| "W322" \| "W323" \| "M240" \| "M241" \| "M242" \| "E360" \| "E361" \| "E362" \| "E363" \| "E364" \| "E365" \| "E366" \| "E367" \| "W330" \| "W331" \| "W332" \| "W333" \| "W334" \| "M250" \| "M251" \| "E400" \| "E401" \| "E402" \| "E403" \| "W350" \| "W351" \| "W352" \| "W353" \| "M270" \| "M271" \| "E420" \| "E421" \| "E422" \| "E423" \| "E424" \| "W360" \| "W361" \| "W362" \| "W363" \| "W364" \| "M180" \| "M280" \| "M281" \| "M282" \| "E320" \| "E321" \| "E322" \| "E323" \| "E324" \| "E325" \| "E326" \| "E327" \| "E328" \| "E329" \| "E330" \| "W310" \| "W311" \| "W312" \| "W313" \| "W314" \| "M130" \| "M131" \| "M132" \| "M230" \| "M231" \| "M232" \| "M233" \| "M234" \| "M235" \| "M236" \| "M237" \| "M238" \| "E380" \| "E381" \| "E382" \| "E383" \| "W340" \| "W341" \| "W342" \| "W343" \| "M260" \| "I100" \| "I101" \| "I102" \| "I103" \| "I104" \| "I105" \| "I200" \| "I201" \| "I202" \| "I203" \| "I204" \| "I206" \| "R100" \| "R101" \| "R200" \| "R201" \| "R202" \| "R203" \| "R204" \| "R205" \| "R206" \| "R207" \| "S100" \| "S200" \| "S101" \| "S102" \| "S103" \| "S104" \| "S201" \| "S202" \| "S203"` | yes | Stable code to branch on; E-codes are errors, W-codes are warnings. |
| `warnings[].severity` | `"error" \| "warning"` | yes | Errors stop rendering; warnings never do. |
| `warnings[].message` | `string` | yes | What is wrong, in one sentence. |
| `warnings[].line` | `integer` | yes | 1-based line in the submitted source. minimum 1. |
| `warnings[].column` | `integer` | yes | 1-based column in that line. minimum 1. |
| `warnings[].length` | `integer` | yes | Number of characters the problem covers. minimum 1. |
| `warnings[].hint` | `string \| null` | yes | A concrete suggestion for fixing it, or null. |

## See also

| Doc | Why |
|---|---|
| [API reference](https://docs.plotwork.dev/api/reference.md) | Every endpoint, and the error envelope |
| [Schemas](https://docs.plotwork.dev/api/schemas.md) | Every request and response type |
| [`render_diagram`](https://docs.plotwork.dev/mcp/tools/render-diagram.md) | The same operation as an MCP tool |
| [Tool reference](https://docs.plotwork.dev/mcp/tools.md) | The operations as callable tools |