Guides
The Decision API
Request ads as JSON with POST /decision on your serving domain. Send a publisher and one or more placements; receive prices, creative content, and signed tracking URLs for each decision. A placement can return multiple winners when configured to do so.
Request and response
Use this endpoint when your application renders ads from JSON. The request below asks for one ad in a sports-page placement. Replace the sample public IDs with a configured sandbox publisher and placement; a successful response lets you inspect the creative content and tracking URLs before connecting them to your rendering code.
POST https://ads.acme.example/decision
{ "publisher_id": "acme-pub", "placements": [{ "placement_id": "acme-leaderboard", "winner_count": 1 }],
"context": { "section": "sports" } }| Request | Meaning |
|---|---|
publisher_id | Publisher public id. |
placements[] | placement_id (public id) with optional winner_count, size and format hints. |
user | Optional user key (privacy-gated) and identity signals. |
context | Key-values mapped onto the request's custom keys and content fields. |
privacy | GPP and legacy consent signals. |
floor, tmax_ms | Floor as a decimal string and auction deadline in milliseconds. |
knobs | Request-time settings such as pacing or exploration rate, subject to configured limits and permissions. |
| Decision | Meaning |
|---|---|
bid_uid | Stable id for the decision, echoed by the beacons. |
line_item_id, line_item_ref, creative_ref, template_id, external_item_id | What won and which creative or template rendered it. |
price, currency | Decimal string and currency. |
markup | Creative JSON or display/native content, including any configured template fields. |
impression_url, click_url | Sealed beacon URLs; fire impression_url when the ad is shown. |
The response includes one entry per requested placement. An empty decisions array means no fill for that placement; the request still succeeds. Call the returned impression URL when an ad is shown to record billable delivery. Explain and diagnostic tools require the operability entitlement.
Clients
Use the Go client (riptide.dev/clients/go/decision) or TypeScript client
(@riptide/decision-client) to send requests. Manage creative templates through
the Admin API; their fields determine the content returned in
markup.
import { DecisionClient } from "@riptide/decision-client";
const client = new DecisionClient({ baseUrl: "https://ads.acme.example" });
const resp = await client.decide({ publisher_id: "acme-pub", placements: [{ placement_id: "acme-leaderboard" }] });Connect tracking to your application
Call the issued beacon URLs when your application shows an ad or records a click. To inspect responses before wiring those callbacks, start with the serving probe.