Ad Request API
The ad-serving engine endpoints are prefixed with /ad, require no authentication, and are used by the SDK / zones on a page to request ads in real time. In production they're typically accessed via js.adbnk.co (SDK) and the main domain.
Before requesting, create a zone in the publisher console and get its zone_key (of the form zone_ab12cd34); see Publisher API · Zones.
Request an ad
GET /ad/request or POST /ad/request
One of zone_id or zone is required.
| Param | Type | Required | Description |
|---|---|---|---|
zone_id | int | Yes* | Zone numeric ID |
zone | string | Yes* | Zone code zone_key (one of, with zone_id) |
limit | int | No | Number of ads to return, default 1 |
page_url | string | No | URL of the page hosting the ad (content targeting; defaults to Referer) |
page_title | string | No | Page title |
page_keywords | string | No | Page keywords |
page_category | string | No | Page category |
page_type | string | No | Page type (article/video/product, etc.) |
page_tags | string | No | Page tags, comma-separated |
page_lang | string | No | Page language |
_v | int | No | Protocol version; 2+ enables the obfuscated/signed protocol |
_d | string | No | Obfuscated device-fingerprint data under the v2 protocol |
A path form is also supported: GET /ad/request/{zone_id} (matched by zone_key or its numeric part).
curl "https://api.adbnk.co/ad/request?zone=zone_ab12cd34&limit=1&page_url=https%3A%2F%2Fblog.example.com%2Fpost%2F1"Response structure
{
"code": 0,
"message": "success",
"data": {
"request_id": "20260710120000a1b2c3d4e5f6a7b8",
"zone": {
"id": 5,
"code": "zone_ab12cd34",
"width": 300,
"height": 250,
"type": "BANNER",
"refresh": 0
},
"ads": [
{
"id": "q1w2e3r4t5y6...",
"type": "IMAGE",
"title": "Summer Sale",
"description": "Up to 50% off",
"button_text": "Shop Now",
"brand_name": "Example Shop",
"image_url": "https://cdn.adbnk.co/creatives/1.jpg",
"video_url": null,
"icon_url": null,
"landing_url": "https://track.adbnk.co/track/click/q1w2e3r4t5y6...",
"click_url": "https://track.adbnk.co/track/click/q1w2e3r4t5y6...",
"impression_url": "https://track.adbnk.co/track/impression/q1w2e3r4t5y6...",
"width": 300,
"height": 250,
"pricing_model": "CPC",
"html": "<!DOCTYPE html>...<span class=\"ad-badge\">AD</span>..."
}
],
"qa_k": "…",
"_rand": "…",
"_ts": 1752200000,
"_v": 2
},
"timestamp": 1752200000
}When no ad is available, data.ads is an empty array and message is "No ad available".
Creative structure
Each item in ads[] is a displayable creative:
| Field | Type | Description |
|---|---|---|
id | string | Tracking ID (track_id), an encrypted envelope of request/creative/ad/zone/bid info |
type | string | Creative type: IMAGE/NATIVE/VIDEO/RICH_MEDIA, etc. |
title / description | string | Headline / description copy |
button_text | string | Call-to-action button text (CTA) |
brand_name | string | Brand name |
image_url / image_url_2 | string | Image URL |
video_url | string | Video URL |
icon_url | string | Icon URL |
display_url | string | Display URL |
landing_url / click_url | string | Click-tracking URL (pointing to track.adbnk.co) |
impression_url | string | Impression-tracking pixel URL |
width / height | int | Creative size |
pricing_model | string | Effective pricing model |
html | string | Fully server-rendered ad HTML, usable directly in iframe.srcdoc |
html_content | string | Rich-media (RICH_MEDIA) template render content (when present) |
Impression and click tracking
The SDK doesn't need to assemble tracking URLs itself: just use the returned impression_url (request on impression) and click_url (redirect on click) — both embed the encrypted track_id. If you render the html field directly, the impression pixel is already injected. See Events & Conversion Reporting for reporting details.
For special zone types, the zone object carries extra config:
POPUP/FLOAT/INTERSTITIAL:trigger(trigger method),frequency(frequency cap),popup(popup behavior).COUPLET(couplet):couplet(min screen width, offset, close button, etc.).REWARDED:rewarded(watch duration, skippable time, reward amount/type).EXIT_INTENT:frequency.
Ad rendering (iframe embed)
GET /ad/render/{zone_id}
Returns an embeddable ad HTML document directly, suitable for <iframe src> inclusion with no frontend JSON handling.
<iframe src="https://api.adbnk.co/ad/render/5"
width="300" height="250" frameborder="0" scrolling="no"></iframe>VAST video ads
GET /ad/render/vast/{zone_id}
Returns VAST 2.0 / 4.2 XML for VAST-capable video players to load video pre-roll ads.
curl "https://api.adbnk.co/ad/render/vast/5"Rewarded ad SSV
Rewarded video provides server-side reward verification (SSV) endpoints under /ad/reward/* (e.g. /ad/reward/token, /ad/reward/verify, /ad/reward/keys, /ad/reward/ssv-callback). Integration follows the console's "Rewarded Ads" config and the SDK docs.