# Search the icon catalog

> `POST` `/v1/authoring-catalogs/icons/query`

URL: https://www.agencytitan.com/docs/tag/authoring-catalogs/POST/v1/authoring-catalogs/icons/query

Operation ID: `authoring_catalogs_icons`

Tag: [authoring_catalogs](https://www.agencytitan.com/docs/tag/authoring-catalogs.md)

## Description

Search or browse icons by keywords across all icon libraries (Hero Icons, Font Awesome, Material Design, Lucide, Feather, Simple Icons).

Use Simple Icons (`simple-icons:*`) for brand and platform logos (e.g. Google, Facebook, Slack, Stripe, Salesforce, HubSpot). Use the other collections for generic UI icons.

Returns matching icons with full format ready to pick and use.

Single search:
- keywords: ["rocket", "launch"] -> finds rocket icons
- keywords: ["lawn", "mower"] -> finds lawn care icons (MDI has great ones)

Batch search (RECOMMENDED when picking icons for multiple stages/items at once):
- searches: [{ label: "Intake", keywords: ["inbox", "intake"] }, { label: "Resolution", keywords: ["wrench", "fix"] }, { label: "Communication", keywords: ["chat", "email"] }]
- Each entry returns its own matches array, keyed by label so you can map results back to the item being iconified.

Use keywords that describe what the icon looks like or represents.

## Parameters

_None_

## Request body

- Required: yes
- Content-Type: `application/json`
  - Type: `object`
  - Properties:
    - `collection` (`string`) — Optional: filter to a specific collection (single-search path). Use "simple-icons" for brand/platform logos.
    - `keywords` (`array<string>`) — Single-search keywords (legacy; prefer searches for batched calls).
    - `limit` (`number`) — Maximum results to return for the single-search path (default: 15, max: 50).
    - `list_all` (`boolean`) — If true, returns icons from all collections. Use sparingly - there are 700+ icons.
    - `searches` (`array<object>`) — Batch multiple icon searches in one call. Each entry runs an independent search and returns its own matches. Recommende…

## Responses

- `200` (`application/json`): Successful response.
  - Type: `object`
  - Properties:
    - `data` (`object`, required)
- `400` (`application/json`): Request validation failed (unknown or out-of-range parameters/properties are rejected).
  - Type: `object`
  - Properties:
    - `error` (`object`, required)
- `401` (`application/json`): Missing, invalid, expired, or revoked bearer token.
  - Type: `object`
  - Properties:
    - `error` (`string`, required)
    - `error_description` (`string`, required)
- `403` (`application/json`): The authenticated user does not have permission for this operation.
  - Type: `object`
  - Properties:
    - `error` (`object`, required)
- `404` (`application/json`): The requested resource was not found.
  - Type: `object`
  - Properties:
    - `error` (`object`, required)
- `409` (`application/json`): The request conflicts with an existing record or partially applied.
  - Type: `object`
  - Properties:
    - `error` (`object`, required)
- `429` (`application/json`): Per-tenant rate limit exceeded (600 requests/minute across all /v1 REST endpoints). The Retry-After header indicates how many seconds to wait.
  - Type: `object`
  - Properties:
    - `error` (`object`, required)
- `500` (`application/json`): An unexpected internal error occurred.
  - Type: `object`
  - Properties:
    - `error` (`object`, required)

## Authentication

- `bearerAuth` — http (bearer) — All /v1 endpoints (except `/v1/openapi.json` and `/v1/llms.txt`) require a bearer token. Two equal first-class paths: (1) an OAuth 2.0 access token from the au…

## Useful links

- Interactive page: https://www.agencytitan.com/docs/tag/authoring-catalogs/POST/v1/authoring-catalogs/icons/query
- API reference home: https://www.agencytitan.com/docs/
- Tag page: https://www.agencytitan.com/docs/tag/authoring-catalogs.md
- This operation as Markdown: https://www.agencytitan.com/docs/tag/authoring-catalogs/POST/v1/authoring-catalogs/icons/query.md
- OpenAPI JSON: https://www.agencytitan.com/docs/openapi.json
- Full API Markdown: https://api.agencytitan.com/v1/llms.txt
- API keys: https://app.agencytitan.com/settings/api-mcp