Agentic Search Mini

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

POST /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

Product attributes when AI enrichment is enabled.

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.

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