Use the /sapi/auction endpoint to manage Prebid.js header bidding auctions. An auction defines a set of bid adapters (SSPs/DSPs), video and slot parameters, and Prebid.js configuration that is applied when requesting bids before an ad break starts. The winning bid is either used directly or passed to an ad server with targeting key-values appended to the ad server URL.
Auctions are assigned to ad breaks in an Ad Schedule via the auction_id field on an ad break item. Multiple auctions can be chained in a waterfall as fallback sources. For more information on configuring auctions in the Blue Billywig interface, see Using Auctions for Header Bidding.
1.0 | Auction Object
1.1 | Example Auction Object
{
"type": "Auction",
"id": "789",
"code": "homepage_preroll_auction",
"name": "Homepage Preroll Auction",
"publicationid": "754",
"status": "published",
"subtype": "prebid",
"createddate": "2024-03-01T12:00:00Z",
"updateddate": "2024-06-01T09:15:22Z",
"adServerUrl": "https://pubads.g.doubleclick.net/gampad/ads?iu=/1234/video&sz=640x480&...",
"prebidConfiguration": {
"config": {
"usePrebidCache": true,
"cache": {
"url": "https://bb-pbc.mainroll.com/cache"
},
"priceGranularity": "medium",
"deviceAccess": true
},
"adUnits": {
"homepage_preroll_auction": {
"code": "homepage_preroll_auction",
"mediaTypes": {
"video": {
"minduration": 5,
"maxduration": 30,
"minbitrate": 100,
"maxbitrate": 5000,
"mimes": ["video/mp4"],
"w": 1280,
"h": 720,
"pos": 1,
"plcmt": 1,
"playbackmethod": [1],
"playerSize": [1280, 720],
"api": [2],
"protocols": [2, 3, 5, 6]
}
},
"bids": [
{
"bidder": "appnexus",
"params": {
"placementId": "1234567"
}
}
],
"bidderTimeout": 3000,
"deviceAccess": true,
"priceGranularity": "medium",
"enableSendAllBids": false,
"firstPartyData": {
"skipEnrichments": false
}
}
}
}
}1.2 | Auction Attributes
| Parameter | Description |
|---|---|
id | (string) Unique identifier of the auction. Read-only. |
type | (string) Type of object: "Auction". Read-only. |
code | (string) Unique textual code used to reference this auction in ad schedule configurations. Auto-generated from name on creation; cannot be changed after creation. |
name | (string) Display name of the auction. |
publicationid | (string) Unique identifier of the publication. Read-only. |
status | (string) "draft" or "published". Only published auctions are active. |
subtype | (string) Auction type. Currently always "prebid". |
createddate | (string) ISO 8601 date/time the auction was created. Read-only. |
updateddate | (string) ISO 8601 date/time the auction was last updated. Read-only. |
adServerUrl | (string) Optional. VAST URL of your ad server (e.g. Google Ad Manager). Prebid targeting key-values are appended to this URL. Leave empty to use the winning bid directly. |
prebidConfiguration | (object) Prebid.js configuration for this auction. See prebidConfiguration Attributes. |
1.3 | prebidConfiguration Attributes
The prebidConfiguration object has two top-level keys: config and adUnits.
config
| Parameter | Description |
|---|---|
config.usePrebidCache | (boolean) When true, stores VAST responses in Prebid cache so they can be retrieved via a cache key. Required for video ads in most setups. |
config.cache.url | (string) URL of the Prebid cache endpoint. |
config.priceGranularity | (string) Default price granularity used to convert bid prices into targeting key-values. Options: "low", "medium", "high", "auto", "dense". Can be overridden per ad unit. |
config.deviceAccess | (boolean) When true, allows Prebid.js to read and write cookies and local storage. |
adUnits
The adUnits object is keyed by the auction code. Each entry is a Prebid.js ad unit definition.
| Parameter | Description |
|---|---|
adUnits[code].code | (string) Ad unit code. Matches the auction code. |
adUnits[code].bids | (array) List of bid adapter configurations. Each item has a bidder (string) and params (object) with adapter-specific parameters. |
adUnits[code].mediaTypes.video | (object) OpenRTB video media type definition. See Video Attributes. |
adUnits[code].bidderTimeout | (integer) Maximum time in milliseconds bidders have to respond. Minimum value: 100. |
adUnits[code].deviceAccess | (boolean) Allows Prebid.js to read and write cookies and local storage for this ad unit. |
adUnits[code].priceGranularity | (string) Price granularity for this ad unit. Overrides config.priceGranularity when set. |
adUnits[code].enableSendAllBids | (boolean) When true (and adServerUrl is set), all bids are sent as targeting keys. When false, only the top bid is forwarded. |
adUnits[code].firstPartyData.skipEnrichments | (boolean) When true, disables the first-party data enrichment module for this auction. |
adUnits[code].gptPreAuction.enabled | (boolean) Activates the Google Publisher Tag pre-auction module. |
adUnits[code].gptPreAuction.useDefaultPreAuction | (boolean) Uses the default GPT pre-auction implementation when enabled. |
1.4 | Video Attributes
These fields correspond to the OpenRTB mediaTypes.video object and describe the type of video creative the auction requests.
| Parameter | Description |
|---|---|
minduration | (integer) Minimum acceptable video ad duration in seconds. |
maxduration | (integer) Maximum acceptable video ad duration in seconds. |
minbitrate | (integer) Minimum acceptable bitrate in kbps. |
maxbitrate | (integer) Maximum acceptable bitrate in kbps. |
mimes | (array of strings) Accepted video MIME types, e.g. ["video/mp4", "application/javascript"]. |
w | (integer) Width of the video player in pixels. |
h | (integer) Height of the video player in pixels. |
pos | (integer) Position of the player on the page. OpenRTB pos values: 0 = Unknown, 1 = Above the fold, 3 = Below the fold, 4 = Header, 5 = Footer, 6 = Sidebar, 7 = Fullscreen. |
plcmt | (integer) Placement type per OpenRTB v2.6. 1 = Instream, 2 = Accompanying Content, 3 = Interstitial, 4 = No Content / Standalone. |
placement | (integer) Legacy OpenRTB placement field. Prefer plcmt for new configurations. 1 = In-stream, 2 = In-banner, 3 = In-article, 4 = In-feed, 5 = Interstitial/Floating. |
playbackmethod | (array of integers) Allowed playback initiation methods. 1 = Page load with sound on, 2 = Page load with sound off, 3 = Click with sound on, 4 = Mouse-over with sound on, 5 = Entering viewport with sound on, 6 = Entering viewport with sound off. Leave empty to allow all methods. |
playerSize | (array of integers) Player dimensions as sent to bidders: [width, height]. |
api | (array of integers) Supported API frameworks. 1 = VPAID 1.0, 2 = VPAID 2.0, 3 = MRAID-1, 4 = ORMMA, 5 = MRAID-2, 6 = MRAID-3. |
protocols | (array of integers) Supported VAST protocol versions. 1 = VAST 1.0, 2 = VAST 2.0, 3 = VAST 3.0, 5 = VAST 2.0 Wrapper, 6 = VAST 3.0 Wrapper, 7 = VAST 4.0, 8 = VAST 4.0 Wrapper. |
delivery | (array of integers) Supported ad delivery methods. 1 = Streaming, 2 = Progressive, 3 = Download. |
2.0 | Retrieve List
GET /sapi/auction
Retrieves a list of auctions.
3.0 | Retrieve
GET /sapi/auction/{id}
Retrieves a single auction object.
4.0 | Create/Update
PUT /sapi/auction
Creates a new auction. Omit id in the request body to create; include id to update an existing auction.
Note:
The code field is auto-generated from name on creation and cannot be changed after the auction is saved.
Example request payload:
{
"name": "Homepage Preroll Auction",
"status": "published",
"adServerUrl": "https://pubads.g.doubleclick.net/gampad/ads?iu=/1234/video&sz=640x480&...",
"prebidConfiguration": {
"config": {
"usePrebidCache": true,
"cache": {
"url": "https://bb-pbc.mainroll.com/cache"
},
"priceGranularity": "medium",
"deviceAccess": true
},
"adUnits": {
"homepage_preroll_auction": {
"code": "homepage_preroll_auction",
"mediaTypes": {
"video": {
"minduration": 5,
"maxduration": 30,
"mimes": ["video/mp4"],
"w": 1280,
"h": 720,
"pos": 1,
"plcmt": 1
}
},
"bids": [
{
"bidder": "appnexus",
"params": {
"placementId": "1234567"
}
}
],
"bidderTimeout": 3000
}
}
}
}5.0 | Delete
DELETE /sapi/auction/{id}
Deletes an auction. Before deleting, remove the auction from any ad schedule items that reference it.