# Search icons

> Page: https://docs.plotwork.dev/api/get-v1-icons. Index of every page: https://docs.plotwork.dev/llms.txt

Find bundled icon names.

`GET /v1/icons`

## TL;DR

| Question | Answer |
|---|---|
| What does it do? | Find bundled icon names. |
| Which tool does the same? | [`search_icons`](https://docs.plotwork.dev/mcp/tools/search-icons.md) |
| What does it take? | `q`, `limit` in the query string. |
| What does it return? | Status 200 with a body of type [`IconSearchResponse`](https://docs.plotwork.dev/api/schemas.md#iconsearchresponse). |
| 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

Returns set:name references such as lucide:database, simple:postgresql, or aws:lambda, best match first. It understands product names and phrases, so lambda, s3, gke, or serverless function each find the right provider icon. Unknown icon names are rejected when a diagram is validated.

## Query parameters

| Field | Type | Required | Description |
|---|---|---|---|
| `q` | `string` | yes | Words to look for: a name such as "database", an idea such as "token exchange", or a cloud product such as "lambda" or "gke". |
| `limit` | `integer` | no | Most names to return. |

## Responses

| Status | Meaning | Body |
|---|---|---|
| 200 | Matching names. | [`IconSearchResponse`](https://docs.plotwork.dev/api/schemas.md#iconsearchresponse) |
| 400 | The query 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) |
| 429 | Too many requests. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |

## Response body

A 200 answer has the type [`IconSearchResponse`](https://docs.plotwork.dev/api/schemas.md#iconsearchresponse).

| Field | Type | Required | Description |
|---|---|---|---|
| `query` | `string` | yes | The query that was searched. |
| `items` | `string[]` | yes | Matching icon references as set:name, best match first. |

## 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 |
| [`search_icons`](https://docs.plotwork.dev/mcp/tools/search-icons.md) | The same operation as an MCP tool |
| [Tool reference](https://docs.plotwork.dev/mcp/tools.md) | The operations as callable tools |