Agentic Search

Sync AI-powered search with customer profile personalization. Returns up to 8 products with comprehensive product information.

POST /v1/agentic-search

cURL

PowerShell

curl -X POST https://api.getcatalog.ai/v1/agentic-search \
  -H "Content-Type: application/json" \
  -H "x-api-key: $CATALOG_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"
      }
    }
  ]
}

When to use: Best for personalized shopping experiences where you have customer profile data and need comprehensive product information. For faster searches with up to 10 results, use POST /v1/agentic-search-mini.

Performance: This endpoint provides comprehensive AI-powered analysis and typically takes longer to respond. Use Agentic Search Mini if you need quicker response times.

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.

Common Structure:

{
  "style": {
    "fit": "string",
    "color": "string",
    "aesthetic": ["string"],
    "silhouette": ["string"],
    "avoid": ["string"]
  },
  "preferences": {
    "in_stock_only": boolean,
    "comfort_priority": boolean
  },
  "usage_context": {
    "activities": ["string"],
    "environment": "string",
    "travel_friendly": boolean,
    "durability_priority": boolean
  },
  "purchase_behavior": {
    "value": "string",
    "buying_frequency": "string"
  }
}

Response

products · array

Array of products matching the search query with comprehensive product information (up to 8 products). Fewer products may be returned if some cannot be processed or don’t meet quality requirements.

Hide 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 (ISO 8601 format)

images · array

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

Show Image Properties

id · string

Unique image identifier

url · string

Image URL

width · number

Image width in pixels

height · number

Image height in pixels

altText · string

Alt text for the image

position · number

Display position/order of the image

variantIDs · array

Array of variant IDs that use this image

variants · array

Product variants with pricing, availability, and sizing information

Show Variant Properties

id · string

Unique variant identifier

SKU · string

Stock Keeping Unit identifier

price · string

Variant price as string

title · string

Full variant title including options

option1 · string

First option value (e.g., size)

isAvailable · boolean

Variant availability status

compareAtPrice · string

Compare at price (original/MSRP price)

options · array

Available product options (size, color, etc.)

Show Option Properties

name · string

Option name (e.g., “Size”, “Color”)

values · array

Array of available values for this option

position · number

Display position of the option

attributes · object

Rich product attributes including style, mood, color, material, season, occasion, and care instructions. Attributes are dynamically extracted and vary by product based on available information.

Show Common Attributes

color · object

Color information with merchant label and ISCC classification (when available)

material · object

Material information with primary material and merchant label (when available)

style · array

Style descriptors (e.g., [“casual”, “relaxed-fit”])

mood · array

Mood descriptors (e.g., [“playful”, “cheerful”])

season · array

Suitable seasons (e.g., [“spring”, “summer”, “fall”])

occasion · array

Suitable occasions (e.g., [“everyday”, “casual”, “weekend”])

gender · string

Gender classification (when available)

features · string

Key product features

care_instructions · string

Care and washing instructions (when available)

summary · string

Product summary

Dynamic Attributes: The attributes object contains dynamic keys and values that vary by product. The exact structure depends on the product and available data sources.

video_url · string | null

Product video URL (if available)

meta · object

Search metadata and result information

Show Meta Properties

totalItems · number

Total number of products returned (may be less than 8 if some products couldn’t be processed)

urls · array

Array of all product URLs in the result set

cURL

PowerShell

curl -X POST https://api.getcatalog.ai/v1/agentic-search \
  -H "Content-Type: application/json" \
  -H "x-api-key: $CATALOG_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"
      }
    }
  ]
}