Diagrams
Outline diagram
Describe diagram source as text.
POST
/v1/diagrams/outlineTL;DR
| Question | Answer |
|---|---|
| What does it do? | Describe diagram source as text. |
| Which tool does the same? | outline_diagram |
| What does it take? | A JSON body of type DiagramSourceInput. |
| What does it return? | Status 200 with a body of type OutlineResponse. |
| 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
Returns participants, steps, tables, and connections in reading order. Use it to check that a diagram says what was intended or as alt text. Source with errors is refused with 422.
Request body
The body has the type DiagramSourceInput.
| 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. |
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 text outline. | OutlineResponse |
| 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 OutlineResponse.
| Field | Type | Required | Description |
|---|---|---|---|
kind | string | yes | A diagram kind: flow, sequence, schema, git, gantt, class, state, timeline, journey, mindmap, treemap, pie, quadrant, layers, c4, matrix, sankey, xychart, tree, or swimlane today. Later versions add kinds, so expect others. |
summary | string | yes | One-line description. |
outline | string[] | yes | Lines in reading order: participants, steps, tables, and connections. |
See also
| Doc | Why |
|---|---|
| API reference | Every endpoint, and the error envelope |
| Schemas | Every request and response type |
outline_diagram | The same operation as an MCP tool |
| Tool reference | The operations as callable tools |