> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tastelabs.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Brand search
> Find brands in the corpus by aesthetic or by visual similarity
Extraction answers "what does this URL look like?". **Brand search** answers the other direction: "which brands look like this?". You describe an aesthetic in plain language, or point at one of your own extractions, and the engine returns ranked brands from its curated corpus.
Unlike extraction, search is **synchronous**. There is no submission to poll: the call returns the results.
## Two ways to search
* **By description**: [`POST /search`](/api-reference/endpoint/search-brands) takes a natural-language `query` such as `"dark brutalist developer tools"` or `"warm pastel skincare landing pages"`.
* **By similarity**: [`GET /search/similar`](/api-reference/endpoint/find-similar-brands) takes the `submission_id` of one of your completed extractions and returns its nearest visual neighbours.
Both return the same result cards, so you can render them with one code path.
```bash theme={null}
curl -X POST https://api.tastelabs.com/search \
-H "X-API-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{"query": "dark brutalist developer tools", "depth": "fast", "top_k": 6}'
```
## Result cards
Each result is a card describing one brand:
| Field | Holds |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `url` | The brand's page in the corpus. |
| `brand_name` | The brand name, when one was identified. |
| `identity_paragraph` | A short description of the brand's visual identity. |
| `match` | Confidence tier of the match: `strong`, `good`, or `related`. |
| `reason` | One sentence on why the brand matched the query. |
| `badge` | `discovery` marks a rotating exemplar of the detected style (see [The corpus](#the-corpus)). |
| `tags` | Descriptive tags, such as industry and page type. |
| `palette` | Palette classification: `luminance`, `temperature`, `saturation`, `themes`, `aesthetic_codes`, `effects`, plus `primary` and `secondary` hex lists. |
| `typography` | Typography classification: `family_strategy`, `hierarchy`, and `character`. |
| `screenshot_url` | A full-page screenshot. Fetch it to see the brand. |
Alongside the cards, `POST /search` returns `query_tags`: the engine's soft reading of your query (detected `industry`, `page_type`, `hue`, `aesthetic`, and `style`). It is display metadata, never a constraint on the results.
Results come from the curated corpus, not from your own submissions. A card is a pointer, not an extraction. To get the full [design system](/concepts/design-system) for a result, submit its `url` to [`POST /design/submissions`](/api-reference/endpoint/create-submission).
## Depth
`POST /search` takes a `depth`:
* **`fast`** (default): returns in seconds.
* **`deep`**: when result quality matters more than latency. Can take up to about 3 minutes.
Each search consumes credits, and `deep` consumes more than `fast`. The charge is refunded automatically if the search fails.
## Filters
When a constraint is non-negotiable, move it out of the query and into the optional `filters` object. `POST /search` accepts four filter fields: `page_type`, `industry`, `hue`, and `layout`.
```bash theme={null}
curl -X POST https://api.tastelabs.com/search \
-H "X-API-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{"query": "warm editorial look", "filters": {"industry": "beauty", "hue": "pink"}}'
```
Filters are **hard constraints**, not a ranking hint: every returned card satisfies them, and the list is never padded with out-of-filter lookalikes. Values are matched verbatim against the corpus vocabulary, so an unknown value returns no matches rather than an error.
Each filter draws from a closed vocabulary:
| Filter | Values |
| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `page_type` | `homepage`, `about`, `pricing`, `careers`, `case_study`, `features`, `customer_stories`, `portfolio`, `product`, `collections`, `solutions`, `blog`, `landing_page`, `team`, `services` |
| `industry` | `saas`, `ai`, `design`, `creative_agency`, `fintech`, `branding`, `developer_tools`, `fashion`, `venture_capital`, `entertainment`, `beverage`, `food`, `cybersecurity`, `e_commerce`, `architecture`, `cloud_infrastructure`, `ai_infrastructure`, `healthcare`, `edtech`, `web_development`, `productivity`, `beauty`, `photography`, `hr_tech`, `media`, `hospitality`, `gaming`, `financial_services`, `wellness`, `investment`, `real_estate`, `proptech`, `web3`, `restaurant`, `insurtech`, `insurance`, `nonprofit` |
| `hue` | `red`, `orange`, `yellow`, `green`, `teal`, `blue`, `purple`, `pink`, `brown`. Matched against the dominant hues of each brand's palette. |
| `layout` | `grid_based_strict`, `asymmetric_broken_grid`, `generous_whitespace`, `dense_packed`, `centered_symmetric`, `left_aligned_flush`, `card_based`, `overlapping_layered` |
Do not confuse `filters` with the response's `query_tags`: filters narrow retrieval, query tags only describe how the engine read your query.
## The corpus
The **Search** does not read your submissions. It searches a prebuilt corpus of curated brands, prepared ahead of time, which is what makes a search synchronous and fast.
A few result slots rotate: the tail of the list brings in fresh exemplars of the style detected in your query, marked `badge: "discovery"`, so running the same search twice does not return an identical set. Setting any filter disables the rotation, because a rotated-in exemplar could violate the filter.
`GET /search/similar` compares one of your completed extractions against the corpus and returns its nearest neighbours. The comparison runs fresh on every call, so neighbours can vary slightly between calls for the same submission. See [How the engine works](/concepts/architecture#the-search).
## Search history
[`GET /search/submissions`](/api-reference/endpoint/list-searches) lists your past searches and similarity lookups, newest first. Listing history is free. Narrow it with:
* **`kind`**: `search` for query searches, `similar` for similarity lookups.
* **`status`**: `completed`, `failed`, or `in_progress`.
* **`depth`**: `fast` or `deep`.
* **`q`**: free text over the query.
* **`api_key_id`**: only searches made with one API key.
Alongside the page, `total` counts everything matching the filter and `total_by_status` breaks the counts down by outcome, both ignoring pagination.
Results are not stored, only the request (including its `filters` and detected `query_tags`) and its outcome (`status`, `result_count`, `latency_ms`, `credits_consumed`, and the credit reference). Run the search again to get the cards back.
Extraction history is separate and lives at [`GET /design/submissions`](/api-reference/endpoint/list-submissions).
## From your agent
The same two searches are exposed as [MCP tools](/ai-tools/mcp): `search_brands(query, depth, top_k)` and `search_similar_brands(submission_id, top_k)`. An agent can search for a look, pick a result, and extract it with `extract_brand(url)` in one flow. The [`brand-search` skill](/ai-tools/skills#find-references-with-brand-search) packages that flow as installable instructions.
## Next steps
The search, pick, extract workflow end to end.
The endpoint reference, with an interactive playground.
Give your coding agent the same search tools.