Skip to main content
POST
https://api.getcatalog.ai
/
v2
/
agentic-search
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 -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. 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:
FlagAffected Fields
enable_enrichmentattributes, product_type, google_product_category_id, google_product_category_path