> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getcatalog.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Make your first Catalog API request in under 5 minutes

## Create your API key

[Contact our team](mailto:founders@getcatalog.ai) 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.

```bash theme={null}
CATALOG_API_KEY=<YOUR_API_KEY>
```

## Make an API request

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

<Tabs>
  <Tab title="Python">
    Install the required Python packages. If you want to store your API key in a `.env` file, make sure to install the dotenv library.

    ```bash theme={null}
    pip install requests
    pip install python-dotenv
    ```

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

    <Tabs>
      <Tab title="Extract">
        Extract high-quality, real-time product data.

        ```python theme={null}
        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 batch processing
        response = requests.post(
            'https://api.getcatalog.ai/v1/products',
            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': True,
                'country_code': 'us'
            }
        )

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

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

      <Tab title="Agentic Search">
        AI-powered semantic search tailored to customer profiles.

        ```python theme={null}
        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/v1/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 {data['meta']['totalItems']} products")
        ```
      </Tab>

      <Tab title="Crawl">
        Discover collections and product listings

        ```python theme={null}
        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/v1/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/v1/crawl/{execution_id}',
                headers={'x-api-key': os.getenv('CATALOG_API_KEY')}
            )
            status_data = status_response.json()
            
            if status_data['status'] == 'completed':
                print(f"Crawl completed! Found {status_data['total_listings_found']} listings")
                break
            elif status_data['status'] == 'failed':
                print("Crawl failed")
                break
            else:
                print("Crawl is still running...")
                time.sleep(10)  # Wait 10 seconds before next poll

        # Fetch the discovered listings
        listings_response = requests.post(
            'https://api.getcatalog.ai/v1/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['listings'])} listings:")
        for listing in listings['listings']:
            print(f"- {listing['name']}: {listing['url']}")
        ```
      </Tab>

      <Tab title="Generate Affiliate Links">
        Generate affiliate links to earn up to 5% on purchases across 50k+ vendors.

        ```python theme={null}
        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/v1/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['results']:
            print(f"Original: {result['original_url']}")
            print(f"Affiliate: {result['wildfire_link']}")
        ```
      </Tab>
    </Tabs>
  </Tab>

  <Tab title="JavaScript">
    Install the required JavaScript packages. If you want to store your API key in a `.env` file, make sure to install the dotenv library.

    ```bash theme={null}
    npm install dotenv
    ```

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

    <Tabs>
      <Tab title="Extract">
        Extract high-quality, real-time product data.

        ```javascript theme={null}
        import dotenv from 'dotenv';

        dotenv.config();

        // Start async batch processing
        const response = await fetch('https://api.getcatalog.ai/v1/products', {
          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: true,
            country_code: 'us'
          })
        });

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

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

        pollStatus();
        ```
      </Tab>

      <Tab title="Agentic Search">
        AI-powered semantic search tailored to customer profiles.

        ```javascript theme={null}
        import dotenv from 'dotenv';

        dotenv.config();

        const response = await fetch('https://api.getcatalog.ai/v1/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.meta.totalItems} products`);
        ```
      </Tab>

      <Tab title="Crawl">
        Discover collections and product listings

        ```javascript theme={null}
        import dotenv from 'dotenv';

        dotenv.config();

        // Start async crawl
        const response = await fetch('https://api.getcatalog.ai/v1/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/v1/crawl/${execution_id}`,
              {
                headers: {
                  'x-api-key': process.env.CATALOG_API_KEY
                }
              }
            );
            
            const statusData = await statusResponse.json();
            
            if (statusData.status === 'completed') {
              console.log(`Crawl completed! Found ${statusData.total_listings_found} listings`);

              // Fetch the discovered listings
              const listingsResponse = await fetch('https://api.getcatalog.ai/v1/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.listings.length} listings:`);
              listings.listings.forEach(listing => {
                console.log(`- ${listing.name}: ${listing.url}`);
              });
              break;
            } else if (statusData.status === 'failed') {
              console.error('Crawl failed');
              break;
            } else {
              console.log('Crawl is still running...');
              await new Promise(resolve => setTimeout(resolve, 10000)); // Wait 10 seconds
            }
          }
        };

        pollStatus();
        ```
      </Tab>

      <Tab title="Generate Affiliate Links">
        Generate affiliate links to earn up to 5% on purchases across 50k+ vendors.

        ```javascript theme={null}
        import dotenv from 'dotenv';

        dotenv.config();

        const response = await fetch('https://api.getcatalog.ai/v1/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.results.forEach(result => {
          console.log(`Original: ${result.original_url}`);
          console.log(`Affiliate: ${result.wildfire_link}`);
        });
        ```
      </Tab>
    </Tabs>
  </Tab>

  <Tab title="cURL">
    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:

    <Tabs>
      <Tab title="Extract">
        Extract high-quality, real-time product data.

        ```bash theme={null}
        # Start async batch processing
        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"
            ],
            "enable_enrichment": true,
            "country_code": "us"
          }'

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

      <Tab title="Agentic Search">
        AI-powered semantic search tailored to customer profiles.

        ```bash theme={null}
        curl -X POST https://api.getcatalog.ai/v1/agentic-search \
          -H "Content-Type: application/json" \
          -H "x-api-key: ${CATALOG_API_KEY}" \
          -d '{
            "query": "sustainable minimalist sneakers for everyday wear"
          }'
        ```
      </Tab>

      <Tab title="Crawl">
        Discover collections and product listings

        ```bash theme={null}
        # Start async crawl
        curl -X POST https://api.getcatalog.ai/v1/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/v1/crawl/EXECUTION_ID" \
          -H "x-api-key: ${CATALOG_API_KEY}"

        # Fetch the discovered listings (after crawl completes)
        curl -X POST https://api.getcatalog.ai/v1/listings \
          -H "Content-Type: application/json" \
          -H "x-api-key: ${CATALOG_API_KEY}" \
          -d '{
            "vendor": "skims.com",
            "page": 1,
            "page_size": 5
          }'
        ```
      </Tab>

      <Tab title="Generate Affiliate Links">
        Generate affiliate links to earn up to 5% on purchases across 50k+ vendors.

        ```bash theme={null}
        curl -X POST https://api.getcatalog.ai/v1/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"
            ]
          }'
        ```
      </Tab>
    </Tabs>
  </Tab>
</Tabs>