Skip to main content
POST
https://api.getcatalog.ai
/
v1
/
agentic-search
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"
      }
    }
  }'
{
  "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 discoveryExamples:
  • "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.
meta
object
Search metadata and result information
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"
      }
    }
  }'
{
  "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"
      }
    }
  ]
}