Pre-bid API Reference

The Pre-bid binary exposes a small HTTP/1.1 API. There are two endpoints: one for lookups, one for health checks. Both speak plain HTTP and respond with JSON (lookup) or a status code (health check).

The binary runs locally on your bidder host. The base URL is whatever address and port the binary is bound to — typically http://localhost:9898. The examples below use that default.

Authentication

Every lookup request must include an API key in the k query parameter. Your Pinokio account manager will provide the key.

There is no header-based authentication and no token refresh. The key is configured into the binary and into your bidder; rotation happens out of band.

Request constraints

A few rules apply to every lookup:

The total request size must not exceed 8 KB.
The request URL and all parameter names must be lowercase.
All parameter values must be URL-encoded.
Parameter values must not contain any of: #, @, =, ;.
Data passed in Pre-bid lookups should match what you pass to Post-bid for the same impression — that is what lets us close the loop between the two.

`GET /api/v1/ivt/lookup`

Submits a bid request for prediction. Returns a JSON payload that your bidder can use to decide whether to drop the bid, log it for review, or proceed normally.

Schain in the path

The supply chain is passed as a path segment, not a query parameter. The format mirrors the OpenRTB schain string:

/api/v1/ivt/lookup?schain=<version>,<complete>!<node>!<node>!...

Each node is comma-delimited: asi,sid,hp,rid,name,domain. Nodes are separated with !. Example:

schain=1.0,1!rtbmarket.net,742934582496,1,bid-request-815715,publisher,mobilepub.net!adbridge.io,633,1,bid-request550974,intermediary,sspbridge.com

The query string follows the ? after the schain segment.

Query parameters

Most parameter names match the equivalent Post-bid parameters so you can populate both from the same source. The full list:

Parameter	Required	Description
`p`	Yes	Pinokio Partner ID (UUID). Identifies your account.
`k`	Yes	API key.
`pub`	Yes	Publisher ID — same value as field #2 in the `ads.txt`.
`node`	Yes	Bidder or prebid instance / server identifier.
`ip`	Yes	Client IP address.
`ua`	Yes	User agent string (URL-encoded).
`uid`	Yes	Unique user identifier — cookie ID on web, IFA on mobile/CTV.
`ifa`	Conditional	Device IFA (IDFA / AAID). Required on mobile and CTV.
`app`	Conditional	App ID / bundle ID. Required for in-app and CTV traffic. Case-sensitive.
`sid`	Yes	Supplier ID — domain of the supplier/exchange. Matches field #1 in `ads.txt`.
`adt`	Yes	Ad type. Integer: `1` Banner, `2` Video, `3` Audio, `4` Native.
`dvt`	Yes	Device type. See device type values.
`rat`	No	Rendered ad type. See rendered ad type values.
`adv`	No	Advertiser ID.
`plc`	No	Placement ID.
`cre`	No	Creative ID.
`cb`	No	Cache buster — random value to force tag reload.
`dim`	No	Creative dimensions, format `{Width}x{Height}`.
`aid`	No	Ad ID — unique identifier for the creative.
`geo`	No	Two-letter ISO country code.
`p1`–`p5`	No	Custom reporting dimensions. Not unique per request — used for grouping in reports.

http://localhost:9898/api/v1/ivt/lookup
  ?schain=1.0,1!rtbmarket.net,742934582496,1,bid-request-815715,publisher,mobilepub.net
         !adbridge.io,633,1,bid-request550974,intermediary,sspbridge.com
  ?p=1b6c4502-dfef-4875-b2e9-4d1abb7f039a
  &k=rePVI7t
  &node=US-worker-1
  &pub=1
  &ua=Mozilla%2F5.0%20%28Linux%3B%20Android%2012%3B%20SM-A525F%29%20AppleWebKit%2F537.36
  &ip=34.147.173.143
  &uid={UID}
  &ifa=204787CA-13E7-44EA-BAC6-3AABBE993565
  &app=1712942862
  &rid=6711-a5741770-00b1-4fb7-9a8a-0c3fc6d5cf7a
  &sid=supplyhub.com
  &adt=3
  &dvt=4
  &rat=2
  &adv=9230
  &plc=1712942862-414x896
  &cre=vXM93TtEu1nv5Z%2FgrRJTyCJ%2FMNjQ
  &cb=SlN8FgEn6z
  &dim=414x896
  &aid=vXM93TtEu1nv5Z%2FgrRJTyCJ%2FMNjQ
  &geo=JP
  &p1=97451
  &p2=8930
  &p3=shop_Banner_GB
  &p4=1107

curl -s "http://localhost:9898/api/v1/ivt/lookup\
?schain=1.0,1!rtbmarket.net,742934582496,1,bid-request-815715,publisher,mobilepub.net!adbridge.io,633,1,bid-request550974,intermediary,sspbridge.com\
?p=1b6c4502-dfef-4875-b2e9-4d1abb7f039a\
&k=rePVI7t\
&node=US-worker-1\
&pub=1\
&ip=34.147.173.143\
&ua=Mozilla%2F5.0%20%28Linux%3B%20Android%2012%29\
&uid=abc123\
&ifa=204787CA-13E7-44EA-BAC6-3AABBE993565\
&app=1712942862\
&sid=supplyhub.com\
&adt=3&dvt=4&rat=2\
&dim=414x896&geo=JP"

Response

The response is a JSON object with four top-level sections. Example:

{
  "ipReputation": {
    "ipBotActivity": false,
    "ipHosting": false,
    "ipVpn": false
  },
  "botRisk": {
    "score": 0.30000000000000004,
    "band": "low",
    "confidence": 1
  },
  "components": {
    "p_hard": 0.3,
    "p_givt": 0,
    "p_sivt": 0,
    "p_hist": 0
  },
  "uaValid": false,
  "schain": {
    "valid": true,
    "verified": true,
    "complete": 1
  }
}

`botRisk`

The headline bot prediction.

Field	Type	Description
`score`	number	Combined risk prediction, `0.0`–`1.0`. Higher means higher likelihood of invalid traffic.
`band`	string	Bucketed risk level: `low`, `medium`, or `high`. Most bidders use this as the primary signal.
`confidence`	number	How confident the model is in the prediction. `0` means there is not enough data yet to be confident; higher means more confidence.

`components`

The individual probabilities that feed into botRisk.score. Useful for debugging and for custom bidding logic that wants to weight categories differently.

Field	Description
`p_hard`	Probability based on hard signals (deterministic flags — known-bad IFAs, malformed UAs, etc.).
`p_givt`	Probability of General Invalid Traffic — automated, declared, easily detectable.
`p_sivt`	Probability of Sophisticated Invalid Traffic — bots that mimic human behavior.
`p_hist`	Probability based on historical patterns for this user / device / source.

`ipReputation`

Three boolean flags about the request IP.

Field	Description
`ipBotActivity`	The IP is frequently seen recently to be used by bots.
`ipHosting`	The IP belongs to a hosting / datacenter range, not residential.
`ipVpn`	The IP is a known VPN exit node.

`uaValid`

Boolean. false indicates the user agent is malformed, spoofed, or otherwise inconsistent with the rest of the request signals.

`schain`

The result of validating the schain string passed in the path.

Field	Description
`valid`	The string parsed without errors.
`verified`	Every node in the chain matched our records.
`complete`	The `complete` flag from the schain string itself (`1` or `0`).

HTTP status codes

Code	Meaning
`200`	Lookup succeeded. Body contains the JSON above.
`400`	Bad request — usually a missing required parameter or a forbidden character.
`401`	API key missing or invalid.
`413`	Request too large (over 8 KB).
`503`	Binary cannot serve lookups — see Troubleshooting.

`GET /health-check`

Lightweight endpoint for monitoring. Returns no body — only a status code.

Code	Meaning
`200`	Binary is healthy.
`503`	Binary is up but cannot serve lookups.

curl -i http://localhost:9898/health-check

We recommend polling this once every 10 seconds to once per minute from your monitoring system.

Reference tables

Device type values

Used by dvt. Aligned with OpenRTB 2.6 / AdCOM 1.0.

Value	Meaning
`1`	Mobile / tablet (legacy combined category)
`2`	Personal computer (desktop / laptop)
`3`	Connected TV
`4`	Phone
`5`	Tablet
`6`	Connected device (Roku, Apple TV, Fire TV, consoles)
`7`	Set-top box
`8`	Digital out-of-home (DOOH)

Rendered ad type values

Used by rat. Interpretation depends on the media type (adt).

Value	Display	Video	Audio	Native
`0`	Unknown	Unknown	Unknown	Unknown
`1`	Rich media	—	—	Rich media
`2`	Static	—	—	Static
`3`	—	Skippable in-stream	Skippable in-stream	—
`4`	—	Non-skippable in-stream	Non-skippable in-stream	—
`5`	—	Video discovery	—	—
`6`	—	Bumper	—	—
`7`	—	Outstream	—	—
`8`	—	Masthead	—	—

For example, a rich-media display unit is adt=1, rat=1. A non-skippable in-stream video is adt=2, rat=4.