Documentation
Serving API reference
This is the surface that exists today: the one that serves ads and collects what happens to them. It is not a management API, and the difference matters enough to say in the first line.
Endpoints
All of them answer on the same origin the tag was loaded from.
| Endpoint | What it is for | What authorises it |
|---|---|---|
| GET /tag.js | The tag a publisher embeds in their page. | Nothing. It is a public static file. |
| GET /a | An ad request for every slot on a page, in one call. | A placement token, which identifies inventory rather than an account. |
| GET /a/{placement_token} | An ad request for a single placement. | A placement token, which identifies inventory rather than an account. |
| POST /b/i | The viewability beacon. This is what produces the billable impression. | A server-signed token, single-use and expiring. |
| GET /c/{token} | The click redirect. One plain 302, no HTML and no interstitial. | A server-signed token, single-use and expiring. |
| GET /reports | Public ad reporting, with no account and no session. | The served ad's own signed impression token, which expires. |
| POST /reports | The submission behind that form. A browser is redirected to the confirmation; any other caller is answered with the report id. | The same signed impression token, posted with the report. No account and no API key, and submissions are rate-limited per network. |
| GET /reports/{id} | The confirmation for a filed report: its id, its review status and when it arrived. JSON by default, and a page to a browser. | The report id. Nothing else is needed, which is why the answer carries nothing about whoever filed it. |
| GET /pb/{token} | The server-to-server conversion receiver. | An HMAC-SHA256 computed with your shared secret. |
How each call is authorised
Almost none of these calls carries a credential. What authorises them is a signed token that expires and is consumed.
- The placement token identifies one specific slot. It is not a secret: it identifies inventory, not an account.
- The beacon and the click redirect carry a token the server signed with HMAC. The signature is the whole of its authorisation, and the token expires after an hour.
- The postback receiver is authorised by an HMAC-SHA256 computed with your shared secret, which never travels over the wire.
- Click and impression tokens are single-use. A repeated token is a replay and is treated as one, without the response revealing anything to whoever repeated it.