# Outline diagram

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

Describe diagram source as text.

`POST /v1/diagrams/outline`

## TL;DR

| Question | Answer |
|---|---|
| What does it do? | Describe diagram source as text. |
| Which tool does the same? | [`outline_diagram`](https://docs.plotwork.dev/mcp/tools/outline-diagram.md) |
| What does it take? | A JSON body of type [`DiagramSourceInput`](https://docs.plotwork.dev/api/schemas.md#diagramsourceinput). |
| What does it return? | Status 200 with a body of type [`OutlineResponse`](https://docs.plotwork.dev/api/schemas.md#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`](https://docs.plotwork.dev/api/schemas.md#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. |

## Responses

| Status | Meaning | Body |
|---|---|---|
| 200 | The text outline. | [`OutlineResponse`](https://docs.plotwork.dev/api/schemas.md#outlineresponse) |
| 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 [`OutlineResponse`](https://docs.plotwork.dev/api/schemas.md#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](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 |
| [`outline_diagram`](https://docs.plotwork.dev/mcp/tools/outline-diagram.md) | The same operation as an MCP tool |
| [Tool reference](https://docs.plotwork.dev/mcp/tools.md) | The operations as callable tools |