Catalog API Reference

Complete API reference for product search, discovery, and commerce intelligence endpoints. Includes authentication, request/response formats, and error handling.

The Catalog API provides powerful endpoints for product search, discovery, and commerce intelligence. Build intelligent shopping experiences with natural language search, detailed product data, and real-time availability information.

What is the API base URL?

All API endpoints use the base URL:

https://api.getcatalog.ai

How do you authenticate API requests?

All requests require your API key in the x-api-key header. Get your API key if you don’t have one yet.

curl -H "x-api-key: YOUR_API_KEY" https://api.getcatalog.ai/api/search

Keep your API key secure and never expose it in client-side code. Store it in environment variables or secure configuration.

What endpoints are available?

Feed

Get Feed

GET /api/feed

Retrieve customizable product feeds for commerce applications.

Product

Get Product by URL

POST /api/product

Get detailed information about a specific product by URL.

Vendors

List Vendors

GET /api/vendors

List all available vendors and their metadata.

Search

Agentic Search

POST /api/search

Advanced AI-powered product search with natural language understanding and comprehensive filtering.

Agentic Search Mini

POST /v1/agentic-search-mini

Fast product discovery with optional AI enrichment (up to 10 results).

Regular Search

POST /api/regular-search

High-performance product search without AI processing for maximum speed.

What do API responses look like?

All API responses follow a consistent structure:

{
  "data": {
    // Response data specific to the endpoint
  },
  "meta": {
    "totalItems": 100,
    "totalPages": 10,
    "currentPage": 1,
    "pageSize": 10
  }
}

For search and feed endpoints, the response includes a products array:

{
  "products": [
    {
      "id": "12345",
      "title": "Product Name",
      "description": "Product description",
      "vendor": "Brand Name",
      "price": 2999,
      "currency": "USD",
      "is_available": true,
      "image_url": "https://example.com/image.jpg",
      "attributes": {
        "color": "blue",
        "material": "cotton",
        "category": "Women > Shirts"
      }
    }
  ],
  "meta": {
    "totalItems": 42,
    "totalPages": 5,
    "currentPage": 1,
    "pageSize": 10
  }
}

How does the API handle errors?

The API returns errors with standard HTTP status codes and detailed error information to help you troubleshoot issues quickly:

{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "The 'query' parameter must be a string",
    "details": {
      "parameter": "query",
      "expected": "string",
      "received": "number"
    }
  }
}

Common error codes and how to fix them

Error Code	HTTP Status	What it means	How to fix
UNAUTHORIZED	401	Invalid or missing API key	Check your API key is correct and included in the x-api-key header
FORBIDDEN	403	API key access denied	Contact support to verify your API key permissions
INVALID_PARAMETER	400	Invalid request parameter	Review the parameter requirements in the endpoint documentation
NOT_FOUND	404	Resource not found	Verify the endpoint URL and any resource IDs
RATE_LIMITED	429	Too many requests	Implement rate limiting or reduce request frequency
INTERNAL_ERROR	500	Server error	Try again or contact support if the issue persists

All error responses include detailed message and details fields to help you identify and fix issues quickly.