cURL
curl -X POST https://api.getcatalog.ai/v2/agentic-search-mini \
-H "Content-Type: application/json" \
-H "x-api-key: $CATALOG_API_KEY" \
-d '{
"query": "sustainable midi dresses",
"enable_enrichment": true
}'
const response = await fetch('https://api.getcatalog.ai/v2/agentic-search-mini', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-api-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
query: 'sustainable midi dresses',
enable_enrichment: true
})
});
const data = await response.json();
console.log(`Found ${data.data.length} products`);
import requests
response = requests.post(
'https://api.getcatalog.ai/v2/agentic-search-mini',
headers={
'Content-Type': 'application/json',
'x-api-key': 'YOUR_API_KEY'
},
json={
'query': 'sustainable midi dresses',
'enable_enrichment': True
}
)
data = response.json()
print(f"Found {len(data['data'])} products")
{
"data": [
{
"url": "https://bysonqo.com/products/floral-crochet-organic-cotton-dress-sustainable-party-top",
"product": {
"title": "Organic Cotton Floral Crochet Dress",
"price": {
"current_value": 733.6,
"compare_at_value": null,
"currency": "USD"
},
"description": "",
"images": [
[
"https://encrypted-tbn2.gstatic.com/shopping?q=tbn:ANd9GcQPlPfCKoRew2h3A9Xi54Wm1xfod5UhOVbLvgHtCW7m02kRkqYKg_IgyVrZ_-AZyT-AFivJYE3I0fMKhzQ3zDZCExx1K1UVxJ68QLeIqljZ"
]
],
"attributes": {
"product_name": "Floral Crochet Organic Cotton Dress",
"material": "100% Peruvian Organic Cotton",
"certifications": "GOTS, USDA",
"origin": "Handmade in Peru",
"design": "Crochet midi dress",
"measurements": "Hips: 36.22 inches (92 cm), Length: 40.55 inches (103 cm)",
"available_sizes": "S, M",
"available_colors": "Ivory, Black, Pink, Red, Orange, Gray, Light Blue, Light Green, Light Violet",
"care_instructions": "Hand wash with shampoo",
"production_time": "4-6 days"
}
}
},
...
],
"pagination": {
"page": 1,
"page_size": 10,
"total_items": 10,
"total_pages": 1,
"has_next": false,
"has_prev": false
},
"meta": {}
}
Search
Agentic Search Mini
Fast synchronous search returning up to 10 products. Optional AI-powered attribute enrichment.
POST
/
v2
/
agentic-search-mini
cURL
curl -X POST https://api.getcatalog.ai/v2/agentic-search-mini \
-H "Content-Type: application/json" \
-H "x-api-key: $CATALOG_API_KEY" \
-d '{
"query": "sustainable midi dresses",
"enable_enrichment": true
}'
const response = await fetch('https://api.getcatalog.ai/v2/agentic-search-mini', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-api-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
query: 'sustainable midi dresses',
enable_enrichment: true
})
});
const data = await response.json();
console.log(`Found ${data.data.length} products`);
import requests
response = requests.post(
'https://api.getcatalog.ai/v2/agentic-search-mini',
headers={
'Content-Type': 'application/json',
'x-api-key': 'YOUR_API_KEY'
},
json={
'query': 'sustainable midi dresses',
'enable_enrichment': True
}
)
data = response.json()
print(f"Found {len(data['data'])} products")
{
"data": [
{
"url": "https://bysonqo.com/products/floral-crochet-organic-cotton-dress-sustainable-party-top",
"product": {
"title": "Organic Cotton Floral Crochet Dress",
"price": {
"current_value": 733.6,
"compare_at_value": null,
"currency": "USD"
},
"description": "",
"images": [
[
"https://encrypted-tbn2.gstatic.com/shopping?q=tbn:ANd9GcQPlPfCKoRew2h3A9Xi54Wm1xfod5UhOVbLvgHtCW7m02kRkqYKg_IgyVrZ_-AZyT-AFivJYE3I0fMKhzQ3zDZCExx1K1UVxJ68QLeIqljZ"
]
],
"attributes": {
"product_name": "Floral Crochet Organic Cotton Dress",
"material": "100% Peruvian Organic Cotton",
"certifications": "GOTS, USDA",
"origin": "Handmade in Peru",
"design": "Crochet midi dress",
"measurements": "Hips: 36.22 inches (92 cm), Length: 40.55 inches (103 cm)",
"available_sizes": "S, M",
"available_colors": "Ivory, Black, Pink, Red, Orange, Gray, Light Blue, Light Green, Light Violet",
"care_instructions": "Hand wash with shampoo",
"production_time": "4-6 days"
}
}
},
...
],
"pagination": {
"page": 1,
"page_size": 10,
"total_items": 10,
"total_pages": 1,
"has_next": false,
"has_prev": false
},
"meta": {}
}
When to use: Ideal for autocomplete, quick previews, or when you need fast AI-enriched results with a small result set. For larger result sets with customer profile personalization, use
POST /v2/agentic-search.Request
string
required
Your API key for authentication.
Request Body
string
required
Natural language search query for product discoveryExamples:
"sustainable midi dresses""luxury minimalist handbags""versatile blazers for work"
boolean
default:"true"
Enable AI-powered product attribute enrichment for enhanced product data analysis. Set to
false for faster response times if detailed attributes are not needed.When to disable enrichment:- You need the fastest possible response times
- You only need basic product information (title, price, URL)
- You’re building a real-time autocomplete feature
- You need detailed product attributes (color, material, features)
- You’re building product comparison tools
- You need rich product data for AI-powered recommendations
Response
array
Array of discovered products with enriched data (up to 10 results).
Hide Product Object
Hide Product Object
string
Product URL (normalized and cleaned)
object
Product details
Hide Product Properties
Hide Product Properties
string
Product title
object
string
Product description
array
Array of product image URLs
object
Product attributes when AI enrichment is enabled.
Show Attributes object
Show Attributes object
Key-value object from AI enrichment. Structure is product-dependent; no fixed schema. May include semantic attributes (e.g. style, material, occasion) and other enriched fields.
object
Pagination metadata for the results
Show Pagination Properties
Show Pagination Properties
number
Current page number (always 1 for this endpoint)
number
Number of items per page (equals the number of products returned)
number
Total number of products returned (may be less than 10 if some products couldn’t be processed)
number
Total number of pages (always 1 for this endpoint)
boolean
Whether there is a next page (always false for this endpoint)
boolean
Whether there is a previous page (always false for this endpoint)
object
Response metadata
Show Meta Properties
Show Meta Properties
string
Unique request identifier for support purposes. Also available in the
Request-ID response header.Response Schema and Enable Flags
The/v2/agentic-search-mini endpoint maintains a consistent response schema regardless of enable_* flag values. All fields are always present in product objects returned in the data array, but will be null when the corresponding flag is false.
Field Mappings:
| Flag | Affected Fields | Behavior When false |
|---|---|---|
enable_enrichment | attributes, product_type, google_product_category_id, google_product_category_path |
cURL
curl -X POST https://api.getcatalog.ai/v2/agentic-search-mini \
-H "Content-Type: application/json" \
-H "x-api-key: $CATALOG_API_KEY" \
-d '{
"query": "sustainable midi dresses",
"enable_enrichment": true
}'
const response = await fetch('https://api.getcatalog.ai/v2/agentic-search-mini', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-api-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
query: 'sustainable midi dresses',
enable_enrichment: true
})
});
const data = await response.json();
console.log(`Found ${data.data.length} products`);
import requests
response = requests.post(
'https://api.getcatalog.ai/v2/agentic-search-mini',
headers={
'Content-Type': 'application/json',
'x-api-key': 'YOUR_API_KEY'
},
json={
'query': 'sustainable midi dresses',
'enable_enrichment': True
}
)
data = response.json()
print(f"Found {len(data['data'])} products")
{
"data": [
{
"url": "https://bysonqo.com/products/floral-crochet-organic-cotton-dress-sustainable-party-top",
"product": {
"title": "Organic Cotton Floral Crochet Dress",
"price": {
"current_value": 733.6,
"compare_at_value": null,
"currency": "USD"
},
"description": "",
"images": [
[
"https://encrypted-tbn2.gstatic.com/shopping?q=tbn:ANd9GcQPlPfCKoRew2h3A9Xi54Wm1xfod5UhOVbLvgHtCW7m02kRkqYKg_IgyVrZ_-AZyT-AFivJYE3I0fMKhzQ3zDZCExx1K1UVxJ68QLeIqljZ"
]
],
"attributes": {
"product_name": "Floral Crochet Organic Cotton Dress",
"material": "100% Peruvian Organic Cotton",
"certifications": "GOTS, USDA",
"origin": "Handmade in Peru",
"design": "Crochet midi dress",
"measurements": "Hips: 36.22 inches (92 cm), Length: 40.55 inches (103 cm)",
"available_sizes": "S, M",
"available_colors": "Ivory, Black, Pink, Red, Orange, Gray, Light Blue, Light Green, Light Violet",
"care_instructions": "Hand wash with shampoo",
"production_time": "4-6 days"
}
}
},
...
],
"pagination": {
"page": 1,
"page_size": 10,
"total_items": 10,
"total_pages": 1,
"has_next": false,
"has_prev": false
},
"meta": {}
}
⌘I