Markdown
Plan document diagrams
Find the sections of a document a picture would help.
POST
/v1/markdown/planTL;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 |
| What does it take? | A JSON body of type PlanDocumentInput. |
| What does it return? | Status 200 with a body of type 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.
| 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 |
| 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 |
| 429 | Too many requests. | ErrorResponse |
Response body
A 200 answer has the type 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 | Every endpoint, and the error envelope |
| Schemas | Every request and response type |
plan_document_diagrams | The same operation as an MCP tool |
| Tool reference | The operations as callable tools |