Calling GET /api/v1/serve
A single GET request returns a matched native ad in around 50ms — with far more request and response detail than headline/body/image.
Authentication
Pass your API key in the X-Adscod-Key header (preferred), or as a publisherKey query parameter if a header isn't practical for your integration.
The request
Send a GET request to /api/v1/serve with source=publisher, your key, and as much placement context as you have: placementId, country, device (MOBILE, DESKTOP, or TABLET), category, an intent/query hint via q, and limit if you want more than one ad back (default 1, max 10 — useful for a product carousel placement).
What you get back
Each returned ad includes far more than a headline and image: title, body, imageUrl, ctaLabel, clickUrl and clickToken, cpcUsd, a human-readable matchContext explaining why it matched, optional adPrice/adCompareAtPrice/adCurrency, brand identity (brandName, brandLogoUrl, brandVerified), and an optional products[] array for shopping-feed campaigns.
$ curl -s https://api.adscod.com/v1/serve \-H 'X-Adscod-Key: adc_••••'-H 'country: NG'-H 'category: food-drink'-d 'placementId=p_123'
Brand, price, CTA and match reason — render with your own markup.
No-fill and backfill
If no paid campaign is eligible, the engine automatically backfills the slot with an Adscod house ad rather than leaving it empty — a genuinely empty ads: [] response is rarer than "no ad matched" alone, and also happens if your embedding domain has been blocked.
Response time
Matching and fraud pre-checks happen server-side and target under 50ms, so the call can sit inline in your page or app render path without a noticeable delay — this is a performance target the engine is built to, not a hard guarantee on every request.
Handling clicks
- Always use the click-tracking URL returned in the response — don't link directly to the advertiser's destination
- Argus screens the click for fraud when the tracking URL is hit, before billing the advertiser and crediting you
- Fraud-flagged clicks are excluded from your earnings automatically
- CPM campaigns are billed differently — on the separate /api/v1/dwell viewability beacon rather than at serve time — see Rendering native ad formats
Rate limits and caching
Don't cache responses across different visitors — each call is matched to that specific request's context. The endpoint applies both a per-IP and a per-key rate limit; if you're consistently hitting limits at real scale, contact support rather than working around it client-side.