Agentic Search

Async AI-powered search with customer profile personalization. Returns immediately with an execution_id to check status and retrieve results.

POST https://api.getcatalog.ai/v2/agentic-search

cURL

PowerShell

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"
      }
    }
  }'

POST Response (202 Accepted)

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

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

Show Meta Object

credits_used · number

Number of credits charged for starting this search operation

request_id · string

Unique request identifier for support purposes (also available in the Request-ID response header)

cURL

PowerShell

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"
      }
    }
  }'

POST Response (202 Accepted)

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