Diagrams
Render diagram
Render diagram source to SVG.
POST
/v1/diagrams/renderTL;DR
| Question | Answer |
|---|---|
| What does it do? | Render diagram source to SVG. |
| Which tool does the same? | render_diagram |
| What does it take? | A JSON body of type RenderInput. |
| What does it return? | Status 200 with a body of type 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.
| 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 (opens in a new tab). |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | The rendered diagram. | RenderResponse |
| 400 | The body failed schema validation. | ErrorResponse |
| 401 | The API key is missing or not valid. | ErrorResponse |
| 403 | The account is on the Free plan, which does not include the REST drawing and checking routes (plan.rest_not_included). | ErrorResponse |
| 413 | The body is larger than the size cap. | ErrorResponse |
| 422 | The diagram source has errors; the diagnostics are in details. | ErrorResponse |
| 429 | Too many requests. | ErrorResponse |
Response body
A 200 answer has the type 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 | Every endpoint, and the error envelope |
| Schemas | Every request and response type |
render_diagram | The same operation as an MCP tool |
| Tool reference | The operations as callable tools |