Bid Endpoint§

One GET per impression opportunity. We answer with the ad that won the auction, or with 204 when nothing bid.

GET /v1/feed/{feed_key} HTTP/1.1
Host: dsp.xml.adon3.com
Accept: application/json
Accept-Encoding: gzip

{feed_key} identifies your supply endpoint and its supply type. POST is not supported. Every parameter below is a query parameter and must be URL-encoded.

Parameter names and enumerated values on this page are provisional while version 1.0 is finalised. Confirm anything you are about to hard-code with the adon3 integration office.

Required parameters§

We reject a call with 400 when either is missing. A truncated or synthesised user agent is worse than useless, because it passes validation and then loses you the targeting that pays best.

Identification§

subid is the dimension every report breaks down by, so a scheme you can still read six months from now is worth ten minutes today. Sending one subid for all traffic works, and tells you nothing.

Accepted aliases§

Two fields have a second spelling, and both have been accepted since this endpoint launched. If you are already integrated on the short form, keep it — it is not deprecated and nothing about it will change.

Endpoints we issued before September 2026 carry ref and kw; newer ones carry referrer and keyword. They behave identically — we simply publish the longer names now because they are the ones documented here.

subscription_age is also read, and takes precedence over sub_age when you send both. Send one.

Parameter names are case-sensitive and lower case. Referrer or KW are read as unknown parameters and ignored, which looks exactly like sending nothing.

Context and targeting§

Setting n above 1 is only useful when you have somewhere to show the extras. Requesting five ads and showing one depresses your fill quality score.

Pop parameters§

Accepted only on feed keys whose supply type is pop.

Push parameters§

Accepted only on feed keys whose supply type is push. On any other key they return 403.

If you cannot render an image at the size you asked for, ask for the size you can render. We select creatives against these values, and a mismatch shows up as a low click-through rate rather than as an error.

Direct link parameters§

Accepted only on feed keys whose supply type is direct link. On any other key they return 403.

redirect_url does two jobs. It is forwarded to the buyer unchanged — several direct link buyers require it and will not bid without one, so sending it raises your fill rate on this supply type. And in redirect mode it is where we send the visitor when the auction returns nothing, so a no fill lands them somewhere of your choosing rather than on a blank tab.

Both appear pre-filled on the endpoint we issue you, redirect set to 1 and redirect_url left as a macro. Substitute it, or delete the parameter if you have nothing to send — an unsubstituted {redirect_url} is treated as absent rather than rejected, so a partly filled URL still works.

Redirect mode§

A direct link is the navigation itself: somebody pressed something and is waiting on a blank tab while you decide where to send them. redirect=1 lets you put this endpoint in front of them directly, with nothing to parse and no code on your side.

curl -sSi -G 'https://dsp.xml.adon3.com/v1/feed/{feed_key}' \
  --data-urlencode 'ip=203.0.113.44' \
  --data-urlencode 'ua=Mozilla/5.0 (Linux; Android 14; Pixel 8) AppleWebKit/537.36' \
  --data-urlencode 'subid=zone-4471' \
  --data-urlencode 'redirect=1' \
  --data-urlencode 'redirect_url=https://your-site.example/backfill'

HTTP/1.1 302 Found
Location: https://dsp.xml.adon3.com/track/click/...
Cache-Control: no-store, no-cache, must-revalidate
Referrer-Policy: no-referrer

Three things follow from there being no body:

• The impression is counted for you. Normally you fire imp_url yourself; a 302 has nowhere to carry it, so we fire it server-side before redirecting. Your counts match either way.
• format cannot be set. There is no body to encode, so redirect=1 with format=xml returns 403 rather than quietly ignoring one of them.
• A no fill sends them to your redirect_url. There is a person waiting on a blank tab, so a 204 would be the right answer to a parser and the wrong one to them. Send no redirect_url and a no fill is a 204 as usual — we will not invent a destination. Outside redirect mode nothing changes: you get the 204 and run your own fallback, which stays your decision.
• Coded errors are never redirected. A 400, 401 or 403 is an integration mistake, and hiding it behind a redirect is how a partner spends a week sending traffic that never had a chance of filling.

The redirect is 302, never 301. The destination is decided per visit, and a permanent redirect would be cached by the browser and by every proxy in between, so the first creative a visitor saw would become the only one that link ever went to.

Client hints§

Modern browsers reduce the user agent, so send the hints when you have them. Each maps to the header of the same name.

Response control§

A complete request§

curl -sS -G 'https://dsp.xml.adon3.com/v1/feed/9862b397ba3320149b94a05079597eb3' \
  --compressed \
  --data-urlencode 'ip=203.0.113.44' \
  --data-urlencode 'ua=Mozilla/5.0 (Linux; Android 14; Pixel 8) AppleWebKit/537.36' \
  --data-urlencode 'subid=zone-4471' \
  --data-urlencode 'rid=8f2a1c30-6b4e-4d9a-9f11-2c7e3b5a8d40' \
  --data-urlencode 'uid=3d9f7a2b6c1e' \
  --data-urlencode 'referrer=https://gazette.example.com/markets/open-exchange' \
  --data-urlencode 'lang=en-US' \
  --data-urlencode 'cat=IAB13' \
  --data-urlencode 'ch_platform=Android' \
  --data-urlencode 'ch_mobile=1' \
  --data-urlencode 'n=1'

Status codes§

Full bodies and error codes are on Status & Errors.

Next: Response Formats.