# Find pattern

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

Find a ready-made architecture diagram.

`POST /v1/patterns/find`

## TL;DR

| Question | Answer |
|---|---|
| What does it do? | Find a ready-made architecture diagram. |
| Which tool does the same? | [`find_pattern`](https://docs.plotwork.dev/mcp/tools/find-pattern.md) |
| What does it take? | A JSON body of type [`FindPatternInput`](https://docs.plotwork.dev/api/schemas.md#findpatterninput). |
| What does it return? | Status 200 with a body of type [`FindPatternResponse`](https://docs.plotwork.dev/api/schemas.md#findpatternresponse). |
| 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 serverless api or two availability zones, and optionally a provider flavour, tags, a diagram kind, and a limit of up to 5. Answers with the best matches first, each with an id, a one-sentence summary, its tags, and the flavours it comes in, and never the source, so a search stays small. Nothing that fits is a normal 200 result with no matches and a hint for what to try next, never an error. Start here when a request names a common architecture, then read the pattern with the get route or draw it with the draw route.

## Request body

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

| Field | Type | Required | Description |
|---|---|---|---|
| `query` | `string` | yes | The architecture wanted, in plain words, such as "three tier network". at least 1 character; at most 200 characters. |
| `provider` | `"neutral" \| "aws" \| "azure" \| "gcp"` | no | Only patterns that come in this flavour: neutral, aws, azure, or gcp. |
| `tags` | `string[]` | no | Tags every result must have, such as "load balancer". Up to 5. |
| `kind` | `"flow" \| "sequence" \| "schema" \| "git" \| "gantt" \| "class" \| "state" \| "timeline" \| "journey" \| "mindmap" \| "treemap" \| "pie" \| "quadrant" \| "layers" \| "c4" \| "matrix" \| "sankey" \| "xychart" \| "tree" \| "swimlane"` | no | Only patterns of this diagram kind: flow, sequence, schema, git, gantt, class, state, timeline, journey, mindmap, treemap, pie, quadrant, layers, c4, matrix, sankey, xychart, tree, or swimlane. |
| `limit` | `integer` | no | Most results to return, up to 5. minimum 1; maximum 5; default 5. |

## Responses

| Status | Meaning | Body |
|---|---|---|
| 200 | The matching patterns, best first, and what to call next. | [`FindPatternResponse`](https://docs.plotwork.dev/api/schemas.md#findpatternresponse) |
| 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 [`FindPatternResponse`](https://docs.plotwork.dev/api/schemas.md#findpatternresponse).

| Field | Type | Required | Description |
|---|---|---|---|
| `query` | `string` | yes | The query that was searched. |
| `matches` | `object[]` | yes | Up to the limit, best match first. Empty when nothing fits. |
| `matches[].id` | `string` | yes | The pattern id, as find_pattern returns it, such as three-tier-network. at least 1 character; at most 60 characters. |
| `matches[].title` | `string` | yes |  |
| `matches[].summary` | `string` | yes | One sentence: what the diagram shows. |
| `matches[].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. |
| `matches[].tags` | `string[]` | yes |  |
| `matches[].providers` | `("neutral" \| "aws" \| "azure" \| "gcp")[]` | yes | The flavours the pattern comes in. |
| `matches[].score` | `number` | yes | How well it matches; only the order of the results is meaningful. |
| `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 |
| [`find_pattern`](https://docs.plotwork.dev/mcp/tools/find-pattern.md) | The same operation as an MCP tool |
| [Tool reference](https://docs.plotwork.dev/mcp/tools.md) | The operations as callable tools |