RTB Integration

Send OpenRTB 2.5 bid requests to Praevis and receive winning VAST or display creatives.

Endpoint: POST https://rtb.praevis.com/rtb

Authentication

Find your API key in the dashboard under Supply → your supply source (Publisher) → API Key.

We support two authentication methods. Both are equally secure — use whichever your platform supports.

Method A: API Key in Header (preferred)

X-API-Key: YOUR_API_KEY
Content-Type: application/json

Method B: API Key in Request Body

For third-party aggregators and platforms that cannot set custom HTTP headers, place the API key in the OpenRTB publisher.ext field. No X-API-Key header needed.

For web/display traffic — use site.publisher.ext.api_key:

{
  "site": {
    "publisher": {
      "id": "YOUR_PUBLISHER_ID",
      "ext": {
        "api_key": "YOUR_API_KEY"
      }
    }
  }
}

For mobile/CTV traffic — use app.publisher.ext.api_key:

{
  "app": {
    "publisher": {
      "id": "YOUR_PUBLISHER_ID",
      "ext": {
        "api_key": "YOUR_API_KEY"
      }
    }
  }
}

The exchange checks for the API key in this order: X-API-Key header → site.publisher.ext.api_key → app.publisher.ext.api_key. The first valid key found is used.

Bid request structure

Minimum viable request (CTV video)

{
  "id": "unique-request-id",
  "imp": [{
    "id": "1",
    "video": {
      "mimes": ["video/mp4"],
      "minduration": 6,
      "maxduration": 30,
      "protocols": [2, 3],
      "w": 1920,
      "h": 1080,
      "placement": 1
    },
    "bidfloor": 0.50,
    "bidfloorcur": "USD"
  }],
  "app": {
    "bundle": "com.example.ctv",
    "name": "Example CTV",
    "publisher": { "id": "YOUR_PUBLISHER_ID" }
  },
  "device": {
    "ua": "Mozilla/5.0 ...",
    "ip": "1.2.3.4",
    "devicetype": 3
  }
}

With full content metadata

{
  "id": "req-001",
  "imp": [{ "id": "1", "video": { ... }, "bidfloor": 1.00, "bidfloorcur": "USD" }],
  "app": {
    "bundle": "com.example.ctv",
    "name": "Drama Streaming",
    "publisher": { "id": "YOUR_PUBLISHER_ID" },
    "content": {
      "id": "ep-456",
      "title": "Episode 3 — The Return",
      "series": "Dark Shadows",
      "season": "2",
      "episode": 3,
      "genre": "drama",
      "len": 2700,
      "livestream": 0,
      "cat": ["IAB1", "IAB1-7"]
    }
  },
  "device": {
    "ua": "SmartTV/1.0",
    "ip": "87.50.1.100",
    "geo": { "country": "GBR", "region": "ENG", "city": "London" },
    "devicetype": 3,
    "make": "Samsung",
    "model": "Smart TV 2022"
  }
}

Key fields reference

`imp` object

Field	Required	Description
`imp[].id`	✓	Impression ID
`imp[].video`	✓ (video)	Video object
`imp[].banner`	✓ (display)	Banner object
`imp[].bidfloor`	recommended	Floor price in USD CPM
`imp[].bidfloorcur`	recommended	Always `"USD"`
`imp[].secure`	recommended	`1` = HTTPS required

`video` object

Field	Required	Description
`mimes`	✓	`["video/mp4"]`
`minduration`	✓	Minimum ad length (seconds)
`maxduration`	✓	Maximum ad length (seconds)
`protocols`	✓	`[2, 3]` = VAST 2/3
`w` / `h`	✓	Player dimensions
`placement`	recommended	`1` = in-stream, `2` = in-banner
`linearity`	recommended	`1` = linear

`device` object

Field	Description
`ua`	User agent string
`ip`	Viewer IP (IPv4 or IPv6)
`devicetype`	`1`=mobile, `2`=PC, `3`=CTV, `4`=phone, `5`=tablet, `6`=connected device
`ifa`	Advertising ID (IDFA/GAID)
`lmt`	`1` = limit ad tracking
`geo.country`	ISO 3166-1 alpha-3 (e.g. `"GBR"`)

`app` object (mobile / CTV)

Field	Description
`bundle`	Bundle ID: `com.example.app`
`storeurl`	App store URL
`publisher.id`	Your Praevis Publisher ID
`content`	Content metadata (see below)

`site` object (web)

Field	Description
`domain`	Root domain: `example.com`
`page`	Full page URL
`publisher.id`	Your Praevis Publisher ID

`content` object

Field	Description
`genre`	Content genre (improves fill rate with genre-targeting DSPs)
`title`	Content title
`series`	Series name
`season`	Season (string)
`episode`	Episode number
`len`	Length in seconds
`livestream`	`1` = live
`cat`	IAB content categories

Praevis extensions (`ext`)

Field	Description
`ext.partner_id`	Platform partner ID (if applicable)
`ext.pool_id`	Override which inventory pool routes this request

Responses

Win (HTTP 200)

{
  "id": "req-001",
  "seatbid": [{
    "bid": [{
      "id": "bid-uuid",
      "impid": "1",
      "price": 3.50,
      "adm": "<VAST version=\"3.0\">...</VAST>",
      "crid": "creative-uuid",
      "w": 1920,
      "h": 1080
    }]
  }],
  "cur": "USD"
}

adm contains the full VAST XML string. Pass it directly to your video player.

No bid (HTTP 204)

Empty body. No DSP bid above the floor price.

Geo not served (HTTP 403)

Request came from a country with no active demand. Treat as no-fill — same as 204 from your ad server’s perspective. This is not an error.

Error (HTTP 400)

{ "error": "invalid publisher ID" }

Timeout

The exchange waits up to 150ms for DSPs to respond. Your request will always get a response within ~200ms total.

If you need sub-150ms response guarantees, consider the Praevis edge regions. FRA, NYC, and LON are all within 10ms of major CDN PoPs.

VAST Integration Sandbox Testing