> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getcatalog.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Agentic Search
> Sync AI-powered search with customer profile personalization. Returns up to 8 products with comprehensive product information.
**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`](/v1/api-reference/endpoints/search/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
Your API key for authentication
### Request Body
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"`
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:**
```json theme={null}
{
"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
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.
Unique product identifier
Product title
Product description
Product description with HTML formatting
Product URL
Product brand name
Product vendor/retailer
URL-friendly product identifier
Product category tags
Main product category
Base price amount in decimal format
Currency code (e.g., "USD", "EUR")
Minimum price across all variants
Maximum price across all variants
Product availability status
Platform-specific product ID
Domain of the retailer
Canonical URL of the store
Google product category identifier
Full Google product category path
Last update timestamp (ISO 8601 format)
Product images with metadata including URL, dimensions, alt text, and variant associations
Unique image identifier
Image URL
Image width in pixels
Image height in pixels
Alt text for the image
Display position/order of the image
Array of variant IDs that use this image
Product variants with pricing, availability, and sizing information
Unique variant identifier
Stock Keeping Unit identifier
Variant price as string
Full variant title including options
First option value (e.g., size)
Variant availability status
Compare at price (original/MSRP price)
Available product options (size, color, etc.)
Option name (e.g., "Size", "Color")
Array of available values for this option
Display position of the option
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.
Color information with merchant label and ISCC classification (when available)
Material information with primary material and merchant label (when available)
Style descriptors (e.g., \["casual", "relaxed-fit"])
Mood descriptors (e.g., \["playful", "cheerful"])
Suitable seasons (e.g., \["spring", "summer", "fall"])
Suitable occasions (e.g., \["everyday", "casual", "weekend"])
Gender classification (when available)
Key product features
Care and washing instructions (when available)
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.
Product video URL (if available)
Search metadata and result information
Total number of products returned (may be less than 8 if some products couldn't be processed)
Array of all product URLs in the result set
```powershell cURL theme={null}
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"
}
}
}'
```
```javascript JavaScript theme={null}
const response = await fetch('https://api.getcatalog.ai/v1/agentic-search', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-api-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
query: 'A popular Barbour jacket to wear to the office',
customer_profile: {
style: {
fit: 'elevated casual with artistic flair',
avoid: [
'flashy logos',
'overt streetwear',
'overly techy sportswear'
],
color: 'prefers earth tones, neutrals, and black',
aesthetic: [
'understated cool'
],
silhouette: [
'loose',
'cropped',
'unstructured'
]
},
preferences: {
in_stock_only: true,
comfort_priority: true
},
usage_context: {
activities: [
'office',
'coffee runs',
'after work events'
],
environment: 'urban, temperate climate',
travel_friendly: true,
durability_priority: true
},
purchase_behavior: {
value: 'unique and expressive pieces',
buying_frequency: 'occasional, style-driven purchases'
}
}
})
});
const data = await response.json();
```
```python Python theme={null}
import requests
response = requests.post(
'https://api.getcatalog.ai/v1/agentic-search',
headers={
'Content-Type': 'application/json',
'x-api-key': 'YOUR_API_KEY'
},
json={
'query': 'A popular Barbour jacket to wear to the office',
'customer_profile': {
'style': {
'fit': 'elevated casual with artistic flair',
'avoid': [
'flashy logos',
'overt streetwear',
'overly techy sportswear'
],
'color': 'prefers earth tones, neutrals, and black',
'aesthetic': [
'understated cool'
],
'silhouette': [
'loose',
'cropped',
'unstructured'
]
},
'preferences': {
'in_stock_only': True,
'comfort_priority': True
},
'usage_context': {
'activities': [
'office',
'coffee runs',
'after work events'
],
'environment': 'urban, temperate climate',
'travel_friendly': True,
'durability_priority': True
},
'purchase_behavior': {
'value': 'unique and expressive pieces',
'buying_frequency': 'occasional, style-driven purchases'
}
}
}
)
data = response.json()
```
```json Success Response theme={null}
{
"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. SKU: LSH1357MI5214
",
"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"
}
}
]
}
```