# Map icons

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

Choose icons for many names at once.

`POST /v1/icons/map`

## TL;DR

| Question | Answer |
|---|---|
| What does it do? | Choose icons for many names at once. |
| Which tool does the same? | [`map_icons`](https://docs.plotwork.dev/mcp/tools/map-icons.md) |
| What does it take? | A JSON body of type [`MapIconsInput`](https://docs.plotwork.dev/api/schemas.md#mapiconsinput). |
| What does it return? | Status 200 with a body of type [`MapIconsResponse`](https://docs.plotwork.dev/api/schemas.md#mapiconsresponse). |
| 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 up to 40 service or product names and an optional cloud provider, and answers for each name with one icon to write as icon=, or, when the name could mean more than one icon, the candidates to choose from. It never guesses: a name that matches nothing is listed as a gap with a neutral fallback. A name with no match is a normal 200 result, never an error. Prefer this route over calling the icon search route once per name; use the search route when you are exploring one idea.

## Request body

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

| Field | Type | Required | Description |
|---|---|---|---|
| `names` | `string[]` | yes | Services, products, or ideas to find icons for, written as the user wrote them ("S3", "Postgres", "load balancer"). Up to 40 names of up to 80 characters. |
| `provider` | `"aws" \| "gcp" \| "azure" \| "alibaba" \| "oci" \| "ibm" \| "cloudflare" \| "digitalocean" \| "vercel"` | no | The cloud the architecture runs on. A name is looked up there first, so "queue" finds aws:sqs for aws. Omit it when the names are not tied to one provider. |

## Responses

| Status | Meaning | Body |
|---|---|---|
| 200 | One icon decision per name, and the names that found no icon. | [`MapIconsResponse`](https://docs.plotwork.dev/api/schemas.md#mapiconsresponse) |
| 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 [`MapIconsResponse`](https://docs.plotwork.dev/api/schemas.md#mapiconsresponse).

| Field | Type | Required | Description |
|---|---|---|---|
| `provider` | `"aws" \| "gcp" \| "azure" \| "alibaba" \| "oci" \| "ibm" \| "cloudflare" \| "digitalocean" \| "vercel" \| null` | yes | The provider hint that was used, or null. |
| `results` | `object[]` | yes | One entry per name that matched something, in the order sent. |
| `results[].name` | `string` | yes | The name exactly as it was sent. |
| `results[].resolved` | `boolean` | yes | True when icon holds the one icon to use. False when the name could mean more than one: choose from candidates, or ask the user. |
| `results[].icon` | `string \| null` | yes | The icon to write as icon=, such as aws:lambda; null when resolved is false. |
| `results[].confidence` | `"exact" \| "strong" \| "ambiguous"` | yes | exact: the name is the icon or product name. strong: the name clearly points at this icon and no other provider competes. ambiguous: several icons fit, or the match is by idea only. |
| `results[].alternatives` | `string[]` | yes | Up to 3 other icons that also fit a resolved name, best first. Empty when none. |
| `results[].candidates` | `string[]` | yes | When resolved is false, the icons that fit, best first (up to 4). Empty when resolved. |
| `gaps` | `object[]` | yes | Names that matched nothing, in the order sent. |
| `gaps[].name` | `string` | yes | The name that matched no icon. |
| `gaps[].fallback` | `string` | yes | A neutral icon to use instead, or leave icon= out so the node type draws its own. |
| `gaps[].reason` | `string` | yes | Why there is no match, and what to try. |
| `resolvedCount` | `integer` | yes | How many names have one icon to use. |
| `ambiguousCount` | `integer` | yes | How many names need a choice from candidates. |
| `gapCount` | `integer` | yes | How many names matched nothing. |

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