​
API Key Authentication

The API uses a simple key-based authentication system. You must include your API key in the x-api-key header with every request:

curl -X POST https://catalogai.vercel.app/api/products \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_VALID_API_KEY" \
  -d '{ "query": "t-shirt" }'

Replace YOUR_VALID_API_KEY with the actual API key provided to you by our team.

​
Obtaining an API Key

To get an API key:

  1. Contact our team to request access to the Catalog API
  2. Once onboarded, you’ll receive your unique API key
  3. Store this key securely and do not share it publicly

​
Making Your First API Call

​
1. Basic Search Request

Let’s start with a simple discovery query for “organic cotton shirt”:

curl -X POST https://catalogai.vercel.app/api/products \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_VALID_API_KEY" \
  -d '{
        "query": "organic cotton shirt"
      }'

​
2. Understanding the Response

If successful, you’ll receive a JSON response containing an array of matching products and metadata for your AI shopping agent:

{
  "products": [
    {
      "id": 1234,
      "title": "Organic Cotton T-Shirt",
      "description": "Comfortable 100% organic cotton t-shirt",
      "vendor": "EcoWear",
      "is_available": true,
      // More product properties...
    },
    // More products...
  ],
  "meta": {
    "totalItems": 42,
    "totalPages": 5,
    "currentPage": 1,
    "pageSize": 10
  }
}

​
3. Adding Filters

Now, let’s refine our AI agent’s discovery by adding filters:

curl -X POST https://catalogai.vercel.app/api/products \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_VALID_API_KEY" \
  -d '{
        "query": "shirt",
        "filters": {
          "price_min": 20.00,
          "price_max": 50.00,
          "is_available": true,
          "attributes": {
            "color": "Blue"
          }
        }
      }'

​
Next Steps

Congratulations! You’ve now made your first API call to the Catalog AI discovery platform. To learn more about what you can do with AI shopping agents:

  • Explore our Developer Guide for detailed request options
  • Learn about Filtering options to fine-tune your product discovery