Agentic Search

Intelligent product search powered by AI agents

Perform advanced product searches that reason through natural language queries and customer preferences.

Request

x-api-key · string · required

Your API key for authentication

Request Body

query · string · required

Natural language search query for product discovery

Examples:

• "performance activewear for HIIT workouts in humid climates"
• "versatile capsule wardrobe pieces for European business travel"
• "statement jewelry that complements a maximalist aesthetic"

customer_profile · object

Optional customer profile information to personalize search results. This field accepts any JSON structure, allowing you to provide custom customer attributes and preferences.

Response

products · array

Array of products matching the search query with comprehensive product information

Show Product Properties

id · string

Unique product identifier

title · string

Product title

description · string

Product description

description_html · string

Product description with HTML formatting

url · string

Product URL

brand · string

Product brand name

vendor · string

Product vendor/retailer

handle · string

URL-friendly product identifier

tags · array

Product category tags

product_type · string

Main product category

price_amount · number

Base price amount in decimal format

price_currency · string

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

min_price · number

Minimum price across all variants

max_price · number

Maximum price across all variants

is_available · boolean

Product availability status

platform_id · string

Platform-specific product ID

store_domain · string

Domain of the retailer

store_canonical_url · string

Canonical URL of the store

google_product_category_id · string

Google product category identifier

google_product_category_path · string

Full Google product category path

updated_at · string

Last update timestamp

images · array

Product images with metadata including URL, dimensions, alt text, and variant associations

variants · array

Product variants with pricing, availability, and sizing information

options · array

Available product options (size, color, etc.)

attributes · object

Rich product attributes including style, mood, color, material, season, occasion, and care instructions

video_url · string

Product video URL (if available)

meta · object

Search metadata and result information

Show Meta Properties

totalItems · number

Total number of products found

urls · array

Array of all product URLs in the result set

cURL

curl -X POST https://api.getcatalog.ai/v1/agentic-search \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "query": "A Barbour jacket suitable for the office",
    "customer_profile": {
      "style": {
        "fit": "casual with a refined, creative edge",
        "avoid": [
          "large logos",
          "loud streetwear",
          "technical performancewear"
        ],
        "color": "prefers earth tones, neutrals, black",
        "aesthetic": [
          "minimal and cool"
        ],
        "silhouette": [
          "relaxed",
          "cropped",
          "unstructured"
        ]
      },
      "preferences": {
        "in_stock_only": true,
        "comfort_priority": true
      },
      "usage_context": {
        "activities": [
          "office",
          "coffee runs",
          "after-work events"
        ],
        "environment": "urban, mild climate",
        "travel_friendly": true,
        "durability_priority": true
      },
      "purchase_behavior": {
        "value": "distinctive, expressive pieces",
        "buying_frequency": "occasional, style-driven"
      }
    }
  }'

Success Response

{
  "meta": {
    "urls": [
      "https://www.barbour.com/us/safari-relaxed-long-sleeved-shirt-LSH1357MI5214.html",
      "https://www.barbour.com/us/otterburn-gilet-LGI0003BE71.html",
      "https://www.barbour.com/us/elsie-wide-leg-trousers-LTR0385NY99.html",
      "https://www.barbour.com/us/abbey-casual-jacket-LCA0362WH1114.html"
    ],
    "totalItems": 4
  },
  "products": [
    {
      "id": "c9d57a2c-2017-4b67-94f0-65744d029e84",
      "url": "https://www.barbour.com/us/safari-relaxed-long-sleeved-shirt-LSH1357MI5214.html",
      "tags": ["SHIRTS"],
      "brand": "Barbour",
      "title": "Safari Relaxed Long-Sleeved Shirt",
      "handle": "safari-relaxed-long-sleeved-shirt-lsh1357mi5214",
      "vendor": "barbour",
      "platform_id": "LSH1357MI5214",
      "is_available": true,
      "price_amount": 115,
      "product_type": "SHIRTS",
      "store_domain": "www.barbour.com",
      "price_currency": "USD",
      "min_price": 115,
      "max_price": 115,
      "description": "Meet the Safari shirt with its 100% cotton construction and relaxed fit. This cotton-blend garment is imagined in an all-over pattern, offering a feminine option for weekend looks.",
      "description_html": "Meet the Safari shirt with its 100% cotton construction and relaxed fit. This cotton-blend garment is imagined in an all-over pattern, offering a feminine option for weekend looks. <p class=\"pt-3\">SKU: LSH1357MI5214</p>",
      "store_canonical_url": "https://www.barbour.com/",
      "google_product_category_id": "212",
      "google_product_category_path": "Apparel & Accessories > Clothing > Shirts & Tops",
      "updated_at": "2025-08-05T12:27:51.896Z",
      "video_url": null,
      "images": [
        {
          "id": "img-1754396866999-0",
          "url": "https://images.salsify.com/image/upload/s--qi5RyAOF--/a37a100905bd45f9069b666bf211c4b066532e33.jpg",
          "width": 1500,
          "height": 1836,
          "altText": "Safari Relaxed Long-Sleeved Shirt product image (primary)",
          "position": 1
        }
      ],
      "variants": [
        {
          "id": "variant-1754396867009-0",
          "SKU": "LSH1357MI5214",
          "price": "115",
          "title": "Safari Relaxed Long-Sleeved Shirt - Us 4",
          "option1": "US 4",
          "isAvailable": true,
          "compareAtPrice": "115"
        }
      ],
      "options": [
        {
          "name": "Size",
          "values": ["US 4", "US 6", "US 8", "US 10", "US 12", "US 14"],
          "position": 1
        }
      ],
      "attributes": {
        "mood": ["playful", "cheerful", "relaxed"],
        "color": {
          "iscc_shade": "null",
          "iscc_family": "white",
          "merchant_label": "all-over pattern"
        },
        "style": ["casual", "relaxed-fit", "futuristic"],
        "gender": "female",
        "season": ["spring", "summer", "fall", "year-round"],
        "pattern": "allover",
        "summary": "Feminine relaxed long-sleeved shirt made from 100% cotton.",
        "features": "Comfortable and stylish for weekend looks.",
        "material": {
          "primary": "cotton",
          "merchant_label": "100% cotton"
        },
        "occasion": ["everyday", "casual", "weekend"],
        "care_instructions": "Machine wash cold"
      }
    }
  ]
}

Examples

Basic Search

Simple product search with natural language:

cURL

curl -X POST https://api.getcatalog.ai/v1/agentic-search \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"query": "sustainable minimalist sneakers for everyday wear"}'

Personalized Search

Search with customer profile for personalized results:

cURL

curl -X POST https://api.getcatalog.ai/v1/agentic-search \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "query": "sophisticated athleisure for urban commuting",
    "customer_profile": {
      "style": {
        "fit": "tailored yet comfortable",
        "color": "neutral tones with subtle accents",
        "aesthetic": ["modern professional", "athletic chic"],
        "silhouette": ["streamlined", "functional"]
      },
      "preferences": {
        "in_stock_only": true,
        "comfort_priority": true
      },
      "usage_context": {
        "activities": ["commuting", "work", "gym", "casual meetings"],
        "environment": "urban, variable weather",
        "travel_friendly": true,
        "durability_priority": true
      },
      "purchase_behavior": {
        "value": "versatile pieces that work across contexts",
        "buying_frequency": "considered purchases, quality over quantity"
      }
    }
  }'