Quickstart

Create your API key

Contact our team to obtain your API key.

Create a .env file

Create a file called .env in the root of your project and add the following line.

CATALOG_API_KEY=<YOUR_API_KEY>

Make an API request

Use Python or JavaScript, or call the API directly with cURL.

Python
JavaScript
cURL

Install the required Python packages. If you want to store your API key in a .env file, make sure to install the dotenv library.

pip install requests
pip install python-dotenv

Once you’ve installed the dependencies, choose an endpoint below to get started:

Extract
Agentic Search
Crawl
Generate Affiliate Links

Extract high-quality, real-time product data.

import os
import requests
import time
from dotenv import load_dotenv

# Use .env to store your API key or paste it directly into the code
load_dotenv()

# Start async extraction with URLs
response = requests.post(
    'https://api.getcatalog.ai/v2/extract',
    headers={
        'Content-Type': 'application/json',
        'x-api-key': os.getenv('CATALOG_API_KEY')
    },
    json={
        'urls': [
            'https://www.nike.com/t/air-force-1-07-mens-shoes-5QFp5Z/CW2288-111'
        ],
        'enable_enrichment': False,
        'country_code': 'us'
    }
)

data = response.json()
execution_id = data['execution_id']
print(f"Started extraction with execution ID: {execution_id}")

# Poll for results
while True:
    status_response = requests.get(
        f'https://api.getcatalog.ai/v2/extract/{execution_id}',
        headers={'x-api-key': os.getenv('CATALOG_API_KEY')}
    )
    status_data = status_response.json()
    
    if status_data['status'] == 'completed':
        product = status_data['data'][0]
        if product['success']:
            print(f"Product title: {product['product']['title']}")
        break
    elif status_data['status'] == 'failed':
        print(f"Extraction failed: {status_data.get('error', 'Unknown error')}")
        break
    else:
        progress = status_data.get('meta', {}).get('progress', {})
        print(f"Progress: {progress.get('percent_complete', 0)}%")
        time.sleep(5)  # Wait 5 seconds before next poll

AI-powered semantic search tailored to customer profiles. This endpoint is async: it returns an execution_id immediately; poll the status endpoint until completed to get results.

import os
import requests
import time
from dotenv import load_dotenv

# Use .env to store your API key or paste it directly into the code
load_dotenv()

# Start async search
response = requests.post(
    'https://api.getcatalog.ai/v2/agentic-search',
    headers={
        'Content-Type': 'application/json',
        'x-api-key': os.getenv('CATALOG_API_KEY')
    },
    json={
        'query': 'sustainable minimalist sneakers for everyday wear'
    }
)

data = response.json()
execution_id = data['execution_id']
print(f"Search started with execution ID: {execution_id}")

# Poll for results
while True:
    status_response = requests.get(
        f'https://api.getcatalog.ai/v2/agentic-search/{execution_id}',
        headers={'x-api-key': os.getenv('CATALOG_API_KEY')}
    )
    status_data = status_response.json()

    if status_data['status'] == 'completed':
        products = status_data.get('data', [])
        print(f"Found {len(products)} products")
        for item in products[:3]:
            if item.get('product'):
                print(f"  - {item['product'].get('title', 'N/A')}")
        break
    elif status_data['status'] == 'failed':
        print(f"Search failed: {status_data.get('error', 'Unknown error')}")
        break
    else:
        progress = status_data.get('meta', {}).get('progress', {})
        print(f"Progress: {progress.get('percent_complete', 0)}%")
        time.sleep(5)  # Wait 5 seconds before next poll

Discover collections and product listings

import os
import requests
import time
from dotenv import load_dotenv

# Use .env to store your API key or paste it directly into the code
load_dotenv()

# Start async crawl
response = requests.post(
    'https://api.getcatalog.ai/v2/crawl',
    headers={
        'Content-Type': 'application/json',
        'x-api-key': os.getenv('CATALOG_API_KEY')
    },
    json={
        'url': 'skims.com'
    }
)

data = response.json()
execution_id = data['execution_id']
print(f"Crawl started with execution ID: {execution_id}")

# Poll for results
while True:
    status_response = requests.get(
        f'https://api.getcatalog.ai/v2/crawl/{execution_id}',
        headers={'x-api-key': os.getenv('CATALOG_API_KEY')}
    )
    status_data = status_response.json()
    
    if status_data['status'] == 'completed':
        result = status_data['meta']['result']
        print(f"Crawl completed!")
        print(f"Collections found: {result['collections_total']}")
        print(f"Listings found: {result['listings_total']}")
        break
    elif status_data['status'] == 'failed':
        print(f"Crawl failed: {status_data.get('error', 'Unknown error')}")
        break
    else:
        progress = status_data.get('meta', {}).get('progress')
        if progress:
            print(f"Progress: {progress['collections_found']} collections, {progress['listings_found']} listings")
        time.sleep(10)  # Wait 10 seconds before next poll

# Fetch the discovered listings (GET with query params)
listings_response = requests.get(
    'https://api.getcatalog.ai/v2/listings',
    headers={'x-api-key': os.getenv('CATALOG_API_KEY')},
    params={
        'vendor': 'skims.com',
        'page': 1,
        'page_size': 5
    }
)

listings = listings_response.json()
print(f"\nFirst {len(listings['data'])} listings:")
for listing in listings['data']:
    print(f"- {listing['name']}: {listing['url']}")

Generate affiliate links to earn up to 5% on purchases across 50k+ vendors.

import os
import requests
from dotenv import load_dotenv

# Use .env to store your API key or paste it directly into the code
load_dotenv()

response = requests.post(
    'https://api.getcatalog.ai/v2/affiliate',
    headers={
        'Content-Type': 'application/json',
        'x-api-key': os.getenv('CATALOG_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'
        ]
    }
)

data = response.json()
for result in data['data']:
    print(f"Original: {result['original_url']}")
    print(f"Affiliate: {result['wildfire_link']}")

Install the required JavaScript packages. If you want to store your API key in a .env file, make sure to install the dotenv library.

npm install dotenv

Once you’ve installed the dependencies, choose an endpoint below to get started:

Extract
Agentic Search
Crawl
Generate Affiliate Links

Extract high-quality, real-time product data.

import dotenv from 'dotenv';

dotenv.config();

// Start async extraction with URLs
const response = await fetch('https://api.getcatalog.ai/v2/extract', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': process.env.CATALOG_API_KEY
  },
  body: JSON.stringify({
    urls: [
      'https://www.nike.com/t/air-force-1-07-mens-shoes-5QFp5Z/CW2288-111'
    ],
    enable_enrichment: false,
    country_code: 'us'
  })
});

const { execution_id } = await response.json();
console.log(`Started extraction with execution ID: ${execution_id}`);

// Poll for results
const pollStatus = async () => {
  while (true) {
    const statusResponse = await fetch(
      `https://api.getcatalog.ai/v2/extract/${execution_id}`,
      {
        headers: {
          'x-api-key': process.env.CATALOG_API_KEY
        }
      }
    );
    
    const statusData = await statusResponse.json();
    
    if (statusData.status === 'completed') {
      const product = statusData.data[0];
      if (product.success) {
        console.log(`Product title: ${product.product.title}`);
      }
      break;
    } else if (statusData.status === 'failed') {
      console.error(`Extraction failed: ${statusData.error || 'Unknown error'}`);
      break;
    } else {
      const progress = statusData.meta?.progress || {};
      console.log(`Progress: ${progress.percent_complete || 0}%`);
      await new Promise(resolve => setTimeout(resolve, 5000)); // Wait 5 seconds
    }
  }
};

pollStatus();

AI-powered semantic search tailored to customer profiles. This endpoint is async: it returns an execution_id immediately; poll the status endpoint until completed to get results.

import dotenv from 'dotenv';

dotenv.config();

// Start async search
const response = await fetch('https://api.getcatalog.ai/v2/agentic-search', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': process.env.CATALOG_API_KEY
  },
  body: JSON.stringify({
    query: 'sustainable minimalist sneakers for everyday wear'
  })
});

const { execution_id } = await response.json();
console.log(`Search started with execution ID: ${execution_id}`);

// Poll for results
const pollStatus = async () => {
  while (true) {
    const statusResponse = await fetch(
      `https://api.getcatalog.ai/v2/agentic-search/${execution_id}`,
      { headers: { 'x-api-key': process.env.CATALOG_API_KEY } }
    );
    const statusData = await statusResponse.json();

    if (statusData.status === 'completed') {
      const products = statusData.data || [];
      console.log(`Found ${products.length} products`);
      products.slice(0, 3).forEach((item) => {
        if (item.product) console.log(`  - ${item.product.title || 'N/A'}`);
      });
      break;
    } else if (statusData.status === 'failed') {
      console.error(`Search failed: ${statusData.error || 'Unknown error'}`);
      break;
    } else {
      const progress = statusData.meta?.progress || {};
      console.log(`Progress: ${progress.percent_complete || 0}%`);
      await new Promise((r) => setTimeout(r, 5000));
    }
  }
};

pollStatus();

Discover collections and product listings

import dotenv from 'dotenv';

dotenv.config();

// Start async crawl
const response = await fetch('https://api.getcatalog.ai/v2/crawl', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': process.env.CATALOG_API_KEY
  },
  body: JSON.stringify({
    url: 'skims.com'
  })
});

const { execution_id } = await response.json();
console.log(`Crawl started with execution ID: ${execution_id}`);

// Poll for results
const pollStatus = async () => {
  while (true) {
    const statusResponse = await fetch(
      `https://api.getcatalog.ai/v2/crawl/${execution_id}`,
      {
        headers: {
          'x-api-key': process.env.CATALOG_API_KEY
        }
      }
    );
    
    const statusData = await statusResponse.json();
    
    if (statusData.status === 'completed') {
      const result = statusData.meta.result;
      console.log('Crawl completed!');
      console.log(`Collections found: ${result.collections_total}`);
      console.log(`Listings found: ${result.listings_total}`);

      // Fetch the discovered listings (GET with query params)
      const listingsParams = new URLSearchParams({
        vendor: 'skims.com',
        page: '1',
        page_size: '5'
      });
      const listingsResponse = await fetch(
        `https://api.getcatalog.ai/v2/listings?${listingsParams}`,
        { headers: { 'x-api-key': process.env.CATALOG_API_KEY } }
      );

      const listings = await listingsResponse.json();
      console.log(`\nFirst ${listings.data.length} listings:`);
      listings.data.forEach(listing => {
        console.log(`- ${listing.name}: ${listing.url}`);
      });
      break;
    } else if (statusData.status === 'failed') {
      console.error(`Crawl failed: ${statusData.error || 'Unknown error'}`);
      break;
    } else {
      const progress = statusData.meta?.progress;
      if (progress) {
        console.log(`Progress: ${progress.collections_found} collections, ${progress.listings_found} listings`);
      }
      await new Promise(resolve => setTimeout(resolve, 10000)); // Wait 10 seconds
    }
  }
};

pollStatus();

Generate affiliate links to earn up to 5% on purchases across 50k+ vendors.

import dotenv from 'dotenv';

dotenv.config();

const response = await fetch('https://api.getcatalog.ai/v2/affiliate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': process.env.CATALOG_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'
    ]
  })
});

const data = await response.json();
data.data.forEach(result => {
  console.log(`Original: ${result.original_url}`);
  console.log(`Affiliate: ${result.wildfire_link}`);
});

cURL is typically pre-installed on most systems. No installation needed.Pass one of the following commands to your terminal to make an API request:

Extract
Agentic Search
Crawl
Generate Affiliate Links

Extract high-quality, real-time product data.

# Start async extraction with URLs
curl -X POST https://api.getcatalog.ai/v2/extract \
  -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"
    ],
    "enable_enrichment": false,
    "country_code": "us"
  }'

# Check execution status (replace EXECUTION_ID with the execution_id from the response above)
curl -X GET "https://api.getcatalog.ai/v2/extract/EXECUTION_ID" \
  -H "x-api-key: ${CATALOG_API_KEY}"

AI-powered semantic search tailored to customer profiles. This endpoint is async: it returns an execution_id; poll the status URL until status is “completed” to get results.

# Start async search (returns execution_id)
curl -X POST https://api.getcatalog.ai/v2/agentic-search \
  -H "Content-Type: application/json" \
  -H "x-api-key: ${CATALOG_API_KEY}" \
  -d '{
    "query": "sustainable minimalist sneakers for everyday wear"
  }'

# Check status and get results (replace EXECUTION_ID with the execution_id from the response above)
curl -X GET "https://api.getcatalog.ai/v2/agentic-search/EXECUTION_ID" \
  -H "x-api-key: ${CATALOG_API_KEY}"

Discover collections and product listings

# Start async crawl
curl -X POST https://api.getcatalog.ai/v2/crawl \
  -H "Content-Type: application/json" \
  -H "x-api-key: ${CATALOG_API_KEY}" \
  -d '{
    "url": "skims.com"
  }'

# Check execution status (replace EXECUTION_ID with the execution_id from the response above)
curl -X GET "https://api.getcatalog.ai/v2/crawl/EXECUTION_ID" \
  -H "x-api-key: ${CATALOG_API_KEY}"

# Fetch the discovered listings (after crawl completes)
curl -X GET "https://api.getcatalog.ai/v2/listings?vendor=skims.com&page=1&page_size=5" \
  -H "x-api-key: ${CATALOG_API_KEY}"

Generate affiliate links to earn up to 5% on purchases across 50k+ vendors.

curl -X POST https://api.getcatalog.ai/v2/affiliate \
  -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"
    ]
  }'

Get Started

API Reference

Guides

Resources

Migration Guides

Create your API key

Create a .env file

Make an API request

Get Started

API Reference

Guides

Resources

Migration Guides

​Create your API key

​Create a .env file

​Make an API request

Create your API key

Create a .env file

Make an API request