# Plan document diagrams

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

Find the sections of a document a picture would help.

`POST /v1/markdown/plan`

## TL;DR

| Question | Answer |
|---|---|
| What does it do? | Find the sections of a document a picture would help. |
| Which tool does the same? | [`plan_document_diagrams`](https://docs.plotwork.dev/mcp/tools/plan-document-diagrams.md) |
| What does it take? | A JSON body of type [`PlanDocumentInput`](https://docs.plotwork.dev/api/schemas.md#plandocumentinput). |
| What does it return? | Status 200 with a body of type [`PlanDocumentResponse`](https://docs.plotwork.dev/api/schemas.md#plandocumentresponse). |
| 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; `429` too many requests. Every failure uses the one error envelope. |

## What it does

Takes a whole document (Markdown, HTML, or plain text pasted from a wiki) and answers with the sections a picture would help, in document order: the heading and its line, the diagram kind, a one-sentence reason, a confidence, and a starter source drafted from the section's own lists, tables, numbers, and dates. Sections that read well as text, or already hold a diagram fence, are left out, and every cap that left something out is stated in caps. Draws nothing, writes no file, and lays nothing out.

## Request body

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

| Field | Type | Required | Description |
|---|---|---|---|
| `document` | `string` | yes | The whole document: Markdown, plain text pasted from Confluence, Notion, or Google Docs, or HTML. Up to 10000000 characters. at least 1 character; at most 10000000 characters. |
| `maxSuggestions` | `integer` | no | Most sections to suggest a picture for, up to 12. The strongest are kept, in document order. The default is 8. minimum 1; maximum 12; default 8. |

## Responses

| Status | Meaning | Body |
|---|---|---|
| 200 | The sections a picture would help, each with a starter, and what to do next. | [`PlanDocumentResponse`](https://docs.plotwork.dev/api/schemas.md#plandocumentresponse) |
| 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) |
| 429 | Too many requests. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |

## Response body

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

| Field | Type | Required | Description |
|---|---|---|---|
| `summary` | `string` | yes | One sentence: how many sections were read and how many would gain a picture. |
| `format` | `"markdown" \| "html" \| "text"` | yes | How the document was read: Markdown headings, HTML h1 to h6, or plain text with heading-like lines. |
| `sectionsRead` | `integer` | yes | Sections read, up to the cap. |
| `suggestions` | `object[]` | yes | In document order. Sections that read well as text, or already have a diagram, are not listed. |
| `suggestions[].heading` | `string` | yes | The heading of the section, as written. |
| `suggestions[].line` | `integer` | yes | The 1-based line of the heading in the document that was sent. minimum 1. |
| `suggestions[].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. |
| `suggestions[].style` | `string \| null` | yes | The style the starter uses: compare, score, raci, or risk for a matrix, files or org for a tree; null for the kind's only style. |
| `suggestions[].why` | `string` | yes | One sentence: what in the section points to this kind. |
| `suggestions[].confidence` | `"high" \| "medium" \| "low"` | yes | high: the text names this kind of picture or its shape fits it exactly. medium: it leans toward it. low: a fallback worth considering. |
| `suggestions[].starter` | `string` | yes | A short Plotwork source of this kind that parses without errors: built from the names and numbers in the text where it could find them, otherwise a small example to edit. Replace every placeholder before you draw it. |
| `suggestions[].tailored` | `boolean` | yes | True when the starter uses names or numbers from the text; false when it is the kind's small example. |
| `caps` | `object` | yes |  |
| `caps.hit` | `boolean` | yes | True when a cap left something out; messages says what. |
| `caps.messages` | `string[]` | yes |  |
| `caps.maxSections` | `integer` | yes |  |
| `caps.maxSuggestions` | `integer` | yes |  |
| `next` | `string` | yes | The next step in one sentence. |

## 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 |
| [`plan_document_diagrams`](https://docs.plotwork.dev/mcp/tools/plan-document-diagrams.md) | The same operation as an MCP tool |
| [Tool reference](https://docs.plotwork.dev/mcp/tools.md) | The operations as callable tools |