Diagrams
Suggest diagram
Choose the kind of diagram for a request.
POST
/v1/diagrams/suggestTL;DR
| Question | Answer |
|---|---|
| What does it do? | Choose the kind of diagram for a request. |
| Which tool does the same? | suggest_diagram |
| What does it take? | A JSON body of type SuggestDiagramInput. |
| What does it return? | Status 200 with a body of type SuggestDiagramResponse. |
| 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 request in plain words, such as permission matrix for these endpoints and roles, and optional pasted data (a table, a list, or numbers by period), and answers with up to 3 diagram kinds, best first, each with a one-sentence reason, a confidence, the statements to use, and a short starter source that parses, built from the names and numbers it could read. A request that names no kind is a normal 200 result with low-confidence suggestions. Deterministic, and it lays nothing out.
Request body
The body has the type SuggestDiagramInput.
| Field | Type | Required | Description |
|---|---|---|---|
request | string | yes | What the picture is for, in plain words, such as "permission matrix for these endpoints and roles" or "how a refund moves between support and billing". at least 1 character; at most 1000 characters. |
data | string | no | Optional text to draw from: a pasted table, a list, numbers by period, or notes. Names and numbers in it are used in the starters. at most 20000 characters. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | The kinds that fit, best first, each with a starter, and what to call next. | SuggestDiagramResponse |
| 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 SuggestDiagramResponse.
| Field | Type | Required | Description |
|---|---|---|---|
request | string | yes | The request that was read. |
suggestions | object[] | yes | Up to 3, best first, one for each kind and style. |
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: why this kind fits. |
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. |
suggestions[].statements | string[] | yes | The few statements of this kind to write, as syntax. get_diagram_syntax with this kind has them all. |
importFormat | string | no | Present when the data is, or the request names, a file import_source reads (sql, openapi, compose, terraform, and so on): call import_source with this format and the file's text instead of editing a starter. |
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 |
suggest_diagram | The same operation as an MCP tool |
| Tool reference | The operations as callable tools |