cURL
curl -X POST https://api.getcatalog.ai/v2/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"
}
}
}'
const response = await fetch('https://api.getcatalog.ai/v2/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();
console.log(`Search started with execution ID: ${data.execution_id}`);
console.log(`Credits used: ${data.meta.credits_used}`);
// Poll for results: GET /v2/agentic-search/{execution_id}
import requests
response = requests.post(
'https://api.getcatalog.ai/v2/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()
execution_id = data['execution_id']
print(f"Search started with execution ID: {execution_id}")
print(f"Credits used: {data['meta']['credits_used']}")
# Poll for results: GET /v2/agentic-search/{execution_id}
{
"execution_id": "agentic-a1b2c3d4-1735123456789",
"status": "pending",
"meta": {
"credits_used": 25
}
}
Search
Agentic Search
Async AI-powered search with customer profile personalization. Returns immediately with an execution_id to check status and retrieve results.
POST
/
v2
/
agentic-search
cURL
curl -X POST https://api.getcatalog.ai/v2/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"
}
}
}'
const response = await fetch('https://api.getcatalog.ai/v2/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();
console.log(`Search started with execution ID: ${data.execution_id}`);
console.log(`Credits used: ${data.meta.credits_used}`);
// Poll for results: GET /v2/agentic-search/{execution_id}
import requests
response = requests.post(
'https://api.getcatalog.ai/v2/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()
execution_id = data['execution_id']
print(f"Search started with execution ID: {execution_id}")
print(f"Credits used: {data['meta']['credits_used']}")
# Poll for results: GET /v2/agentic-search/{execution_id}
{
"execution_id": "agentic-a1b2c3d4-1735123456789",
"status": "pending",
"meta": {
"credits_used": 25
}
}
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 /v2/agentic-search-mini.Async Processing: This endpoint starts processing asynchronously and returns an
execution_id immediately. Use GET /v2/agentic-search/{execution_id} to check progress and retrieve results when processing completes.View All Executions: You can view all your agentic search executions using GET /v2/agentic-search to see all search jobs, their statuses, and when they were created.Cancel Execution: You can cancel a running agentic search execution using DELETE /v2/agentic-search/{execution_id} if you need to stop a search that is currently processing.Request
Your API key for authentication
Request Body
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"
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
Unique execution identifier for this search job. Use this ID with
GET /v2/agentic-search/{execution_id} to check progress and retrieve results.Format: agentic-{uuid}-{timestamp}Initial execution status. Always
"pending" when the search is first started.cURL
curl -X POST https://api.getcatalog.ai/v2/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"
}
}
}'
const response = await fetch('https://api.getcatalog.ai/v2/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();
console.log(`Search started with execution ID: ${data.execution_id}`);
console.log(`Credits used: ${data.meta.credits_used}`);
// Poll for results: GET /v2/agentic-search/{execution_id}
import requests
response = requests.post(
'https://api.getcatalog.ai/v2/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()
execution_id = data['execution_id']
print(f"Search started with execution ID: {execution_id}")
print(f"Credits used: {data['meta']['credits_used']}")
# Poll for results: GET /v2/agentic-search/{execution_id}
{
"execution_id": "agentic-a1b2c3d4-1735123456789",
"status": "pending",
"meta": {
"credits_used": 25
}
}
Response Schema and Enable Flags
The/v2/agentic-search endpoint maintains a consistent response schema regardless of enable_* flag values. When you retrieve results via GET status, all fields are always present in the product object of each item in the data array, but will be null when the corresponding flag is false.
Field Mappings:
| Flag | Affected Fields |
|---|---|
enable_enrichment | attributes, product_type, google_product_category_id, google_product_category_path |
⌘I