Get Products by URLs

cURL

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

// Start async batch processing
const response = await fetch('https://api.getcatalog.ai/v1/products', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    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',
    enable_reviews: false,
    enable_image_tags: false
  })
});

const { execution_id } = await response.json();

// Poll for results: GET /v1/products/{execution_id}

import requests

# Start async batch processing
response = requests.post(
    'https://api.getcatalog.ai/v1/products',
    headers={
        'Content-Type': 'application/json',
        'x-api-key': 'YOUR_API_KEY'
    },
    json={
        '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',
        'enable_reviews': False,
        'enable_image_tags': False
    }
)

data = response.json()
execution_id = data['execution_id']

# Poll for results: GET /v1/products/{execution_id}

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

POST

products

cURL

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

// Start async batch processing
const response = await fetch('https://api.getcatalog.ai/v1/products', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    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',
    enable_reviews: false,
    enable_image_tags: false
  })
});

const { execution_id } = await response.json();

// Poll for results: GET /v1/products/{execution_id}

import requests

# Start async batch processing
response = requests.post(
    'https://api.getcatalog.ai/v1/products',
    headers={
        'Content-Type': 'application/json',
        'x-api-key': 'YOUR_API_KEY'
    },
    json={
        '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',
        'enable_reviews': False,
        'enable_image_tags': False
    }
)

data = response.json()
execution_id = data['execution_id']

# Poll for results: GET /v1/products/{execution_id}

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

string

required

Your API key for authentication

Request Body

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.

boolean

default:"true"

Whether to enable AI enrichment for products. When enabled, products are enhanced with additional attributes and categorization.

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

boolean

default:"false"

Whether to enable product reviews processing

boolean

default:"false"

Whether to enable AI-generated image tags and descriptions

Response

boolean

Whether the batch processing request was successfully started

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:

Use the execution_id to poll GET /v1/products/{execution_id}
Check the status field - when it’s "completed", results are available
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

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

// Start async batch processing
const response = await fetch('https://api.getcatalog.ai/v1/products', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    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',
    enable_reviews: false,
    enable_image_tags: false
  })
});

const { execution_id } = await response.json();

// Poll for results: GET /v1/products/{execution_id}

import requests

# Start async batch processing
response = requests.post(
    'https://api.getcatalog.ai/v1/products',
    headers={
        'Content-Type': 'application/json',
        'x-api-key': 'YOUR_API_KEY'
    },
    json={
        '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',
        'enable_reviews': False,
        'enable_image_tags': False
    }
)

data = response.json()
execution_id = data['execution_id']

# Poll for results: GET /v1/products/{execution_id}

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

Workflow

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

Get Started

API Reference

Guides

Resources

Request

Request Body

Response

Response Schema and Enable Flags

Workflow

​Request

​Request Body

​Response

​Response Schema and Enable Flags

​Workflow

Request

Request Body

Response

Response Schema and Enable Flags

Workflow