Skip to main content
POST
https://api.getcatalog.ai
/
v1
/
products
curl -X POST https://api.getcatalog.ai/v1/products \
  -H "Content-Type: application/json" \
  -H "x-api-key: $CATALOG_API_KEY" \
  -d '{
    "urls": [
      "https://www.nike.com/t/air-force-1-07-mens-shoes-5QFp5Z/CW2288-111",
      "https://www.adidas.com/us/gazelle-shoes/BB5476.html"
    ],
    "enable_enrichment": true,
    "country_code": "us"
  }'

{
  "success": true,
  "execution_id": "products-batch-51d87084-7f42-402f-a5af-6ff512c82cd0"
}
Async Processing: This endpoint starts processing asynchronously and returns an execution_id immediately. Use GET /v1/products/{execution_id} to check progress and retrieve results when processing completes.
Managing Executions:
  • View All Executions: You can view all your product processing executions using GET /v1/products to see all processing jobs, their statuses, and when they were created.
  • Cancel Running Executions: If you need to stop a running execution, use DELETE /v1/products/{execution_id}.

​
Request

​
x-api-key
string
required
Your API key for authentication

​
Request Body

​
urls
string[]
required
Array of product URLs to process (up to 1000 URLs per request)Requirements:
  • Must be a non-empty array
  • Each entry must be a non-empty string
  • Maximum 1000 URLs per request
Example:
[
  "https://www.nike.com/t/air-force-1-07-mens-shoes-5QFp5Z/CW2288-111",
  "https://www.adidas.com/us/gazelle-shoes/BB5476.html",
  "https://www.example-store.com/product/123"
]
Note: You can send a single URL in an array: ["https://example.com/product"]
​
enable_enrichment
boolean
default:"true"
Whether to enable AI enrichment for products. When enabled, products are enhanced with additional attributes and categorization.
​
country_code
string
default:"us"
ISO 2-letter country code for localization (e.g., “us”, “ca”, “gb”, “de”)Supported Country Codes: nl, ca, si, co, by, ee, no, br, us, de, es, vn, il, th, gb, ph, kg, in, ru, fr, hk, ua, jp, at, mm, my, pl, au, nz, ro, tw, mx, id, dk, ng, ch, hu, sg, sa, ae, cn, ar, cl, it, tr, lv, gh, sk, gr, eg, lu, bg, se, lt, lk, kz, hr, bd, kr, cz, fi, ie, be, pt, za
​
enable_reviews
boolean
default:"false"
Whether to enable product reviews processing
​
enable_image_tags
boolean
default:"false"
Whether to enable AI-generated image tags and descriptions

​
Response

​
success
boolean
Whether the batch processing request was successfully started
​
execution_id
string
Unique execution identifier for this batch processing job. Use this ID with GET /v1/products/{execution_id} to check progress and retrieve results.Format: products-batch-{uuid}
Getting Results: The POST endpoint returns immediately with an execution_id. Processing happens asynchronously. To get your results:
  1. Use the execution_id to poll GET /v1/products/{execution_id}
  2. Check the status field - when it’s "completed", results are available
  3. Use pagination parameters (page, limit) to retrieve results in chunks

​
Response Schema and Enable Flags

The /v1/products endpoint maintains a consistent response schema regardless of enable_* flag values. All fields are always present in product objects, but will be null when the corresponding flag is false. Field Mappings:
FlagAffected Fields
enable_reviewsreviews
enable_enrichmentattributes, product_type, google_product_category_id, google_product_category_path
enable_image_tagsimages[].attributes
curl -X POST https://api.getcatalog.ai/v1/products \
  -H "Content-Type: application/json" \
  -H "x-api-key: $CATALOG_API_KEY" \
  -d '{
    "urls": [
      "https://www.nike.com/t/air-force-1-07-mens-shoes-5QFp5Z/CW2288-111",
      "https://www.adidas.com/us/gazelle-shoes/BB5476.html"
    ],
    "enable_enrichment": true,
    "country_code": "us"
  }'

{
  "success": true,
  "execution_id": "products-batch-51d87084-7f42-402f-a5af-6ff512c82cd0"
}

​
Workflow

  1. Start Processing: Send a POST request with your URLs to start async batch processing
  2. Get Execution ID: Receive an execution_id immediately in the response
  3. Check Status: Poll GET /v1/products/{execution_id} using the execution_id
  4. Retrieve Results: When status is "completed", results are available with pagination support