Guides
The OpenRTB endpoint
Send OpenRTB 2.6 auction requests to POST /ortb on your serving domain. Riptide resolves placements, evaluates eligible demand, and returns bids or a no-bid response. Responses include the x-openrtb-version: 2.6 header.
Request
Use OpenRTB when your bidder or wrapper already exchanges bid requests. This example offers a video placement with a duration of 5 to 30 seconds and a negotiated deal ID. Replace the sample placement and deal with your sandbox configuration to check whether eligible demand returns a bid with the expected creative and terms.
POST https://ads.acme.example/ortb
Content-Type: application/json
x-openrtb-version: 2.6
{ "id": "auction-1",
"imp": [{ "id": "1", "tagid": "acme-preroll",
"video": { "mimes": ["video/mp4"], "w": 1280, "h": 720, "minduration": 5, "maxduration": 30, "protocols": [2,3,7,8], "plcmt": 1 },
"pmp": { "deals": [{ "id": "ACME-PG-2026" }] } }],
"site": { "page": "https://publisher.example/", "publisher": { "id": "acme-pub" } },
"device": { "ua": "Mozilla/5.0 ...", "ip": "203.0.113.10" },
"tmax": 500 }| Inbound | How Riptide reads it |
|---|---|
imp.tagid / imp.ext.gpid / site,app path | Placement key, in that order. An impression that cannot be served is skipped with a reason; the remaining impressions are processed. |
banner, video, audio, native, pmp, qty, refresh, durfloors | OpenRTB 2.6 impression attributes. Native 1.2 requests include the requested event trackers in the response. |
site, app, dooh, publisher, content, producer, network, channel | Inventory and content objects, including inventorypartnerdomain (2.5 fallback read as well). |
device, geo, user, eids, data/segment (segtax) | Device, geo and identity; seller-defined audiences become qualified segments ("<segtax>:<id>"). |
source.schain, regs (gdpr, us_privacy, gpp, coppa), user.ext.consent | Supply-chain and privacy signals. OpenRTB 2.6 fields take precedence over equivalent 2.5 extension fields. |
video.podid, slotinpod, maxseq, poddur | Impressions sharing a podid are sent to demand as one pod, then combined after each impression’s auction. |
Response
| Outbound | What it carries |
|---|---|
seatbid.seat | One seatbid per buyer seat; the tenant's own seat for house and direct wins. |
bid.impid, price, cur, dealid | Echoes the imp; price in the request's currency; dealid when a preferred, guaranteed or private deal won. |
bid.adm, mtype, dur, w, h | VAST for video (mtype 2), markup for banner (1), Native 1.2 JSON for native (4); duration for video. |
bid.adomain, cat, cattax, attr, apis, protocol, language, bundle, iurl, cid, crid, adid, slotinpod | Creative metadata, all advertiser domains. |
seatbid.group | 1 only when a pod slate from one seat must win or lose together. |
bid.ext.dsa, ext.dchain | Buyer transparency objects pass through. |
Deals and seats
A deal id in imp.pmp.deals matches the tenant's deals (preferred, guaranteed or private, with
flight, seats, domains and caps from the console or createDeal); a winning deal bid answers with
bid.dealid. Seats are the buyer seats configured on demand partners; seat allow-lists on a
private deal are enforced before the auction.
No-bid and loss codes
A no-bid with a reason code returns HTTP 200 with id and nbr.
A no-bid without a reason code returns HTTP 204 with no body. Outbound loss notices use
OpenRTB 3.0 loss codes. Riptide reserves 500 for a bid superseded by the long auction pass
and 501 for a bid blocked by the supply-transparency policy.
| nbr | Meaning |
|---|---|
0 - 17 | The standard list: unknown error, technical error, invalid request, known web crawler, suspected non-human, data-center IP, unsupported device, blocked publisher, unmatched user, daily user cap, daily domain cap, ads.txt unavailable, ads.txt violation, ads.cert unavailable, ads.cert violation, insufficient auction time, incomplete supply chain, blocked supply-chain node. |
500 | Rejected by the request-rate or latency limit. |
501 | Tenant data-residency region differs from this cell. |
502 | Request-level audience gate did not match. |
Check the integration
Run the conformance probe before connecting your wrapper's rendering and tracking code. It checks the response fields the wrapper needs to read.
riptide conformance ortb --serve https://ads.acme.example --pub acme-pub --tag acme-preroll
The probe posts a minimal 2.6 video request and checks the status, the version header, the echoed id and
each bid's impid, VAST markup, and mtype. Customer checkouts also include header-bidding
adapter examples under examples/headerbidding.
Request creative content as JSON
Use the Decision API when your application needs creative content and tracking URLs to render directly. The serving probe can help you check either protocol before connecting your renderer.