Brightcove Ad Configurations API

openapi: 3.0.3
info:
  title: Brightcove Analytics API Reference Access Tokens Ad Configurations API
  description: "Reference for the Brightcove Analytics API, used to retrieve analytics data for your accounts. To test API requests, you can use our <a href=\"/getting-started/concepts-testing-tools-brightcove-apis.html\" target=\"_blank\">API Testing Tools</a>.\n\nFor additional in-depth guides to features of the API, see the **[general documentation](/analytics/index.html)**.\n\n **Base URL**: https://analytics.api.brightcove.com"
  x-bc-access: public
  version: 1.0.0
servers:
- url: https://analytics.api.brightcove.com
  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:
    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
    AdConfigList:
      title: List Ad Configurations Response
      type: array
      description: Array of ad configuration objects
      items:
        $ref: '#/components/schemas/AdConfiguration'
    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
    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
  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/code-samples/oauth-api-sample-get-access-token.html) to learn more
      flows:
        clientCredentials:
          tokenUrl: https://oauth.brightcove.com/v4/access_token
          scopes:
            video-cloud/analytics/read: Read analytics data
            video-cloud/video/read: Read video data
x-bc-implicit-head: true
x-bc-implicit-options: true
x-bc-upstream: https://backend_server