Vocabulary
Get diagram syntax
Get the diagram language reference.
GET
/v1/vocabularyTL;DR
| Question | Answer |
|---|---|
| What does it do? | Get the diagram language reference. |
| Which tool does the same? | get_diagram_syntax |
| What does it take? | kind, topic in the query string. |
| What does it return? | Status 200 with a body of type SyntaxResponse. |
| What can go wrong? | 400 the query 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); 429 too many requests. Every failure uses the one error envelope. |
What it does
With no kind, the overview: the tables every kind shares (node types with default icons and tones, arrows, line options, icon sets, limits, how to edit a picture) and one line about each kind. With a kind, that kind in full: its statements, limits, and one tested example, and the tables that apply to it. Built from the constants the parser uses, so it cannot drift.
Query parameters
| Field | Type | Required | Description |
|---|---|---|---|
kind | "flow" | "sequence" | "schema" | "git" | "gantt" | "class" | "state" | "timeline" | "journey" | "mindmap" | "treemap" | "pie" | "quadrant" | "layers" | "c4" | "matrix" | "sankey" | "xychart" | "tree" | "swimlane" | no | The one kind to read in full. Omit it for the overview: the language every kind shares and one line about each kind. |
topic | "import-formats" | no | import-formats: what import_source reads, draws, and takes, a line each. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | The language reference. | SyntaxResponse |
| 400 | The query 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 |
| 429 | Too many requests. | ErrorResponse |
Response body
A 200 answer has the type SyntaxResponse.
| Field | Type | Required | Description |
|---|---|---|---|
answer | string | yes | What this answer is: overview, a topic (import-formats), or the kind it describes in full (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). |
howToGetAKind | string | yes | In plain words: what this answer holds and how to get the rest. |
kinds | string[] | yes | Header keywords: the first line names the kind. |
kindDetails | object[] | yes | The overview lists every kind in the order of kinds, with its header, noun, and summary, and a pointer in more. A kind answer holds that kind alone, in full. |
kindDetails[].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. |
kindDetails[].header | string | yes | The header line, such as flow "Title". |
kindDetails[].noun | string | yes | What the kind's diagrams are called in a sentence, such as flow or database schema. |
kindDetails[].summary | string | yes | One sentence: what the kind draws. |
kindDetails[].statements | object[] | no | The statements the kind adds to the header. Empty for a kind whose language the shared tables of this reference already describe. |
kindDetails[].statements[].syntax | string | yes | The statement with its parts named, such as: task |
kindDetails[].statements[].meaning | string | yes | What the statement does, and what it needs. |
kindDetails[].statements[].example | string | yes | One line that parses. |
kindDetails[].limits | object[] | no | The quality thresholds the kind adds. Empty for a kind whose limits are in the limits table of this reference. |
kindDetails[].limits[].name | string | yes | What is counted, such as tasks. |
kindDetails[].limits[].value | integer | yes | More than this in one diagram draws a quality warning. |
kindDetails[].limits[].meaning | string | yes | Why the limit exists and what to do past it. |
kindDetails[].more | string | no | Only in the overview, where statements and limits are left out: what a call with this kind returns that the overview does not, and how to ask for it. |
nodeTypes | object[] | no | |
nodeTypes[].type | "person" | "agent" | "client" | "service" | "gateway" | "function" | "database" | "cache" | "queue" | "storage" | "identity" | "secret" | "external" | "step" | "decision" | "terminal" | yes | |
nodeTypes[].shape | "card" | "pill" | yes | How the node is drawn. |
nodeTypes[].isTinted | boolean | yes | True when the card is filled and outlined in its tone, as for decisions. |
nodeTypes[].defaultTone | "neutral" | "blue" | "violet" | "aqua" | "orange" | "green" | "amber" | "red" | yes | Color family used when tone= is not set. |
nodeTypes[].defaultIcon | string | null | yes | Icon used when icon= is not set, or null for none. |
nodeTypes[].isDashed | boolean | yes | True when the outline is dashed, as for external systems. |
nodeTypes[].usableAsActor | boolean | yes | True when a sequence diagram actor may use this type. |
tones | ("neutral" | "blue" | "violet" | "aqua" | "orange" | "green" | "amber" | "red")[] | no | |
directions | ("auto" | "right" | "down" | "left" | "up")[] | no | Values for direction= on a flow header. |
arrows | object[] | no | |
arrows[].token | string | yes | The arrow as written in source. |
arrows[].line | "solid" | "dashed" | "dotted" | yes | How the line is drawn. |
arrows[].heads | "end" | "both" | "none" | yes | Which ends carry an arrowhead. |
arrows[].meaning | string | yes | What the arrow says, so the right one is chosen. |
blockTypes | ("alt" | "opt" | "loop" | "par")[] | no | Frames a sequence diagram can wrap around messages. |
columnFlags | ("pk" | "fk" | "unique" | "nullable")[] | no | Flags a schema column row may carry. |
themes | ("light" | "dark")[] | no | |
iconSets | ("lucide" | "simple" | "status" | "aws" | "gcp" | "azure" | "alibaba" | "oci" | "ibm" | "cloudflare" | "digitalocean" | "vercel")[] | no | |
iconCount | integer | no | Number of bundled icons; use search_icons to find names. |
iconProviders | object[] | no | Cloud and platform providers, each an icon set holding the provider (set:cloud) and its products. |
iconProviders[].set | "aws" | "gcp" | "azure" | "alibaba" | "oci" | "ibm" | "cloudflare" | "digitalocean" | "vercel" | yes | Icon set prefix, as in aws:lambda. |
iconProviders[].title | string | yes | The provider the set stands for. |
iconProviders[].iconCount | integer | yes | Icons in the set: the provider itself (set:cloud) and its products. |
iconProviders[].example | string | yes | One icon of the set that is bundled, for example aws:lambda. |
overlay | object | no | A dashed frame around members that may sit in different groups; it owns none of them. |
overlay.options | string[] | yes | Options an overlay statement takes after its name, as in: overlay id "Name" members=a,b type=scale-group. |
overlay.frame | "solid" | "dashed" | "dotted" | yes | How an overlay is always drawn. |
overlay.meaning | string | yes | What an overlay is for, so it is used where a group would be wrong. |
group | object | no | How a flow group looks and what it accepts; its corner tab shows its icon and name. |
group.options | string[] | yes | Options a group statement takes after its name, as in: group id "Name" type=region provider=aws {. |
group.defaultTone | "neutral" | "blue" | "violet" | "aqua" | "orange" | "green" | "amber" | "red" | yes | Color family of a group with no type when tone= is not set. |
group.example | object | yes | A complete architecture diagram: typed groups nested by provider, a provider icon on every node, stack marks, and a dotted edge. Copy and edit it. |
group.example.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. |
group.example.title | string | yes | |
group.example.source | string | yes | A complete diagram that is checked by the build; copy and edit it. |
group.types | object[] | yes | Every group type. A type gives the group a default icon, tone, frame style, and a shade that deepens with nesting; icon= and tone= override them. |
group.types[].type | "cloud" | "account" | "region" | "zone" | "network" | "subnet" | "public-subnet" | "private-subnet" | "management-subnet" | "isolated-subnet" | "resource-group" | "cluster" | "scale-group" | "service-plan" | "web-tier" | "app-tier" | "data-tier" | "storage-account" | "messaging" | "edge" | "security" | "identity-boundary" | "trust-boundary" | "observability" | "ci-cd" | "environment" | "cloud-boundary" | "on-premises" | "client-side" | "external-systems" | yes | Value for type= on a group. |
group.types[].title | string | yes | What the frame is called in the text description. |
group.types[].meaning | string | yes | What the author means by this type, so the right one is chosen. |
group.types[].tone | "neutral" | "blue" | "violet" | "aqua" | "orange" | "green" | "amber" | "red" | yes | Color family the frame and tab get when tone= is not set. |
group.types[].frame | "solid" | "dashed" | "dotted" | yes | How the outline is drawn. |
group.types[].icon | string | yes | Icon in the corner tab when the group has no provider. |
group.types[].providerIcons | object | yes | Icon in the corner tab for each provider whose icon differs from the generic one, keyed by provider set. |
lineOptions | object[] | no | Options that animate a line (animate=on makes dashes travel toward the arrowhead) or number the steps of a flow or sequence (numbered=on, start=, and step= on a line). All are off by default. |
lineOptions[].key | string | yes | The option as written, such as animate or step. |
lineOptions[].scope | "header" | "line" | yes | header: on the flow or sequence header line. line: on an edge or a message. |
lineOptions[].values | string | yes | What the option takes. |
lineOptions[].meaning | string | yes | What it does, and the cases where it is refused. |
lineOptions[].example | string | yes | One line that parses. |
labelIcons | object[] | no | Edge labels that get a tick or cross automatically; icon=none on the edge removes it. |
labelIcons[].label | string | yes | An edge label that gets an icon automatically, matched whole and ignoring case. |
labelIcons[].icon | string | yes | The icon the label gets. |
verbIcons | object[] | no | The icons a flow edge label draws when it names a relationship with a verb. icon= on the edge wins, icon=none removes it, and icons=off on the header turns them all off. |
verbIcons[].icon | string | yes | The icon drawn in the label. |
verbIcons[].words | string[] | yes | Phrases that draw it: the whole label, or its first words followed by what is acted on ("reads orders"). |
style | string[] | no | How to make a flow diagram look finished: verbs on arrows, role= on lines that mean something, typed groups, product names. |
autoIcons | object | no | Items with no icon= get the icon their label names for certain (a brand, a cloud product, a common role). icon=none keeps one item plain; icons=off on the header keeps them all plain. |
autoIcons.key | string | yes | The header option: icons. |
autoIcons.values | string | yes | What it takes. |
autoIcons.meaning | string | yes | What it does, and how one item opts out. |
autoIcons.example | string | yes | One header line that parses. |
roleIcons | object[] | no | The plain icons for common roles, drawn on flow and sequence service and external items, C4 elements, layers blocks, mind map topics, and swimlane lanes. The last role word of the label wins. |
roleIcons[].icon | string | yes | The icon drawn. |
roleIcons[].words | string[] | yes | Whole words of a label of three words or fewer that draw it. |
statusIcons | object[] | no | Colored status and outcome icons: a green check, a red X, and so on. |
statusIcons[].ref | string | yes | Value for icon=, such as status:success. |
statusIcons[].tone | "neutral" | "blue" | "violet" | "aqua" | "orange" | "green" | "amber" | "red" | yes | Color the icon is always drawn in, whatever tone its owner has. |
statusIcons[].meaning | string | yes | What the icon says, so the right one is chosen. |
limits | object | no | Bounds and quality thresholds. |
limits.maxSourceLength | integer | yes | |
limits.maxFlowNodes | integer | yes | Quality lint: more nodes than this warns, for a diagram with no groups. |
limits.nodesPerGroup | integer | yes | Each group of a flow diagram raises the node limit by this many. |
limits.maxFlowNodesCeiling | integer | yes | The node limit never rises above this, whatever the groups. |
limits.maxSchemaTables | integer | yes | |
limits.maxSequenceActors | integer | yes | |
limits.maxNumberedSteps | integer | yes | More numbered steps than this in one diagram warns (W200). |
limits.maxStackMarks | integer | yes | Most technology marks a node carries in stack=. |
limits.targetWidth | integer | yes | Column width in px that diagrams are checked against. |
editing | object | no | How to edit an existing Plotwork SVG: read it back with read_diagram, change the source, draw it, and save or publish it again. |
editing.steps | string[] | yes | In order: how to change a diagram that already exists as a Plotwork SVG, a hosted link or a file in the repository. |
editing.embedSource | string | yes | When to set embedSource true on draw_diagram, render_diagram, or publish_diagram, and what it means for who can read the source. |
diagnosticCodes | object[] | no | |
diagnosticCodes[].name | string | yes | Identifier of the code. |
diagnosticCodes[].code | string | yes | The code to branch on, such as E120. |
diagnosticCodes[].severity | "error" | "warning" | yes | |
examples | object[] | yes | Tested examples: the overview holds the ones for the kinds the shared tables describe in full, a kind answer holds its own. |
examples[].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. |
examples[].title | string | yes | |
examples[].source | string | yes | A complete diagram that is checked by the build; copy and edit it. |
importFormats | object[] | no | Only for topic import-formats: every format import_source reads, a line each. |
importFormats[].format | string | yes | The format, as import_source takes it. |
importFormats[].reads | string | yes | What it reads. |
importFormats[].draws | string | yes | The diagram it draws. |
importFormats[].options | string | yes | The options it takes. |
See also
| Doc | Why |
|---|---|
| API reference | Every endpoint, and the error envelope |
| Schemas | Every request and response type |
get_diagram_syntax | The same operation as an MCP tool |
| Tool reference | The operations as callable tools |