Developer Reference

API Documentation

Complete reference for the AdsByVirtue ad serving API. Serve halal-compliant display ads, track clicks, and manage sessions.

Getting Started

Base URL

https://adsbyvirtue.netlify.app/api

Authentication

Ad serving requires an API key passed as a query parameter. Generate API keys from your publisher dashboard.

Navigate to Publisher Dashboard → Sites

Click Generate API Key for your registered site

Use the key as the key query parameter

Rate Limits

Endpoint	Limit
Ad serving	1,000 req/min per IP
Auth endpoints	10 attempts/15 min per IP
General API	100 req/min per IP

Ad Tag Integration

Include the ad tag script on your page and add a container with your API key:

<script src="https://adsbyvirtue.netlify.app/ad-tag.js" async></script>
<div
  id="my-ad-slot"
  data-abv-key="sk_live_your_key_here"
  data-abv-format="300x250"
></div>

Endpoints

3 endpoints available.

POST/api/auth/refresh

Refresh the current session. Rotates the refresh token and returns a new access token.

Authentication

Session cookie (automatic)

Response

200: { success: true } · 401: { error: string }

Example

curl -X POST https://adsbyvirtue.netlify.app/api/auth/refresh \
  -H "Cookie: sb-access-token=..."

GET/api/ads/serve

Serve a halal-compliant ad. Returns a JSON object with ad creative data. Includes bot detection and IP rate limiting (10 req/min/IP).

Authentication

API Key (query parameter: key)

Parameters

keystringrequired

Publisher API key

urlstring

Page URL where the ad will be displayed

formatstring

Preferred ad format: 728x90, 300x250, 160x600, native, interstitial

Response

200: { ad: { id, title, image_url, destination_url, ad_text, cta_text, ad_format }, impression_id, session_id }

Example

curl "https://adsbyvirtue.netlify.app/api/ads/serve?key=sk_live_xxx&url=https://example.com/blog"

GET/api/ads/click

Track an ad click and redirect to the destination URL with UTM parameters. Validates prior impression and enforces click rate limits.

Authentication

None (public endpoint)

Parameters

ad_iduuidrequired

The ad ID from the serve response

session_iduuid

Session ID from the serve response

Response

302: Redirects to destination_url · 400: Missing ad_id · 403: No impression / suspicious · 404: Ad not found

Example

curl -L "https://adsbyvirtue.netlify.app/api/ads/click?ad_id=abc-123&session_id=def-456"

Ready to integrate?

Generate an API key from your publisher dashboard to get started.

Get API key Back to home