Skip to main content
Type a query the way a shopper would — red summer dress, oversized denim jacket — and get back the garments in your catalog that match it best, ranked by relevance. Each result is a garment id and url you can pass straight into Generation.
This endpoint needs only your tenant key — send x-api-key and nothing else, with no Authorization: Bearer token. BASE_URL is the Souldi API base URL, https://api.souldi.io. See the authentication model.

Search by text

Runs a natural-language search across your catalog and returns the most relevant garments, ranked by z_score. Required headers Query parameter
string
required
The free-text search query, passed in the URL query string (not the JSON body). For example ?query=red%20summer%20dress.
Body parameters
integer
default:"3"
Maximum number of garments to return. Range 110.
number
default:"1.0"
Relevance floor in standard deviations above the query’s mean. Higher = stricter. Range -5.05.0. See How relevance works.
integer
default:"50"
Size of the candidate pool that defines the z_score baseline. Range 1200.
string[] | null
default:"null"
Optional allowlist of garment IDs to restrict the search to a specific subset of your catalog. Omit it (or pass null) to search your whole catalog.
Response fields
object[]
The matching garments, ordered most-relevant first. May be empty if nothing clears min_z_score.
string
The garment’s unique ID. Use it to reference the garment elsewhere.
string
The garment image URL — pass this into POST /try-on/generate to try it on.
number
The relevance score for this query. See How relevance works.
Tune the result set with min_z_score, pool_size, and top_n — see How relevance works. For the shared status codes and the empty-result case, see Errors.

Next steps

Search by attributes

Switch to exact faceted filters when you know the category, color, or season.

Search by image

Match against a reference image instead of a text query.

Try a garment on

Pass a result url to POST /try-on/generate to render it on your user.