API Integration

For environments where JavaScript script tags don't work, or when you need full control over how ads look.

When to use the API instead of scripts:
  • Chrome extensions (can't inject third-party scripts)
  • Mobile apps or Electron apps
  • Server-side rendered pages where you want the ad in the initial HTML
  • Custom ad templates that don't match our banner/card formats
  • Environments with strict Content Security Policies

For most websites, the script integration is simpler and includes viewability verification. Use the API when scripts aren't an option.

1. Create a placement

Create a placement in the dashboard. Copy the placement ID.

2. Call the serve endpoint

curl https://adventory.to/api/ad/serve?p=YOUR_PLACEMENT_ID

The response looks like this:

{
  "ad": {
    "title": "Acme Dev Tools",
    "description": "Ship faster with Acme.",
    "image": "https://adventory.to/creatives/acme.png",
    "click_url": "https://adventory.to/c/abc123",
    "impression_url": "https://adventory.to/i/abc123"
  }
}

3. Render the ad yourself

Use the returned fields to build your own ad UI. Link the ad to click_url so clicks are tracked.

4. Fire the impression pixel

When the ad becomes visible, fire the impression_url. You can load it as an image or call it with fetch:

// As an image
const img = new Image();
img.src = ad.impression_url;

// Or with fetch
fetch(ad.impression_url);
For server-side calls, pass ip, ua, and country query params so we can serve geo-targeted ads and filter bots.

Next steps