Search Products

Search products using natural language queries with advanced filtering

Search for products using intelligent semantic search with natural language understanding. The API supports complex filtering, pagination, and returns structured product data optimized for AI applications.

Request

x-api-key · string · required

Your API key for authentication

Body

query · string

Natural language search query for semantic product discovery

Examples:

• "silk dress for summer wedding"
• "organic cotton t-shirt"
• "minimalist black handbag"

filters · object

Filter criteria to narrow down results

Show Filter Properties

min_price · number

Minimum price in dollars (e.g. $25.00)

max_price · number

Maximum price in dollars (e.g. $150.00)

vendor · string

Vendor name(s) - can be single string or array of strings

brand · string

Brand name(s) - can be single string or array of strings

is_available · boolean

Filter by availability status

price_currency · string

Currency code(s) (e.g., “USD”, “EUR”)

product_type · string

Product type(s) for categorization

store_domain · string

Store domain(s) to filter by

collection_handle · string

Collection handle(s) for grouped products

handle · string

Product handle(s) - URL-friendly identifiers

tags · string

Product tag(s) for classification

variants_color · string

Variant color(s) - can be single string or array of strings

variants_size · string

Variant size(s) - can be single string or array of strings

variants_title · string

Variant title(s) - can be single string or array of strings

variants_in_stock · boolean

Filter by variant stock availability

attributes · object

Product attribute filters - supports any attribute key-value pairs

Attribute filters depend on the specific attributes available in the product data. Not all products may have all attributes, and filter effectiveness varies based on data consistency.

Show Common Attribute Filters

attributes.color · string

Primary color filter

attributes.color_alt · string

Alternative color classification

attributes.material · string

Material type (e.g., “silk”, “cotton”, “leather”)

attributes.material_alt · string

Alternative material classification

attributes.category · string

Product category (e.g., “Women > Dresses”)

attributes.style · string

Style classification

attributes.style_alt · string

Alternative style classification

attributes.features · string

Product features

attributes.summary · string

Product summary attributes

attributes.aesthetic · string

Aesthetic style (e.g., “minimalist”, “bohemian”)

attributes.gender · string

Target gender (“women”, “men”, “unisex”)

attributes.mood · string

Style mood classification

attributes.trend · string

Fashion trend association

attributes.age_group · string

Target age group

attributes.occasion · string

Suitable occasion (“everyday”, “formal”, “party”, “work”)

attributes.care_instructions · string

Care and maintenance instructions

attributes.fit · string

Fit type (e.g., “slim”, “regular”, “oversized”)

attributes.leg_style · string

Leg style for bottoms

attributes.rise · string

Rise type for bottoms (e.g., “high”, “mid”, “low”)

attributes.season · string

Seasonal appropriateness (“spring”, “summer”, “fall”, “winter”)

attributes.pattern · string

Pattern type (e.g., “solid”, “striped”, “floral”)

attributes.length · string

Length classification

attributes.silhouette · string

Silhouette type

attributes.waist · string

Waist style

attributes.waist_type · string

Waist type classification

attributes.neckline · string

Neckline style for tops

attributes.lens_color · string

Lens color for eyewear

attributes.sleeve_type · string

Sleeve type for tops

attributes.size · string

Size classification

attributes.filling · string

Filling material (e.g., for outerwear)

attributes.closure_type · string

Closure type (e.g., “zipper”, “button”, “velcro”)

page · number · default: "1"

Page number for pagination (1-indexed)

limit · number · default: "10"

Number of items per page (currently fixed at 10)

Response

products · array

Array of matching products

Show Product Object

id · string

Unique product identifier

title · string

Product title

description · string

Product description

description_html · string

HTML-formatted product description

vendor · string

Vendor/brand name

brand · string | null

Brand name (alternative field)

url · string

Product URL

price_amount · number | null

Price in dollars (e.g. $29.99)

price_currency · string | null

Currency code (e.g., “USD”)

min_price · number | null

Minimum price across variants

max_price · number | null

Maximum price across variants

is_available · boolean

Product availability status

product_type · string | null

Product type classification

store_domain · string | null

Store domain where product is sold

store_canonical_url · string | null

Canonical store URL

collection_handle · string | null

Collection handle for grouped products

handle · string | null

Product handle (URL-friendly identifier)

tags · array

Array of product tags

images · object | null

Product images object

variants · object | null

Product variants object with size, color, pricing information

options · object | null

Product options object

attributes · object

Rich product attributes object containing all attribute key-value pairs

created_at · string

Product creation timestamp (ISO 8601)

updated_at · string

Product last update timestamp (ISO 8601)

published_at · string | null

Product publication timestamp (ISO 8601)

meta · object

Pagination and result metadata

Show Meta Properties

totalItems · number

Total number of matching products (capped at 50 for pagination UI)

totalPages · number

Total number of pages available

currentPage · number

Current page number

pageSize · number

Number of items per page (currently fixed at 10)

cURL

curl -X POST https://api.getcatalog.ai/api/search \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "query": "summer dress",
    "filters": {
      "max_price": 150.00,
      "is_available": true,
      "brand": ["fwrd", "amiri"],
      "attributes": {
        "color": ["blue", "white"],
        "season": "summer",
        "gender": "women"
      }
    },
    "page": 1
  }'

Response

{
  "products": [
    {
      "id": "12345",
      "title": "Blue Linen Summer Dress",
      "description": "Lightweight linen dress perfect for warm weather",
      "description_html": "<p>Lightweight linen dress perfect for warm weather</p>",
      "vendor": "Summer Collections",
      "brand": "amiri",
      "url": "https://store.example.com/dress-12345",
      "price_amount": 89.99,
      "price_currency": "USD",
      "min_price": 89.99,
      "max_price": 89.99,
      "is_available": true,
      "product_type": "Dress",
      "store_domain": "store.example.com",
      "store_canonical_url": "https://store.example.com",
      "collection_handle": "summer-collection",
      "handle": "blue-linen-summer-dress",
      "tags": ["summer", "linen", "dress", "blue"],
      "images": {
        "primary": "https://example.com/dress.jpg",
        "gallery": ["https://example.com/dress-1.jpg", "https://example.com/dress-2.jpg"]
      },
      "variants": {
        "color": ["blue"],
        "size": ["XS", "S", "M", "L"],
        "price_range": { "min": 89.99, "max": 89.99 }
      },
      "options": {
        "size": ["XS", "S", "M", "L"],
        "color": ["blue"]
      },
      "attributes": {
        "color": "blue",
        "material": "linen",
        "category": "Women > Dresses",
        "gender": "women",
        "season": "summer",
        "occasion": "casual",
        "fit": "regular",
        "length": "midi",
        "sleeve_type": "short"
      },
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-20T14:45:00Z",
      "published_at": "2024-01-15T12:00:00Z"
    }
  ],
  "meta": {
    "totalItems": 24,
    "totalPages": 3,
    "currentPage": 1,
    "pageSize": 10
  }
}

Examples

Basic Search

Search for products with a simple query:

cURL

curl -X POST https://api.getcatalog.ai/api/search \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"query": "black shoes"}'

Price Range Filter

Filter products by price range:

cURL

curl -X POST https://api.getcatalog.ai/api/search \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "query": "handbag",
    "filters": {
      "min_price": 50.00,
      "max_price": 250.00
    }
  }'

Brand Filter

Search for products from specific brands:

cURL

curl -X POST https://api.getcatalog.ai/api/search \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "query": "denim jacket",
    "filters": {
      "brand": ["Levi"],
      "is_available": true
    }
  }'