Agentic Search Mini

Fast synchronous search returning up to 10 products with AI-powered attribute enrichment.

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

cURL

PowerShell

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

Success Response

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

x-api-key · string · required

Your API key for authentication.

Request Body

query · string · required

Natural language search query for product discovery

Examples:

• "sustainable midi dresses"
• "luxury minimalist handbags"
• "versatile blazers for work"

enable_enrichment · 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

When to enable enrichment (default):

• You need detailed product attributes (color, material, features)
• You’re building product comparison tools
• You need rich product data for AI-powered recommendations

Response

data · array

Array of discovered products with enriched data (up to 10 results).

Hide Product Object

url · string

Product URL (normalized and cleaned)

product · object

Product details

Hide Product Properties

title · string

Product title

price · object

Price information

Show Price Properties

current_value · number

Current product price as a number (e.g., 99.99)

compare_at_value · number | null

Original/compare-at price if on sale, otherwise null

currency · string

Currency code (e.g., "USD")

description · string

Product description

images · array

Array of product image URLs

attributes · object

Comprehensive product attributes extracted through AI analysis and Google Shopping data. Attribute keys and values are dynamic and vary by product based on available information.

Show Common Attributes

color · string

Primary product color (when available)

material · string

Primary material composition (when available)

category · string

Product category classification (when available)

brand · string

Brand information (when available)

features · string

Key product features (when available)

Dynamic Attributes: The attributes object contains dynamic keys and values that vary by product. Common attributes like color, material, category, brand, and features may be present, but the exact structure depends on the product and available data sources (Google Shopping features and AI enrichment when enabled).

pagination · object

Pagination metadata for the results

Show Pagination Properties

page · number

Current page number (always 1 for this endpoint)

page_size · number

Number of items per page (equals the number of products returned)

total_items · number

Total number of products returned (may be less than 10 if some products couldn’t be processed)

total_pages · number

Total number of pages (always 1 for this endpoint)

has_next · boolean

Whether there is a next page (always false for this endpoint)

has_prev · boolean

Whether there is a previous page (always false for this endpoint)

meta · object

Response metadata

Show Meta Properties

request_id · 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

PowerShell

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

Success Response

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