Requesting an ad
GET /api/v1/serve/ad is the one call every SDK makes to get a decision. There is no format/width/height/device parameter — those live on the pre-configured slot.
Query parameters
| Name | Type | Required | Notes |
|---|---|---|---|
api_key | string | Required | Publisher-site key, opaque, pk_ prefix. Public — safe to embed in a shipped client. |
slot_id | UUID | one of slot_id/slot_name | The ad unit id. Prefer this over slot_name. |
slot_name | string | one of slot_id/slot_name | Resolves the most-recently-created active slot with this name. |
page_url | string | Optional | Current page/screen URL, for contextual targeting + brand safety. Must be byte-percent-encoded — see WAF-safe encoding. |
page_keywords | string | Optional | Comma-separated keywords. Must be byte-percent-encoded. |
us_privacy | string | Optional | IAB US Privacy (CCPA) string. Must be byte-percent-encoded. |
euconsent_v2 | string | Optional | IAB TCF v2 consent string (base64). Must be byte-percent-encoded. |
Device and geo signals are derived server-side from the User-Agent header and the client IP — there is nothing to pass for them.
Required headers
| Name | Type | Required | Notes |
|---|---|---|---|
User-Agent | string | Required | An explicit SDK UA — see User-Agent rules. Default HTTP-client UAs (okhttp, python-requests, Java/…) are on the bot blocklist and cause silent no-fill. |
Accept | string | Required | application/json |
Example request
bash
curl "https://api.adx.theaimart.co/api/v1/serve/ad?api_key=pk_...&slot_id=8b1f2c3d-....-uuid" \
-H "User-Agent: theaimart-adx-node/1.0.0" \
-H "Accept: application/json"Server-side identity cookie
The response may include Set-Cookie: _an_id=…. This stabilizes the per-user identity used for frequency capping, retargeting and the attention dividend.
- Browser / mobile clients with a cookie jar should persist and resend it automatically — most HTTP clients (and the Web SDK's
credentials: 'include'fetch) do this for free. - Server-side SDKs (Python, Node, Rust) proxying requests for many different end users must forward each user's own identity cookie and must never share one cookie across users — doing so merges distinct users into one identity server-side.
Forward the real end user, not the server
If you are proxying an ad request on behalf of an end user (any server-side SDK), you must forward that user's realUser-Agent and IP (via X-Forwarded-For) — not your server's. Otherwise every impression looks like one device from one datacenter IP and gets fraud-scored to a no-fill. Both the Python and Node SDKs expose userAgent/clientIp per-request overrides for exactly this.