Skip to main content
Before a shopper can try a garment on, you need a way to surface the right garments from your catalog. Search gives you three ways to do that: a natural free-text query, a structured attribute filter, or a reference image to match against. Every result comes back as a garment id and url you can drop into Generation.

By text

Natural-language queries like red summer dress. Ranked by relevance.

By attributes

Exact filters — category, color, season, and more. Combine to narrow down.

By image

Pass a garment image URL to find visually similar items in your catalog.

​
Before you start

Search needs only your tenant key — send x-api-key and nothing else. Unlike Generation and User & Image, there’s no Authorization: Bearer token: search runs against your catalog, not a specific end-user. See the authentication model.

​
How relevance works

Text and image search return a z_score on every garment — a relative relevance metric, not an absolute one. It measures how far a garment stands out above the average match for this specific query, in standard deviations.
  • A z_score of 2.0 means the garment is two standard deviations more relevant than the typical candidate for your query — a strong, standout match.
  • A z_score near 0 means it’s only about as relevant as average — a weak match.
Because the score is normalized per query, you can’t compare raw scores across different queries, and you shouldn’t hard-code a “good score” threshold. Instead, tune results with three knobs on the request body:
Raise min_z_score for precision (fewer, tighter matches); lower it for recall (more, looser matches). The defaults (min_z_score: 1.0, pool_size: 50, top_n: 3) are a sensible starting point for surfacing a small set of try-on candidates.
Attribute search is an exact filter, not a relevance ranking — its results have no z_score (the field is null).

​
Pick a search mode

Search by text

POST /search/text-search — natural-language query, ranked by z_score.

Search by attributes

POST /search/attribute-search — exact faceted filters across ten attributes.

Search by image

POST /search/image-search — visual similarity to a reference image URL.

​
Errors

These status codes apply to all three search endpoints.
A successful search can legitimately return an empty garments array — for text and image search when nothing clears min_z_score, and for attribute search when no garment matches every filter. Handle the empty case in your UI.

​
Next steps

Try a garment on

Take a garment url from any search result and pass it to POST /try-on/generate to render it on your user.

Review the full flow

See how authentication, search, and generation fit together end to end.