Use the /sapi/adschedule endpoint to manage ad schedules. An ad schedule defines which ads play at which break positions (preroll, midroll, and postroll) during video playback. Ad schedules are assigned to one or more playouts via the playoutCodes field; each playout can have only one active ad schedule at a time.
Each ad break position contains an ordered list of ad items. An item references either a direct VAST URL or a Blue Billywig Auction entity (via the /sapi/auction endpoint). Items can optionally be configured with a waterfall list of fallback sources that are tried in sequence when the primary source returns no ad.
1.0 | AdSchedule Object
1.1 | Example AdSchedule Object
{
"type": "AdSchedule",
"id": "42",
"code": "my_ad_schedule",
"title": "My Ad Schedule",
"description": "Preroll and midroll schedule for the default playout",
"publicationid": "754",
"status": "published",
"createddate": "2024-01-15T10:30:00Z",
"updateddate": "2024-06-01T09:15:22Z",
"playoutCodes": ["default"],
"preroll": {
"skippable": true,
"minimumContentLength": 0,
"items": [
{
"id": "a1b2c3",
"vast_url": "https://example.com/vast.xml"
}
]
},
"midroll": {
"skippable": false,
"minimumContentLength": 120,
"interval": 25,
"intervalUnit": "percent",
"useSceneAlignment": false,
"items": [
{
"id": "d4e5f6",
"auction_id": "my_auction_code",
"waterfalling": true,
"waterfall": [
{
"id": "g7h8i9",
"auction_id": "fallback_auction_code"
}
]
}
]
},
"postroll": {
"skippable": false,
"minimumContentLength": 0,
"items": []
}
}1.2 | AdSchedule Attributes
| Parameter | Description |
|---|---|
id | (string) Unique identifier of the ad schedule. Read-only. |
type | (string) Type of object: "AdSchedule". Read-only. |
code | (string) Unique textual code used to reference this ad schedule. Auto-generated from title on creation; must be unique within the publication. |
title | (string) Display name of the ad schedule. |
description | (string) Optional description. |
publicationid | (string) Unique identifier of the publication. Read-only. |
status | (string) "draft" or "published". Only published ad schedules are active during playback. |
createddate | (string) ISO 8601 date/time the ad schedule was created. Read-only. |
updateddate | (string) ISO 8601 date/time the ad schedule was last updated. Read-only. |
playoutCodes | (array of strings) Codes of the playouts this ad schedule is assigned to. A playout can be assigned to at most one ad schedule. |
preroll | (object) Ad break configuration for pre-roll ads. See Ad Position Attributes. |
midroll | (object) Ad break configuration for mid-roll ads. Extends the base position object with interval settings. See Ad Position Attributes. |
postroll | (object) Ad break configuration for post-roll ads. See Ad Position Attributes. |
playout | (object) Player commercial controls configuration (pause button, mute button, progress bar, ad icon, time display). Applied to playouts assigned to this schedule. |
1.3 | Ad Position Attributes
Applies to preroll, midroll, and postroll. The midroll object includes three additional fields.
| Parameter | Description |
|---|---|
skippable | (boolean) Whether viewers can skip ads at this position. |
minimumContentLength | (integer) Minimum video duration in seconds required before this ad position fires. Set to 0 to always fire. |
items | (array) Ordered list of ad items. See Ad Item Attributes. |
interval | (integer) Midroll only. How often the midroll fires, expressed in the unit defined by intervalUnit. |
intervalUnit | (string) Midroll only. Unit for interval: "percent" (percentage of video duration) or "seconds". |
useSceneAlignment | (boolean) Midroll only. When true, the midroll fires at the nearest scene cut rather than at the exact interval position. |
1.4 | Ad Item Attributes
Each object in an items array represents a single ad source. Exactly one of vast_url or auction_id must be set.
| Parameter | Description |
|---|---|
id | (string) Internal identifier for this item within the schedule. Auto-generated on creation. Read-only. |
vast_url | (string) Direct VAST tag URL. Mutually exclusive with auction_id. |
auction_id | (string) Code of a Blue Billywig Auction (/sapi/auction). Mutually exclusive with vast_url. |
waterfalling | (boolean) When true, the waterfall list is used as an ordered sequence of fallback sources. |
waterfall | (array) Fallback ad sources tried in order when the primary source returns no ad. Each entry contains id, and either vast_url or auction_id. |
2.0 | Retrieve List
Retrieves a list of ad schedules.
3.0 | Retrieve
Retrieves a single ad schedule object.
4.0 | Create/Update
Creates a new ad schedule. Omit id in the request body to create; include id to update an existing ad schedule.
Example request payload:
{
"title": "My Ad Schedule",
"description": "Preroll and midroll schedule for the default playout",
"status": "published",
"playoutCodes": ["default"],
"preroll": {
"skippable": true,
"minimumContentLength": 0,
"items": [
{
"id": "a1b2c3",
"vast_url": "https://example.com/vast.xml"
}
]
},
"midroll": {
"skippable": false,
"minimumContentLength": 120,
"interval": 25,
"intervalUnit": "percent",
"useSceneAlignment": false,
"items": []
},
"postroll": {
"skippable": false,
"minimumContentLength": 0,
"items": []
}
}5.0 | Delete
Deletes an ad schedule. Playouts previously assigned to the deleted schedule will no longer have an active ad schedule.