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

# Topsort Developer Documentation

<style>
  {`
    /* Hide the page title heading but keep it for browser tab */
    #header,
    #header h1 {
      display: none !important;
      visibility: hidden !important;
      height: 0 !important;
      overflow: hidden !important;
    }

    /* Remove tab highlighting on homepage */
    .nav-tabs-item {
      color: rgb(107, 114, 128) !important; /* text-gray-600 */
      text-shadow: none !important;
    }

    .dark .nav-tabs-item {
      color: rgb(156, 163, 175) !important; /* dark:text-gray-400 */
    }

    /* Subtle animated gradient background */
    .hero-gradient {
      background: linear-gradient(135deg,
        rgba(59, 130, 246, 0.05) 0%,
        rgba(139, 92, 246, 0.05) 50%,
        rgba(236, 72, 153, 0.05) 100%);
      background-size: 200% 200%;
      animation: gradientShift 15s ease infinite;
    }

    @keyframes gradientShift {
      0%, 100% { background-position: 0% 50%; }
      50% { background-position: 100% 50%; }
    }

    /* Smooth card hover effect */
    .hover-lift {
      transition: all 0.3s ease;
    }

    .hover-lift:hover {
      transform: translateY(-4px);
      box-shadow: 0 12px 24px -10px rgba(0, 0, 0, 0.2);
    }

    /* Enhance Mintlify cards */
    .markdown [class*="Card"] {
      transition: all 0.3s ease;
    }

    .markdown [class*="Card"]:hover {
      transform: translateY(-2px);
    }

    `}
</style>

<video id="bg-video" autoPlay muted loop playsInline>
  <source src="https://storage.googleapis.com/big-content-pub/combined-light.mp4" type="video/mp4" />
</video>

{/* Mascot images suppressed
<div className="hero-mascot-overlay">
<img
  src="https://storage.googleapis.com/big-content-pub/product/docs/themes/winter-holiday/proto-fill-grinch.png"
  alt=""
  className="hero-mascot-light"
  aria-hidden="true"
/>
<img
  src="https://storage.googleapis.com/big-content-pub/product/docs/themes/winter-holiday/proto-fill-grinch-lights-out.png"
  alt=""
  className="hero-mascot-dark"
  aria-hidden="true"
/>
</div>
*/}

{/* Toppie Video - Centered above title  */}

<div
  id="toppie-container"
  style={{
display: 'flex',
justifyContent: 'center',
alignItems: 'center',
width: '100%',
marginTop: '-2rem'
}}
>
  <video
    id="toppie-video"
    autoPlay
    muted
    playsInline
    loop={false}
    style={{
  width: '400px',
  height: '400px',
  objectFit: 'contain',
  display: 'block',
  marginBottom: '-140px',
  opacity: 1
}}
  >
    <source src="https://storage.googleapis.com/big-content-pub/toppie-fourleaf-animated.webm" type="video/webm" />
  </video>

  <img
    id="toppie-fallback"
    src="https://mintcdn.com/topsort/1RZV69Uhic79Ylqv/assets/topsort-mascot-jumping-full.png?fit=max&auto=format&n=1RZV69Uhic79Ylqv&q=85&s=ed787924392024d85b9e32d11ab93266"
    alt="Topsort Mascot"
    style={{
  width: '500px',
  height: '500px',
  objectFit: 'contain',
  display: 'none',
  marginTop: '-80px',
  marginBottom: '-195px',
  pointerEvents: 'none'
}}
    width="2712"
    height="2712"
    data-path="assets/topsort-mascot-jumping-full.png"
  />
</div>

<div className="hero-gradient py-12 md:py-20 px-6 md:px-8 rounded-2xl mb-12" style={{ position: 'relative', zIndex: 10 }}>
  <div className="max-w-5xl mx-auto text-center">
    <h1 className="text-4xl md:text-5xl lg:text-6xl font-bold mb-6 no-hyphenate">
      Developer Documentation
    </h1>

    <p className="text-xl md:text-2xl text-gray-600 dark:text-gray-400 mb-10 no-hyphenate no-justify mx-auto lg:whitespace-nowrap">Develop and scale an auction-based advertising platform in your marketplace.</p>

    <div className="flex flex-wrap justify-center gap-4 relative z-10">
      <a href="/en/overview" className="inline-flex items-center px-6 py-3 bg-primary text-white rounded-lg font-medium hover:opacity-90 transition-all whitespace-nowrap">
        Intro to Topsort →
      </a>

      <a href="/en/api-reference/introduction" className="inline-flex items-center px-6 py-3 bg-white dark:bg-[#0b0b10] border border-gray-300 dark:border-gray-700 rounded-lg font-medium transition-all whitespace-nowrap">
        API Reference →
      </a>
    </div>
  </div>
</div>

<h2 style={{ textAlign: "center", width: "100%" }}>
  Two Integration Paths — Mix and Match as Necessary
</h2>

<CardGroup cols={2}>
  <Card title="Low Code" icon="rocket">
    Deals with common use cases and gets you started quickly.

    * [**Import catalog with feeds**](/en/ad-platform/listings/product-feed)
    * [**Embed banners with banners.js**](/en/ad-platform/banners/bannersjs)
    * [**Enrich search results with the proxy**](/en/ad-platform/listings/topsort-proxy)
  </Card>

  <Card title="API Driven" icon="code">
    For bespoke functionality and advanced use cases.

    * [**API Reference**](/en/api-reference/introduction)
    * [**Authentication**](/en/api-reference/authentication)
  </Card>
</CardGroup>

## Try It Out

<p style={{ textAlign: "center" }}>Explore our API with these common workflows.</p>

<Tabs>
  <Tab title="1. Upload a product">
    Upload products to your catalog using the Catalog API.

    <CodeGroup>
      ```bash cURL theme={null}
      curl --request POST \
        --url https://api.topsort.com/v2/products \
        --header 'Authorization: Bearer YOUR_API_KEY' \
        --header 'Content-Type: application/json' \
        --data '{
          "products": [
            {
              "id": "product-123",
              "name": "Example Product",
              "price": 29.99,
              "imageUrl": "https://example.com/product.jpg",
              "category": "electronics"
            }
          ]
        }'
      ```

      ```javascript JavaScript theme={null}
      const response = await fetch("https://api.topsort.com/v2/products", {
        method: "POST",
        headers: {
          Authorization: "Bearer YOUR_API_KEY",
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          products: [
            {
              id: "product-123",
              name: "Example Product",
              price: 29.99,
              imageUrl: "https://example.com/product.jpg",
              category: "electronics",
            },
          ],
        }),
      });

      const data = await response.json();
      console.log(data);
      ```

      ```python Python theme={null}
      import requests

      response = requests.post(
        'https://api.topsort.com/v2/products',
        headers={
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
        },
        json={
          'products': [{
            'id': 'product-123',
            'name': 'Example Product',
            'price': 29.99,
            'imageUrl': 'https://example.com/product.jpg',
            'category': 'electronics'
          }]
        }
      )

      print(response.json())
      ```
    </CodeGroup>
  </Tab>

  <Tab title="2. Create a campaign">
    Create your first advertising campaign.

    <CodeGroup>
      ```bash cURL theme={null}
      curl --request POST \
        --url https://api.topsort.com/v2/campaigns \
        --header 'Authorization: Bearer YOUR_API_KEY' \
        --header 'Content-Type: application/json' \
        --data '{
          "name": "My First Campaign",
          "budget": 1000,
          "type": "sponsored_listings",
          "startDate": "2024-01-01"
        }'
      ```

      ```javascript JavaScript theme={null}
      const response = await fetch("https://api.topsort.com/v2/campaigns", {
        method: "POST",
        headers: {
          Authorization: "Bearer YOUR_API_KEY",
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name: "My First Campaign",
          budget: 1000,
          type: "sponsored_listings",
          startDate: "2024-01-01",
        }),
      });

      const data = await response.json();
      console.log(data);
      ```

      ```python Python theme={null}
      import requests

      response = requests.post(
        'https://api.topsort.com/v2/campaigns',
        headers={
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
        },
        json={
          'name': 'My First Campaign',
          'budget': 1000,
          'type': 'sponsored_listings',
          'startDate': '2024-01-01'
        }
      )

      print(response.json())
      ```
    </CodeGroup>
  </Tab>

  <Tab title="3. Run an auction">
    Request ad placements through the auction system.

    <CodeGroup>
      ```bash cURL theme={null}
      curl --request POST \
        --url https://api.topsort.com/v2/auctions \
        --header 'Authorization: Bearer YOUR_API_KEY' \
        --header 'Content-Type: application/json' \
        --data '{
          "slots": 3,
          "products": {
            "ids": ["product-123", "product-456"]
          },
          "category": {
            "id": "electronics"
          }
        }'
      ```

      ```javascript JavaScript theme={null}
      const response = await fetch("https://api.topsort.com/v2/auctions", {
        method: "POST",
        headers: {
          Authorization: "Bearer YOUR_API_KEY",
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          slots: 3,
          products: {
            ids: ["product-123", "product-456"],
          },
          category: {
            id: "electronics",
          },
        }),
      });

      const data = await response.json();
      console.log(data);
      ```

      ```python Python theme={null}
      import requests

      response = requests.post(
        'https://api.topsort.com/v2/auctions',
        headers={
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
        },
        json={
          'slots': 3,
          'products': {
            'ids': ['product-123', 'product-456']
          },
          'category': {
            'id': 'electronics'
          }
        }
      )

      print(response.json())
      ```
    </CodeGroup>
  </Tab>

  <Tab title="4. Track events">
    Track user interactions and conversions.

    <CodeGroup>
      ```bash cURL theme={null}
      curl --request POST \
        --url https://api.topsort.com/v2/events \
        --header 'Authorization: Bearer YOUR_API_KEY' \
        --header 'Content-Type: application/json' \
        --data '{
          "events": [
            {
              "type": "click",
              "productId": "product-123",
              "resolvedBidId": "bid-456",
              "occurredAt": "2024-10-12T17:30:00Z"
            }
          ]
        }'
      ```

      ```javascript JavaScript theme={null}
      const response = await fetch("https://api.topsort.com/v2/events", {
        method: "POST",
        headers: {
          Authorization: "Bearer YOUR_API_KEY",
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          events: [
            {
              type: "click",
              productId: "product-123",
              resolvedBidId: "bid-456",
              occurredAt: new Date().toISOString(),
            },
          ],
        }),
      });

      const data = await response.json();
      console.log(data);
      ```

      ```python Python theme={null}
      import requests
      from datetime import datetime

      response = requests.post(
        'https://api.topsort.com/v2/events',
        headers={
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
        },
        json={
          'events': [{
            'type': 'click',
            'productId': 'product-123',
            'resolvedBidId': 'bid-456',
            'occurredAt': datetime.utcnow().isoformat() + 'Z'
          }]
        }
      )

      print(response.json())
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Our Products

<p style={{ textAlign: "center" }}>Explore Topsort's core components designed to power your retail media business:</p>

<CardGroup cols={2}>
  <Card title="Ad Platform" icon="rectangle-ad" href="/en/knowledge-base/ad-platform">
    Comprehensive solution for launching and managing your advertising business with campaigns, reports, and integrations.
  </Card>

  <Card title="Ad Server" icon="server" href="/en/knowledge-base/ad-server">
    Powerful APIs for customizing ads and integrating with existing systems.
    Control relevance, targeting, and performance.
  </Card>

  <Card title="Ad Intelligence" icon="brain" href="/en/knowledge-base/ad-intelligence">
    Smart tools for forecasting, retrieval, and attribution to enhance your ad
    system with AI-powered insights.
  </Card>

  <Card title="Toppie" icon="chart-network" href="/en/knowledge-base/toppie">
    DSP for advertising agencies and brands to manage campaigns across multiple retailers with real-time data.
  </Card>
</CardGroup>

## Client Libraries

<p style={{ textAlign: "center" }}>We provide client libraries to help you get started quickly:</p>

<CardGroup cols={3}>
  <Card title="Topsort.js" icon="js" href="/en/knowledge-base/ad-platform">
    Client-side JavaScript SDK
  </Card>

  <Card title="Analytics.js" icon="js" href="/en/ad-platform/sdks/javascript-sdk">
    Analytics tracking library
  </Card>

  <Card title="Topsort.kt" icon="android" href="/en/ad-platform/sdks/android">
    Kotlin SDK for Android
  </Card>

  <Card title="PHP SDK" icon="php" href="/en/ad-platform/sdks/topsort-php">
    Server-side PHP library
  </Card>

  <Card title="Banners.js" icon="js" href="/en/ad-platform/banners/bannersjs">
    Banner ad integration library
  </Card>

  <Card title="Topsort.swift" icon="apple" href="/en/ad-platform/sdks/ios">
    Swift SDK for iOS
  </Card>
</CardGroup>

## Learn More

<p style={{ textAlign: "center" }}>Not sure where to begin? Learn about the fundamental components:</p>

<CardGroup cols={2}>
  <Card title="The Catalog" icon="database" href="/en/ad-server/catalog/">
    Manage your product inventory
  </Card>

  <Card title="Banners" icon="rectangle-ad" href="/en/knowledge-base/ad-platform/banners">
    Create and manage banner campaigns
  </Card>

  <Card title="Listings" icon="list" href="/en/knowledge-base/ad-platform/listings">
    Sponsored product listings
  </Card>

  <Card title="Auctions" icon="gavel" href="/en/knowledge-base/ad-server/auctions">
    Understand auction mechanics
  </Card>

  <Card title="Events" icon="chart-line" href="/en/api-reference/events/">
    Track impressions and conversions
  </Card>
</CardGroup>