Brand search

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 takes a natural-language query such as "dark brutalist developer tools" or "warm pastel skincare landing pages".
By similarity: GET /search/similar 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.

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).
`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 for a result, submit its url to POST /design/submissions.

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.

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.

Search history

GET /search/submissions 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.

From your agent

The same two searches are exposed as MCP tools: 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 packages that flow as installable instructions.

Next steps

Find inspiration

The search, pick, extract workflow end to end.

Search brands

The endpoint reference, with an interactive playground.

MCP server

Give your coding agent the same search tools.

Getting Started

Use cases

Brand extractor

Brand adherence verifier

Integrate Agents

Reference

Brand search

Two ways to search

Result cards

Depth

Filters

The corpus

Search history

From your agent

Next steps

Find inspiration

Search brands

MCP server

​Two ways to search

​Result cards

​Depth

​Filters

​The corpus

​Search history

​From your agent

​Next steps

Find inspiration

Search brands

MCP server

Two ways to search

Result cards

Depth

Filters

The corpus

Search history

From your agent

Next steps