Get Products by URLs

Async extraction of product data from product URLs (up to 1000). Returns immediately with an execution_id to check status and retrieve results.

POST /v1/products

cURL

PowerShell

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"
  }'

POST Response

{
  "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"]

URL sanitization: URLs are sanitized and normalized on the backend; client-side sanitization is not required.

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:

Flag	Affected Fields
enable_reviews	reviews
enable_enrichment	attributes, product_type, google_product_category_id, google_product_category_path
enable_image_tags	images[].attributes

cURL

PowerShell

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"
  }'

POST Response

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