Patterns
Get pattern
Read a pattern filled for a flavour.
POST
/v1/patterns/getTL;DR
| Question | Answer |
|---|---|
| What does it do? | Read a pattern filled for a flavour. |
| Which tool does the same? | get_pattern |
| What does it take? | A JSON body of type GetPatternInput. |
| What does it return? | Status 200 with a body of type GetPatternResponse. |
| 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 pattern id from the find route, a flavour (neutral by default, or aws, azure, gcp), and optional slot values that rename its parts. Answers with the valid Plotwork source, every slot with its meaning and value, the advice on what to keep, rename, and split, and the groups and nodes as a flat tree. An unknown id, flavour, or slot, or a value with a quote in it, is a normal 200 result with found false and every problem with its code and a hint, never an error. Use it when you will edit the source before drawing; use the draw route when only the names change.
Request body
The body has the type GetPatternInput.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | The pattern id, as find_pattern returns it, such as three-tier-network. at least 1 character; at most 60 characters. |
provider | "neutral" | "aws" | "azure" | "gcp" | no | neutral (generic glyphs, no vendor names; the default), or aws, azure, or gcp for that provider's icons. Not every pattern comes in every flavour; the answer lists the ones it has. default "neutral". |
slots | object | no | Slot values keyed by slot id, such as {"office": "Branch office"}: plain text of up to 60 characters, no quotes or line breaks. Omit a slot to keep its default. get_pattern lists the slots and what they mean. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | The filled pattern, or the problems that stopped it. | GetPatternResponse |
| 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 GetPatternResponse.
| Field | Type | Required | Description |
|---|---|---|---|
found | boolean | yes | True when the pattern and flavour exist and the slot values are usable. When false, problems says why and nothing else is filled. |
id | string | yes | The pattern id that was asked for. |
title | string | null | yes | |
patternSummary | string | null | yes | One sentence: what the pattern shows. |
whenToUse | string | null | yes | |
kind | string | null | 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. |
flavour | "neutral" | "aws" | "azure" | "gcp" | null | yes | The flavour that was filled. |
flavours | ("neutral" | "aws" | "azure" | "gcp")[] | yes | Every flavour this pattern comes in; empty when the pattern was not found. |
source | string | null | yes | Plotwork source, valid and ready to use; null when not found. |
slots | object[] | yes | Every slot the source uses, with the value it has. |
slots[].id | string | yes | The slot id; the key to use in slots. |
slots[].value | string | yes | The text the slot has in the source: the value sent, or the default. |
slots[].default | string | yes | The default text. |
slots[].meaning | string | yes | What belongs in this slot. |
slots[].isDefault | boolean | yes | True when the slot kept its default. |
notes | object | null | yes | How to adapt the pattern: what to keep, what to rename, and when to split. |
notes.keep | string | yes | What to leave exactly as it is. |
notes.rename | string | yes | What to rename or replace, and how. |
notes.split | string | yes | When the diagram has grown too big, and where to cut it. |
problems | object[] | yes | Mistakes in the id, the flavour, or the slot values, each with a fix. Empty when found. |
problems[].code | "unknown-pattern" | "unknown-flavour" | "unknown-slot" | "bad-slot-value" | "bad-source" | yes | |
problems[].message | string | yes | |
problems[].hint | string | yes | How to fix it. |
tree | object[] | yes | The groups, overlays, and nodes as drawn, depth first, so you can see what to rename. |
tree[].depth | integer | yes | How deep the item sits: 0 for the top level. |
tree[].kind | "group" | "overlay" | "node" | "actor" | "table" | yes | |
tree[].id | string | yes | The id written in the source. |
tree[].label | string | yes | |
tree[].type | string | null | yes | The group type, node type, or actor type; null for a table or an untyped group. |
outline | string[] | yes | The text description of the diagram. |
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 |
get_pattern | The same operation as an MCP tool |
| Tool reference | The operations as callable tools |