Icons
Map icons
Choose icons for many names at once.
POST
/v1/icons/mapTL;DR
| Question | Answer |
|---|---|
| What does it do? | Choose icons for many names at once. |
| Which tool does the same? | map_icons |
| What does it take? | A JSON body of type MapIconsInput. |
| What does it return? | Status 200 with a body of type 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.
| 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 |
| 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 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 | Every endpoint, and the error envelope |
| Schemas | Every request and response type |
map_icons | The same operation as an MCP tool |
| Tool reference | The operations as callable tools |