OpenAPI Specification
openapi: 3.0.3
info:
title: Brightcove Analytics API Reference Access Tokens Players 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: Players
description: Operations for managing players.
paths:
/accounts/{{account_id}}/players:
get:
tags:
- Players
summary: Get a list of players
description: Get a list of players
operationId: GetPlayers
security:
- BC_OAuth2:
- video-cloud/player/read
parameters:
- $ref: '#/components/parameters/account_id'
- $ref: '#/components/parameters/ContentType'
- $ref: '#/components/parameters/Authorization'
responses:
'200':
description: SUCCESS
content:
application/json:
schema:
description: Success response
type: object
properties:
item_count:
type: integer
description: The number of items in the `items` array
items:
type: array
items:
$ref: '#/components/schemas/player_response'
'400':
description: 'BAD_REQUEST: the syntax of the API call is likely incorrect'
'401':
description: 'UNAUTHORIZED: Authentication failed - check to make sure your client credentials were correct for the access token'
'404':
description: 'RESOURCE_NOT_FOUND: The api could not find the resource you requested'
'429':
description: 'RATE_LIMIT_EXCEEDED: Too many requests per second'
'500':
description: 'INTERNAL_SERVER_ERROR: there was an error trying to fulfill the request'
deprecated: false
x-operation-settings:
CollectParameters: false
AllowDynamicQueryParameters: false
AllowDynamicFormParameters: false
IsMultiContentStreaming: false
post:
tags:
- Players
description: Create a player. The POST method creates a player by submitting a player configuration. The properties of Brightcove Player you can manipulate with player management are detailed in the **Request Body Fields** section below. To create a player, a publisher must decide what properties the final player will have. If no properties are given at creation, a blank player will be created with only the base player skin applied to the player. A user may then use an HTTP PATCH method to update properties after the player has been created.
summary: Create a player
operationId: CreatePlayer
security:
- BC_OAuth2:
- video-cloud/player/all
parameters:
- $ref: '#/components/parameters/account_id'
- $ref: '#/components/parameters/ContentType'
- $ref: '#/components/parameters/Authorization'
requestBody:
description: Create a player
content:
application/json:
schema:
$ref: '#/components/schemas/player_request_body'
required: true
responses:
'201':
description: SUCCESS
content:
application/json:
schema:
description: '200'
type: object
properties:
id:
type: string
description: The player id
readOnly: true
url:
type: string
description: The player URL
readOnly: true
embed_code:
type: string
description: The published player iframe tag
readOnly: true
embed_in_page:
type: string
description: URL to browse to retrieve the in-page embed code for published player
readOnly: true
preview_url:
type: string
description: URL to preview player
readOnly: true
preview_embed_in_page:
type: string
description: URL to browse to retrieve the in-page embed code for preview player
readOnly: true
preview_embed_code:
type: string
description: Preview player iframe tag
readOnly: true
example:
id: 69EmV4W8r
url: https://players.brightcove.net/57838016001/69EmV4W8r_default/index.html
embed_code: <iframe src='//players.brightcove.net/57838016001/69EmV4W8r_default/index.html' allowfullscreen webkitallowfullscreen mozallowfullscreen></iframe>
embed_in_page: https://players.brightcove.net/57838016001/69EmV4W8r_default/in_page.embed
preview_url: https://preview-players.brightcove.net/v2/accounts/57838016001/players/69EmV4W8r/preview/embeds/default/master/index.html
preview_embed_in_page: https://preview-players.brightcove.net/v2/accounts/57838016001/players/69EmV4W8r/preview/embeds/default/master/in_page.embed
preview_embed_code: <iframe src='//preview-players.brightcove.net/v2/accounts/57838016001/players/69EmV4W8r/preview/embeds/default/master/index.html' allowfullscreen webkitallowfullscreen mozallowfullscreen></iframe>
'400':
description: 'BAD_REQUEST: the syntax of the API call is likely incorrect'
'401':
description: 'UNAUTHORIZED: Authentication failed - check to make sure your client credentials were correct for the access token'
'404':
description: 'RESOURCE_NOT_FOUND: The api could not find the resource you requested'
'429':
description: 'RATE_LIMIT_EXCEEDED: Too many requests per second'
'500':
description: 'INTERNAL_SERVER_ERROR: there was an error trying to fulfill the request'
deprecated: false
x-operation-settings:
CollectParameters: false
AllowDynamicQueryParameters: false
AllowDynamicFormParameters: false
IsMultiContentStreaming: false
/accounts/{{account_id}}/players/{{player_id}}:
get:
tags:
- Players
summary: Get a single player
description: Get a player by ID
operationId: GetPlayer
security:
- BC_OAuth2:
- video-cloud/player/read
parameters:
- $ref: '#/components/parameters/account_id'
- $ref: '#/components/parameters/player_id'
- $ref: '#/components/parameters/ContentType'
- $ref: '#/components/parameters/Authorization'
responses:
'200':
description: '200'
content:
application/json:
schema:
$ref: '#/components/schemas/player_response'
'400':
description: 'BAD_REQUEST: the syntax of the API call is likely incorrect'
'401':
description: 'UNAUTHORIZED: Authentication failed - check to make sure your client credentials were correct for the access token'
'404':
description: 'RESOURCE_NOT_FOUND: The api could not find the resource you requested'
'429':
description: 'RATE_LIMIT_EXCEEDED: Too many requests per second'
'500':
description: 'INTERNAL_SERVER_ERROR: there was an error trying to fulfill the request'
deprecated: false
x-operation-settings:
CollectParameters: false
AllowDynamicQueryParameters: false
AllowDynamicFormParameters: false
IsMultiContentStreaming: false
patch:
tags:
- Players
description: Update a single player. The PATCH method can be used on a single player to do a VERY limited update. The only fields you can update in this manner are the `name` and `description` properties. All other player configuration must be done via the **PLAYER CONFIGURATIONS** APIs, detailed below.
summary: Update a player by ID
operationId: UpdatePlayer
security:
- BC_OAuth2:
- video-cloud/player/all
parameters:
- $ref: '#/components/parameters/account_id'
- $ref: '#/components/parameters/player_id'
- $ref: '#/components/parameters/ContentType'
- $ref: '#/components/parameters/Authorization'
requestBody:
description: Update the player
content:
application/json:
schema:
description: Update the player
type: object
properties:
name:
type: string
description: The player name
description:
type: string
description: The player description
required: true
responses:
'202':
description: SUCCESS
content:
application/json:
schema:
description: '200'
type: object
properties:
id:
type: string
description: The player id
readOnly: true
preview_url:
type: string
description: URL to preview player
readOnly: true
preview_embed_in_page:
type: string
description: URL to browse to retrieve the in-page embed code for preview player
readOnly: true
example:
id: 69EmV4W8r
url: https://players.brightcove.net/57838016001/69EmV4W8r_default/index.html
embed_code: <iframe src='//players.brightcove.net/57838016001/69EmV4W8r_default/index.html' allowfullscreen webkitallowfullscreen mozallowfullscreen></iframe>
embed_in_page: https://players.brightcove.net/57838016001/69EmV4W8r_default/in_page.embed
preview_url: https://preview-players.brightcove.net/v2/accounts/57838016001/players/69EmV4W8r/preview/embeds/default/master/index.html
preview_embed_in_page: https://preview-players.brightcove.net/v2/accounts/57838016001/players/69EmV4W8r/preview/embeds/default/master/in_page.embed
preview_embed_code: <iframe src='//preview-players.brightcove.net/v2/accounts/57838016001/players/69EmV4W8r/preview/embeds/default/master/index.html' allowfullscreen webkitallowfullscreen mozallowfullscreen></iframe>
'400':
description: 'BAD_REQUEST: the syntax of the API call is likely incorrect'
'401':
description: 'UNAUTHORIZED: Authentication failed - check to make sure your client credentials were correct for the access token'
'404':
description: 'RESOURCE_NOT_FOUND: The api could not find the resource you requested'
'429':
description: 'RATE_LIMIT_EXCEEDED: Too many requests per second'
'500':
description: 'INTERNAL_SERVER_ERROR: there was an error trying to fulfill the request'
deprecated: false
x-operation-settings:
CollectParameters: false
AllowDynamicQueryParameters: false
AllowDynamicFormParameters: false
IsMultiContentStreaming: false
delete:
tags:
- Players
description: Delete a player and all embeds associated with it.
summary: Delete a player by ID
operationId: DeletePlayer
security:
- BC_OAuth2:
- video-cloud/player/all
parameters:
- $ref: '#/components/parameters/account_id'
- $ref: '#/components/parameters/player_id'
- $ref: '#/components/parameters/ContentType'
- $ref: '#/components/parameters/Authorization'
responses:
'200':
description: SUCCESS
content:
application/json:
schema:
description: SUCCESS
type: object
properties:
message:
type: string
description: Message indicating player was deleted
readOnly: true
example: 'Successfully deleted player with the id: 69EmV4W8r'
'400':
description: 'BAD_REQUEST: the syntax of the API call is likely incorrect'
'401':
description: 'UNAUTHORIZED: Authentication failed - check to make sure your client credentials were correct for the access token'
'404':
description: 'RESOURCE_NOT_FOUND: The api could not find the resource you requested'
'429':
description: 'RATE_LIMIT_EXCEEDED: Too many requests per second'
'500':
description: 'INTERNAL_SERVER_ERROR: there was an error trying to fulfill the request'
deprecated: false
x-operation-settings:
CollectParameters: false
AllowDynamicQueryParameters: false
AllowDynamicFormParameters: false
IsMultiContentStreaming: false
/accounts/{{account_id}}/players/{{player_id}}/publish:
post:
tags:
- Players
summary: Publish a player
description: Publish a player for optimization and production use.
operationId: PublishPlayer
security:
- BC_OAuth2:
- video-cloud/player/all
parameters:
- $ref: '#/components/parameters/account_id'
- $ref: '#/components/parameters/player_id'
- $ref: '#/components/parameters/ContentType'
- $ref: '#/components/parameters/Authorization'
responses:
'201':
description: SUCCESS
content:
application/json:
schema:
description: '200'
type: object
properties:
id:
type: string
description: The player id
readOnly: true
url:
type: string
description: The player URL
readOnly: true
embed_code:
type: string
description: The published player iframe tag
readOnly: true
embed_in_page:
type: string
description: URL to browse to retrieve the in-page embed code for published player
readOnly: true
example:
id: SC5GzFPFkL
url: https://players.brightcove.net/57838016001/SC5GzFPFkL_default/index.html
embed_code: <iframe src='//players.brightcove.net/57838016001/SC5GzFPFkL_default/index.html' allowfullscreen webkitallowfullscreen mozallowfullscreen></iframe>
embed_in_page: https://players.brightcove.net/57838016001/SC5GzFPFkL_default/in_page.embed
'400':
description: 'BAD_REQUEST: the syntax of the API call is likely incorrect'
'401':
description: 'UNAUTHORIZED: Authentication failed - check to make sure your client credentials were correct for the access token'
'404':
description: 'RESOURCE_NOT_FOUND: The api could not find the resource you requested'
'429':
description: 'RATE_LIMIT_EXCEEDED: Too many requests per second'
'500':
description: 'INTERNAL_SERVER_ERROR: there was an error trying to fulfill the request'
deprecated: false
x-operation-settings:
CollectParameters: false
AllowDynamicQueryParameters: false
AllowDynamicFormParameters: false
IsMultiContentStreaming: false
components:
schemas:
player_response:
title: Create Player Request Body
type: object
description: Player object
properties:
account_id:
type: string
description: The account id
created_at:
type: string
description: The player creation date-time
embeds_count:
type: integer
description: The number of embeds (instances of this player), will always be at least 1
id:
type: string
description: The player id
last_viewed:
type: array
description: array of objects containing information about recent views of the player
items:
type: object
properties:
count:
type: integer
description: Number of the times the player was viewed
date:
type: string
description: Date-time string for the date of the views
name:
type: string
description: The player name
description:
type: string
description: The player description
url:
type: string
description: URL to player
branches:
type: object
description: The branches of the player - contains objects for the preview and master (published) player
properties:
preview:
type: object
description: The preview player branch
properties:
configuration:
$ref: '#/components/schemas/configuration'
updated_at:
type: string
description: date-time of last update to preview player
template_updated_at:
type: string
description: date-time of last update to preview player template
preview_url:
type: string
description: URL for the player
master:
type: object
description: The master (published) player branch
properties:
configuration:
$ref: '#/components/schemas/configuration'
updated_at:
type: string
description: date-time of last update to preview player
template_updated_at:
type: string
description: date-time of last update to preview player template
preview_url:
type: string
description: URL for the player
example:
account_id: '1752604059001'
id: default
name: Brightcove Default Player
description: This is an instance of the Brightcove Default Player. You can modify this or choose to create your own.
branches:
preview:
configuration:
player:
template:
version: 6.24.1
name: single-video-template
video_cloud:
policy_key: BCpkADawqM1TW0eSP6AUwWK5gRTb0ZL-Wb4SYZkb5unfFMVjCU4NYtePkcJaxArVJpQS1sd4PTJ2HP4TOzY1H3Z-zOM7w9_9y0XzoSI_Xg3F0FTNkcNLPJUVlo4cVnyyPK4qdx90f_xonqux
compatibility: true
updated_at: '2018-07-26T19:34:35.454Z'
template_updated_at: '2018-09-19T13:53:34.437Z'
preview_url: https://preview-players.brightcove.net/v2/accounts/1752604059001/players/default/preview/embeds/default/master/index.html
master:
configuration:
compatibility: true
video_cloud:
policy_key: BCpkADawqM1TW0eSP6AUwWK5gRTb0ZL-Wb4SYZkb5unfFMVjCU4NYtePkcJaxArVJpQS1sd4PTJ2HP4TOzY1H3Z-zOM7w9_9y0XzoSI_Xg3F0FTNkcNLPJUVlo4cVnyyPK4qdx90f_xonqux
player:
template:
name: single-video-template
version: 6.24.1
updated_at: '2018-07-26T19:34:35.476Z'
template_updated_at: '2018-09-19T13:53:39.568Z'
preview_url: https://preview-players.brightcove.net/v2/accounts/1752604059001/players/default/master/embeds/default/master/index.html
created_at: '2018-07-26T19:34:35.456Z'
embed_count: 1
url: https://players.brightcove.net/1752604059001/default_default/index.html
configuration:
title: Player Configuration
type: object
description: Configuration for a player
properties:
ad_config_id:
type: string
description: A Dynamic Delivery SSAI ad configuration ID. In addition to being set on the player configuration, it can be set at runtime via the adConfigId query string parameter for iframe players or the data-ad-config-id attribute for in-page players. Either of these will override any value in the player configuration.
default: undefined
ad_failover:
type: boolean
description: 'Set to true to enable ad failover behavior. This is a multi-part configuration that depends on: <br> - Both IMA3 and SSAI plugins must be configured on the player. <br> - An ad_config_id should be available, otherwise SSAI ads are not available.'
default: undefined
application_id:
type: string
description: The application ID is used to differentiate multiple uses of a single player in metrics. It is invisible to the user.
default: undefined
autoadvance:
type: integer
description: 'Autoadvance setting if using playlists: 0 for no wait; a number for seconds between advance; null to cancel autoadvance'
default: not enabled
autoplay:
oneOf:
- type: boolean
description: If `autoplay` is set to a Boolean value the browser's native autoplay behavior is used.
- type: string
description: 'If `autoplay` is set to one of the following three valid string values, the following occurs:<br> - `play`: The player will manually try to call play.<br> - `muted`: The player will manually mute the player and call play.<br> - `any`: The player will first try to call play. If that fails, mute the player and call play.<br> If any of the above fail, the player will display the "Big Play Button" as if autoplay was set to false.'
enum:
- play
- auto
- any
description: Indicates player should play video immediately, on platforms that allow this
default: false
compatibility:
type: boolean
description: Provides compatibility with the Player 1.x.x API
readOnly: true
crossorigin:
type: boolean
description: 'If true, the underlying <video> element will have
crossorigin="anonymous". This means that any videos or text tracks pulled into the player must have CORS headers.
*This feature should only be used if you know that all your content (video and text tracks) have CORS headers applied to them.*'
readOnly: true
css:
type: object
description: Object containing CSS color overrides
properties:
controlBarColor:
type: string
description: Background color of control bar
default: '{set by player template}'
controlColor:
type: string
description: Color of buttons and text in control bar
default: '{set by player template}'
progressColor:
type: string
description: Color of progress bar
default: '{set by player template}'
debugger:
type: boolean
description: If true, debugger shows player information in a modal window. See the [Player Information Modal document](https://player.support.brightcove.com/troubleshooting/brightcove-player-information-modal.html) for full information.
errors:
type: boolean
description: Indicates if the error messages plugin should be excluded
flash:
type: object
description: Can be used to provide custom Flash options to **Video.js**.
fullscreenControl:
type: boolean
description: Indicates whether the fullscreen control should be shown in the control bar
hls:
oneOf:
- type: boolean
description: If `false`, the player will not include **videojs-contrib-hls**
- type: object
description: If an object is passed, it will be used as options for **videojs-contrib-hls**
properties:
captionServices:
type: object
description: Used to rename 608 captions
properties:
CC1:
type: object
description: Properties of the captions to use for CC1
properties:
language:
type: string
description: The language of the captions
example: en
label:
type: string
description: Label to used for these captions in the player controls
example: English
CC2:
type: object
description: Properties of the captions to use for CC2
properties:
language:
type: string
description: The language of the captions
example: en
label:
type: string
description: Label to used for these captions in the player controls
example: English
parse708captions:
type: boolean
default: true
description: Set to false to hide 708 captions if the encoder is sending both 608 and 708
description: Handling of **videojs-contrib-hls** and renaming of 608 captions
default: {}
language:
type: string
description: Can be provided to set the lang attribute of the <code translate="No"><html></code> element.
default: undefined
languages:
type: array
description: Languages (2 letter abbreviations) you wish your player to support, from the video.js supported list
items:
type: string
enum:
- ar
- ba
- bg
- ca
- cs
- da
- de
- el
- en
- es
- fa
- fi
- fr
- gl
- he
- hr
- hu
- it
- ja
- ko
- nb
- nl
- nn
- pl
- pt-BR
- pt-PT
- ru
- sk
- sr
- sv
- tr
- uk
- vi
- zh-CN
- zh-TW
loop:
type: boolean
description: Indicates if the video should play over as soon as it ends
default: false
media:
type: object
description: Media information for non-Video Cloud media
properties:
sources:
type: array
description: Array of non-Video Cloud media sources
items:
type: object
properties:
height:
type: integer
description: Video frame height in pixels
width:
type: integer
description: Video frame width in pixels
poster:
type: object
description: Information for the poster image
properties:
highres:
type: string
description: The file path to the poster image, relative to the root directory of the skin
src:
type: string
description: The URL of the video file to load into the player
title:
type: string
description: Content of the `<title>` element of the page
type:
type: string
description: MIME type of the video, as specified in the HTML5 standard, for instance `video/mp4` form MP4 or `application/x-mpegURL` for HLS
enum:
- video/mp4
- application/x-mpegURL
src:
type: string
description: The URL of the video file to load into the player
tracks:
type: array
description: Array of text track objects for non-Video Cloud media
items:
type: object
properties:
label:
type: string
description: Text label for the track, for instance `English` for an English language text track
src:
type: string
description: URL to source of track, required in a track object
srclang:
type: string
description: 2 letter code (valid BCP 47 language tag) for the language of the text track
muted:
type: boolean
description: If `true`, the player will be muted when it loads
default: false
play_button:
type: object
description: Properties are available for modification of the play button via player configuration
properties:
hover:
type: string
description: '`glow` or `darken`; default is pink / progress color'
enum:
- glow
- darken
shape:
type: string
description: '`square` or `rectangle`; default is a circle'
enum:
- square
- rectangle
position:
type: string
description: '`topLeft` or `topRight`; default is center'
enum:
- topLeft
- topRight
player:
type: object
description: General settings for the player
properties:
inactive:
type: boolean
description: Whether the player is active (usable) or not
default: true
template:
type: object
description: Object containing details of the template the player is based on
properties:
name:
type: string
description: The template name
readOnly: true
version:
type: string
description: The player template version - note that you only need to be concerned about this if you have opted out of auto-updates for players. See [Opting Out of Automatic Player Updates](/player-management/guides/opting-out-automatic-player-updates.html) for more information.
example: 6.22.7
locked:
type: boolean
description: Whether the player is locked to prevent auto-updates to new template versions
default: false
player_id:
type: string
description: Same as the `id` - the <code translate="No">id</code> for the player is returned as <code translate="No">player_id</code> when you get the configuration by putting <code translate="No">config.json</code> on the end of the player preview URL (it is not returned at all when you get the configuration via the Player Management API, but it returned as `id` in some responses, such as the response to updating or publishing a player)..
readOnly: true
player_name:
type: string
description: Same as the `name` - the <code translate="No">name</code> you enter for the player is returned as <code translate="No">player_name</code> when you get the configuration by putting <code translate="No">config.json</code> on the end of the player preview URL
# --- truncated at 32 KB (44 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/brightcove/refs/heads/main/openapi/brightcove-players-api-openapi.yml