Overview

Complete reference for the Catalog API endpoints

The Catalog API enables AI-powered product search across the web, discovery and indexing of product listings, real-time extraction of rich product data, and affiliate link generation for monetization. All endpoints return JSON responses.

Base URL

https://api.getcatalog.ai

Authentication

All requests require an API key in the x-api-key header. See Authentication for details.

Endpoints

Extract

Endpoint	Method	Description
/v2/extract	POST	Async extraction of product data from URLs or a vendor
/v2/extract	GET	List all extracts with status
/v2/extract/{execution_id}	GET	Get extract status and results
/v2/extract/{execution_id}	DELETE	Cancel a running extract

Search

Endpoint	Method	Description
/v2/agentic-search-mini	POST	Fast synchronous search returning up to 10 products
/v2/agentic-search	POST	Async AI-powered search with customer profile personalization
/v2/agentic-search	GET	List all agentic searches with status
/v2/agentic-search/{execution_id}	GET	Get agentic search status and results
/v2/agentic-search/{execution_id}	DELETE	Cancel a running agentic search

Crawl

Endpoint	Method	Description
/v2/crawl	POST	Async discovery of collections and product listings for a vendor
/v2/crawl	GET	List all crawls with status
/v2/crawl/{execution_id}	GET	Get crawl status and results
/v2/crawl/{execution_id}	DELETE	Cancel a running crawl

Vendors

Endpoint	Method	Description
/v2/vendors	GET	List your crawled vendors

Collections

Endpoint	Method	Description
/v2/collections	GET	Get collections for a vendor

Listings

Endpoint	Method	Description
/v2/listings	GET	Get product listings

Affiliate

Endpoint	Method	Description
/v2/affiliate	POST	Convert URLs to affiliate links

Usage

Endpoint	Method	Description
/v2/usage	GET	Get credit usage and API call statistics

Response format

All successful responses follow a consistent structure with a data array and pagination object:

{
  "data": [{ "_truncated": "Additional items omitted for display" }],
  "pagination": {
    "page": 1,
    "page_size": 10,
    "total_items": 100,
    "total_pages": 10,
    "has_next": true,
    "has_prev": false
  },
  "meta": {}
}

/{execution_id} endpoints also include execution_id and status fields:

{
  "execution_id": "_truncated",
  "status": "completed",
  "data": [{ "_truncated": "Additional items omitted for display" }],
  "pagination": {
    "page": 1,
    "page_size": 50,
    "total_items": 100,
    "total_pages": 2,
    "has_next": true,
    "has_prev": false
  },
  "meta": {
    "progress": { "_truncated": "Progress fields omitted for display" },
    "result": {
      "products_requested": 100,
      "products_successful": 98,
      "products_failed": 2
    }
  }
}

Error handling

Errors return appropriate HTTP status codes with structured error details:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error description",
    "request_id": "req_truncated"
  }
}

Additional fields may be included for specific error types. For example, validation errors may include:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "One or more URLs have invalid format",
    "request_id": "req_truncated"
  },
  "invalid_urls": [
    "Index 0: https://invalid-url - invalid format"
  ]
}

All error responses include a Request-ID header that matches the request_id in the response body.

See Error Codes for the complete reference.