Quickstart

Create your API key

Create your API key in the Catalog Dashboard.

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:

Crawl
Extract
Agentic Search
Generate Affiliate Links

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

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.

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/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()
print(f"Found {len(data['data'])} products")

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:

Crawl
Extract
Agentic Search
Generate Affiliate Links

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
      const listingsResponse = await fetch('https://api.getcatalog.ai/v2/listings', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'x-api-key': process.env.CATALOG_API_KEY
        },
        body: JSON.stringify({
          vendor: 'skims.com',
          page: 1,
          page_size: 5
        })
      });

      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();

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.

import dotenv from 'dotenv';

dotenv.config();

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 data = await response.json();
console.log(`Found ${data.data.length} products`);

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:

Crawl
Extract
Agentic Search
Generate Affiliate Links

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 POST https://api.getcatalog.ai/v2/listings \
  -H "Content-Type: application/json" \
  -H "x-api-key: ${CATALOG_API_KEY}" \
  -d '{
    "vendor": "skims.com",
    "page": 1,
    "page_size": 5
  }'

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.

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

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