Brightcove Ad Configurations API
Operations for managing ad configurations.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/brightcove-ad-configurations-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
description: 'API for Brightcove SSAI
This API is used for managing operations related to Server-Side Ad Insertion (SSAI).
See [Video Cloud SSAI Ad Config API](/ssai/getting-started/video-cloud-ssai-ad-config-api.html) for more details on using the API.
You can easily create, list and delete ad configurations in Video Cloud Studio as well. For details, see [Configuring Server-Side Ad Settings](https://studio.support.brightcove.com/admin/configuring-server-side-ad-settings.html).
For additional in-depth guides to features of the API, see the **[General documentation](/)**.
**Base URL:** https://ssai.api.brightcove.com/v1'
version: 0.1.0
title: Brightcove SSAI Ad Configurations API
x-bc-access: public
servers:
- url: https://ssai.api.brightcove.com/v1
variables: {}
tags:
- name: Ad Configurations
description: Operations for managing ad configurations.
paths:
/accounts/{{account_id}}/ssai_configs:
get:
tags:
- Ad Configurations
summary: List the ad configurations for the account
description: List the ad configurations defined for an account.
operationId: getAdConfigurations
security:
- BC_OAuth2:
- video-cloud/ssai/read
parameters:
- $ref: '#/components/parameters/AccountId'
responses:
'200':
description: A list of videos.
content:
application/json:
schema:
$ref: '#/components/schemas/AdConfigList'
'403':
description: Forbidden
'422':
description: Invalid query parameters
'500':
description: Server error
post:
tags:
- Ad Configurations
summary: Create an ad configuration
description: Create an ad configuration
operationId: createAdConfigurations
security:
- BC_OAuth2:
- video-cloud/ssai/all
parameters:
- $ref: '#/components/parameters/AccountId'
requestBody:
description: Create a new ad configuration
content:
application/json:
schema:
$ref: '#/components/schemas/AdConfiguration'
required: true
responses:
'200':
description: A list of videos.
content:
application/json:
schema:
$ref: '#/components/schemas/AdConfiguration'
'403':
description: Forbidden
'422':
description: Invalid query parameters
'500':
description: Server error
/accounts/{{account_id}}/ssai_configs/{config_id}:
get:
tags:
- Ad Configurations
summary: Get ad configurations details
description: Get the details of an ad configurations defined for an account.
operationId: getAdConfiguration
security:
- BC_OAuth2:
- video-cloud/ssai/read
parameters:
- $ref: '#/components/parameters/AccountId'
- $ref: '#/components/parameters/ConfigId'
responses:
'200':
description: A list of videos.
content:
application/json:
schema:
$ref: '#/components/schemas/AdConfiguration'
'403':
description: Forbidden
'422':
description: Invalid query parameters
'500':
description: Server error
put:
tags:
- Ad Configurations
summary: Update an ad configuration
description: Update an ad configuration
operationId: updateAdConfigurations
security:
- BC_OAuth2:
- video-cloud/ssai/all
parameters:
- $ref: '#/components/parameters/AccountId'
- $ref: '#/components/parameters/ConfigId'
requestBody:
description: Create a new ad configuration
content:
application/json:
schema:
$ref: '#/components/schemas/AdConfiguration'
required: true
responses:
'200':
description: A list of videos.
content:
application/json:
schema:
$ref: '#/components/schemas/AdConfiguration'
'403':
description: Forbidden
'422':
description: Invalid query parameters
'500':
description: Server error
components:
schemas:
AdConfigList:
title: List Ad Configurations Response
type: array
description: Array of ad configuration objects
items:
$ref: '#/components/schemas/AdConfiguration'
AdConfiguration:
title: Ad Configuration Response
type: object
properties:
account_id:
type: string
description: The Video Cloud account id
ad_config:
$ref: '#/components/schemas/AdConfig'
ad_tracking_sample_percentage:
type: integer
description: The value determines the percentage of sessions that will be logged. A value of 0 disables logs entirely. 0 is the default value.
minimum: 0
maximum: 100
default: 0
beacon_templates:
type: array
description: 'An array of beacons to fire (example: 3rd-party beacons)'
items:
$ref: '#/components/schemas/BeaconTemplate'
config_id:
type: string
description: System id for this configuration
readOnly: true
created_timestamp:
type: string
description: Date-time when the ad configuration was created
description:
type: string
description: Description of the ad configuration
discontinuities:
$ref: '#/components/schemas/Discontinuities'
extend_beacon_guard_ttl:
type: boolean
description: Sets the length of the Beacon Guard TTL (Time to live) to the length of the Content’s Session TTL. Otherwise, the default is 1 minute.
default: false
name:
type: string
description: Name of the ad configuration
updated_timestamp:
type: string
description: Date-time when the ad configuration was last updated
vmap_response_namespace:
type: string
description: Adjusts the VMAP output to use the legacy Unicorn Once namespace format or to use the new Brightcove namespace format.
enum:
- bc
- uo
default: bc
example:
- name: SSAI VMAP 2
vmap_response_namespace: bc
config_id: 1bcd16d4-585c-40bd-9300-17caf2ed075e
account_id: '1752604059001'
created_timestamp: '2019-01-09T13:16:42.132450307Z'
updated_timestamp: '2019-01-09T13:16:42.132450307Z'
description: Basic ad configuration
ad_config:
enable_ads: true
expected_ad_response: dfp_vmap
disable_server_beacons: false
round_up_cue_points: true
template_url:
template: https://solutions.brightcove.com/bcls/brightcove-player/vmap/simple-vmap.xml
beacon_templates:
- type: content_start
template_url:
template: https://myserver.com/beaconRX/{{metadata.video_id}}/load?position=load&sid={{system.xfp.unique_user_id}}&jid={{metadata.video_id}}&rnd32={{sytem.random_number_32}}&bid={{system.uuid}}&t={{system.timestamp_utc}}&ua={{system.user_agent}}&ip={{system.ip_address}}&ref={{system.referer}}
- type: content_midpoint
template_url:
template: https://myserver.com/beaconRX/{{metadata.video_id}}/load?position=load&sid={{system.xfp.unique_user_id}}&jid={{metadata.video_id}}&rnd32={{sytem.random_number_32}}&bid={{system.uuid}}&t={{system.timestamp_utc}}&ua={{system.user_agent}}&ip={{system.ip_address}}&ref={{system.referer}}
- type: ad_start
template_url:
template: https://myserver.com/beaconRX/{{metadata.video_id}}/load?position=load&sid={{system.xfp.unique_user_id}}&jid={{metadata.video_id}}&rnd32={{sytem.random_number_32}}&bid={{system.uuid}}&t={{system.timestamp_utc}}&ua={{system.user_agent}}&ip={{system.ip_address}}&ref={{system.referer}}
- type: content_complete
template_url:
template: https://myserver.com/beaconRX/{{metadata.video_id}}/load?position=load&sid={{system.xfp.unique_user_id}}&jid={{metadata.video_id}}&rnd32={{sytem.random_number_32}}&bid={{system.uuid}}&t={{system.timestamp_utc}}&ua={{system.user_agent}}&ip={{system.ip_address}}&ref={{system.referer}}
discontinuities:
dash:
- '*'
hls:
- '*'
extend_beacon_guard_ttl: true
AdConfig:
title: ad_config
type: object
description: Ad config part of an ad configuration object
properties:
expected_ad_response:
type: string
description: 'Which tech to use to parse the response.
When the `expected_ad_response` is set to `vast_3_0`, SSAI makes one VAST call for each ad cue point defined in Video Cloud. For VMAP and ad rules, SSAI makes requests based on the defined ad breaks in the initial ad response.'
enum:
- dfp_ad_rules
- dfp_vmap
- smart_xml
- vast_3_0
enable_ads:
type: boolean
description: 'Flags whether to disable the server side firing of ad requests.
When set to `false`, SSAI will not request any ads server-side and will include all ad requests in the VMAP output
When set to `true`, SSAI will request ads server-side and include any that are unsuccessful in the VMAP output'
default: true
disable_server_beacons:
type: boolean
description: 'Flags whether to disable the server side firing of ad impressions/beacons
When set to `true`, SSAI will not fire any beacons server-side and will include all beacons in the VMAP output
When set to `false`, SSAI will fire the beacons it is able to server-side and include any it is not able to in the VMAP output'
round_up_cue_points:
type: boolean
description: Flags whether to round up ad cue point time to the next keyframe
default: false
template_url:
type: object
properties:
template:
type: string
description: Ad tag template. Available variables described in [this document](/vod/guides/video-cloud-ssai-ad-config-api.html#Ad_variables).
BeaconTemplate:
title: Beacon Template
description: Beacons are sent to send analytics data from the client. The beacon template defines the type of events to send beacons for and the information that will be sent.
type: object
properties:
type:
type: string
description: Type of beacon to fire.
enum:
- content_first_quartile
- content_start
- content_midpoint
- content_third_quartile
- content_complete
- content_quartiles
- content_interval
- ad_start
- ad_first_quartile
- ad_midpoint
- ad_third_quartile
- ad_complete
- ad_quartiles
- ad_break_start
- ad_break_end
- segment_start
- segment_end
- on_load
template_url:
type: object
properties:
template:
type: string
description: The beacon URL template
Discontinuities:
type: object
description: Controls the versions of DASH to deliver Multi Period manifests or versions of HLS to deliver with discontinuities
properties:
dash:
type: array
description: 'Controls which versions of dash to deliver Multi Period Dash manifests.
Set to ["*"] to deliver multi-period dash for all versions
Empty list for never
Example: ["live-timeline"] to deliver for live-timeline but not for hbbtv'
items:
type: string
example:
- live-timeline
hls:
type: array
description: 'Controls which versions of hls to deliver with discontinuities.
Set to ["*"] to delivery with discontinuities in all versions of HLS
Empty list for never
Example: ["v4","v5"] to deliver for v4 & v5 but not for v3'
items:
type: string
example:
- v4
- v5
parameters:
AccountId:
name: account_id
in: path
description: ID of the account to query video statuses for
required: true
schema:
type: string
ConfigId:
name: config_id
in: path
description: ID of the ad configuration
required: true
schema:
type: string
securitySchemes:
BC_OAuth2:
type: oauth2
description: Brightcove OAuth API. See the [support documentation](/oauth/index.html) or [Getting Access Tokens](/oauth/guides/getting-access-tokens.html) to learn more
flows:
clientCredentials:
tokenUrl: https://oauth.brightcove.com/v4/access_token
scopes:
video-cloud/ssai/read: Read SSAI metadata
video-cloud/ssai/all: Read and write SSAI metadata
x-bc-implicit-head: true
x-bc-implicit-options: true
x-bc-upstream: https://backend_server