Search by Attributes

When you already know exactly what you’re looking for — red or blue hot-season dresses, say — attribute search filters your catalog by structured facets instead of guessing at relevance. It’s an exact filter, so results carry no z_score. Each match is a garment id and url you can pass 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 attributes

Filters your catalog by exact garment attributes — no relevance ranking. Use it for faceted browsing (“show me red, hot-season dresses”) or to pre-scope a catalog before a try-on. Required headers

Header	Value
`x-api-key`	Your publishable tenant key
`Content-Type`	`application/json`

How filters combine

Within a single attribute, values are OR-ed — color: ["red", "blue"] matches garments that are red or blue.
Across attributes, filters are AND-ed — adding season: ["hot"] keeps only the red-or-blue garments that are also hot-season.

So { "color": ["red", "blue"], "season": ["hot"] } reads as “(red OR blue) AND hot-season.”

You must provide at least one attribute filter, or the request is rejected with 422. An empty body matches nothing by design.

Body parameters Every attribute is an optional array of allowed values. Each accepts a fixed set of values — an unrecognized value is rejected with 422.

string[]

Garment type, e.g. dress, t-shirt, jacket. See all values below.

string[]

Dominant color, e.g. red, black, multicolor.

string[]

Where the garment sits on the body: top-closed, top-open, bottom-long, bottom-short, fullbody.

string[]

male or female.

string[]

Aesthetic, e.g. casual, formal, streetwear.

string[]

Fabric, e.g. cotton, denim, silk.

string[]

hot, cold, or all_season.

string[]

Silhouette, e.g. slim-fitted, oversized-loose.

string[]

Surface pattern, e.g. solid, striped, floral.

string[]

Intended occasion, e.g. casual_everyday, formal_event.

integer

default:"20"

Maximum number of garments to return. Range 1–100.

Allowed values

category

Tops — t-shirt, tank top, blouse, shirt, sweater, knitwear, corset, blazer, hoodie, sweatshirt, crop top, bodysuitBottoms — trouser, jean, short, skirt, legging, tightOne-pieces — dress, jumpsuit, romper, overall, dungaree, suit, setOuterwear — coat, jacket, vest, gilet, cape, ponchoIntimates & swimwear — swimwear, lingerie, loungewear, sleepwear

color

black, white, grey, red, blue, green, yellow, pink, purple, brown, beige, multicolor

placement

top-closed, top-open, bottom-long, bottom-short, fullbody

gender

male, female

style

streetwear, casual, formal, boho, minimalist, vintage, sporty, preppy

material

cotton, denim, leather, silk, wool, linen, synthetic, knit, suede

season

hot, cold, all_season

fit

oversized-loose, regular-standard, slim-fitted, cropped, maxi/long

pattern

solid, striped, plaid/checkered, floral, animal-print, graphic, tie-dye, abstract

occasion

casual_everyday, work_business, party_night_out, formal_event, beach_vacation, active_sport, lounge_home, festival_concert

curl -X POST "$BASE_URL/search/attribute-search" \
  -H "x-api-key: $SOULDI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "category": ["dress"],
    "color": ["red", "blue"],
    "season": ["hot"],
    "limit": 10
  }'

const res = await fetch(`${BASE_URL}/search/attribute-search`, {
  method: "POST",
  headers: {
    "x-api-key": SOULDI_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    category: ["dress"],
    color: ["red", "blue"],
    season: ["hot"],
    limit: 10,
  }),
});

const { garments } = await res.json();

import requests

res = requests.post(
    f"{BASE_URL}/search/attribute-search",
    headers={"x-api-key": SOULDI_API_KEY},
    json={
        "category": ["dress"],
        "color": ["red", "blue"],
        "season": ["hot"],
        "limit": 10,
    },
)
garments = res.json()["garments"]

{
  "garments": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "url": "https://shop.example.com/garments/red-linen-dress.jpg",
      "z_score": null
    }
  ]
}

Response fields

object[]

The garments matching every filter. May be empty if nothing matches.

string

The garment’s unique ID.

string

The garment image URL — ready to pass into POST /try-on/generate.

null

Always null for attribute search — it’s an exact filter, not a ranked search.

For the shared status codes and the empty-result case, see Errors.

Next steps

Search by text

Use a natural-language query when you don’t have exact facets in mind.

Search by image

Match against a reference image instead of structured filters.

Try a garment on

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

Get Started

Try-On

Catalog Search

Sizes

Search by Attributes