Skip to main content
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"
      }
    }
  }'

{
  "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

​
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

​
execution_id
string
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}
​
status
string
Initial execution status. Always "pending" when the search is first started.
​
meta
object
Metadata about the request
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"
      }
    }
  }'

{
  "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:
FlagAffected Fields
enable_enrichmentattributes, product_type, google_product_category_id, google_product_category_path