Media Sharing with the CMS API

Product(s)
Video Cloud
Role(s)
API Developer
Task(s)
Add Videos/Assets
Manage Videos
Topic(s)
Media Sharing
API(s)
CMS API

In this topic, you will learn how to share videos from one Video Cloud account to another using the CMS API.

Introduction

Media sharing is a feature of Video Cloud that lets publishers share videos with other publishers, enabling you to more easily manage videos across multiple accounts. For example, publishers can keep a Master account of video content and then share videos out to other divisions or subsidiaries of the organization.

Note that all media sharing operation can be performed in Studio as well. See Managing Media Sharing Settings.

Shared media & billing

We often get questions on how media that is shared between publishers affects billing. Below are a few scenarios that explain how billing is handled for content that is shared between publishers.

Scenario 1

  • Pub A and Pub B with content on Brightcove CDN
  • Pub A shares to Pub B
  • Pub B pays Brightcove for streams and bandwidth

Scenario 2

  • Pub A using BYO CDN
  • Pub B on Brightcove CDN OR BYO CDN (doesn't matter)
  • Pub A shares to Pub B
  • Pub B pays Brightcove for streams; Pub A pays their own CDN for bandwidth

Scenario 3

  • Pub A with content on Brightcove CDN
  • Pub B using BYO CDN
  • Pub A shares to Pub B
  • Pub B pays Brightcove for streams and bandwidth assuming that the billing parameters are being passed.

Terminology

In media sharing, there is a relationship between a Master account (that shares videos) and one or more Affiliate accounts (that receive shared videos) involved:

Media Sharing Terminology
Account Description
Master The account that created the original video.

The Master owns the content and is responsible for setting up, managing and providing content to Affiliates.

Affiliate The account that is receiving the video.

The Affiliate can accept content shared to it from a Master.

Channel A pipeline through which content is shared from a Master to any number of Affiliates. When media sharing is enabled a default channel will be created in your account.
Relationship Describes the interaction between a Master and an Affiliate.

A relationship is comprised of a Master to share content, a Channel through which content is shared, a Contract for accepting content, and an Affiliate to receive content.

Contract Describes sharing relationship between a Master and an Affiliate.

A contract is created by the Master, and then must be accepted for sharing to be enabled. The Affiliate can also specify whether shared videos are accepted automatically or must be approved one by one.

Base URL

As for all CMS API requests, the base URL for the operations discussed below is:

https://cms.api.brightcove.com/v1

All endpoints discussed below will be appended to the base URL when you make requests.

Authentication

Authentication for requests requires an Authorization header:

    Authorization: Bearer {access_token}

The access_token is a temporary OAuth2 access token that must be obtained from the Brightcove OAuth service. For details on how to obtain client credentials and use them to retrieve access tokens, see the Brightcove OAuth Overview.

Note that all operations around relationships required new permissions:

video-cloud/video/all
video-cloud/sharing-relationships/read
video-cloud/sharing-relationships/create
video-cloud/sharing-relationships/update
video-cloud/sharing-relationships/delete

Alternatively, you can just use:

video-cloud/sharing-relationships/all

In the Studio API Authentication Admin page, two permissions are shown:

  • Sharing Read (equivalent to video-cloud/sharing-relationships/read)
  • Sharing Read/Write (equivalent to video-cloud/sharing-relationships/all)

Restrictions on sharing

By default, all videos can be shared. You can, however, prevent sharing if:

  • The affiliate account does not a have a custom field for which a value is set on the video in the master account
  • The master account has geo-filtering enabled, but the affiliate account does not

Custom field matching

You can enforce custom field matching for a channel, which means that video shares will fail if the video has values for custom fields that are not present in the affiliate account. Videos will still share successfully if the video does not have values for any non-matching custom fields

By default, custom field matching is not enforced.

If a video share fails because of non-matching custom fields, you will see an error like this in the response:

{
  "video_id": "5691312273001",
  "affiliate_id": "47509719001",
  "affiliate_video_id": null,
  "status": "PROCESSING",
  "error_message": [{"error_code":"MISSING_CUSTOM_FIELDS","error_message":"Affiliate account is missing custom fields: [subject]"}],
  "shared_at": "2018-01-03T16:29:19.080Z",
  "updated_at": "2018-01-03T16:29:19.080Z"
}

Geo-filtering matching

If geo-filtering matching is enabled for a channel, videos cannot be shared if the master account has geo-filtering enabled and the affiliate account does not.

By default, geo-filtering matching is enforced.

The error will look like this:

{
  "video_id": "5691312273001",
  "affiliate_id": "47509719001",
  "affiliate_video_id": null,
  "status": "PROCESSING",
  "error_message": [{"error_code":"CONFLICT","error_message":"Affiliate account is not configured for geo restriction."}],
  "shared_at": "2018-01-03T16:29:19.080Z",
  "updated_at": "2018-01-03T16:29:19.080Z"

See Update channel below to see how you update a channel to enforce custom field and/or geo-filtering matching.

What is shared?

This section explains what gets shared, and how subsequent changes to the video are handled.

When the video is shared

Most of the video metadata fields are copied from the Master to the Affiliate account when the video is shared. The notable exceptions are:

  • id - the video will have its own unique id in the Affiliate account
  • date fields such as created_at and updated_at

All the video assets (renditions, images, text_tracks, etc.) are used by the Affiliate accounts for playback.

After the video is shared

After the video has been shared, some changes to the video in the Master account are automatically inherited by the Affiliate accounts, and some are not.

Video assets

Except for images, Master changes to the video assets are always inherited by Affiliates. Affiliates cannot change assets such as renditions, manifests, text tracks, or the digital master.

Changes to images by the Master are inherited by the Affiliate unless the Affiliate has replaced the image(s). Once an Affiliate changes an image, that image will no longer be inherited from the Master.

Video metadata

Any video metadata (such as the name, description, and reference id) can be modified by the Affiliate, and changes made on the Master video are not inherited by the Affiliate.

Resharing videos

Note, however, that if the Master re-shares the video (this can only be done through the CMS API, not in Studio), all assets and metadata (aside from data/time fields) will be shared to Affiliates, overwriting any changes the Affiliates have made.

Overview of media sharing steps

Setting up a relationship

Below is a summary of the operations for setting up a relationship (click on the operation name for more details):

Setup Operations
Master operations
Operation Method/Endpoint Description
List channels GET /accounts/ master_account_id/channels Get a list of channels for the account
Get channel details GET /accounts/ master_account_id/channels/ channel_name [2-1] Get details of a channel
Update channel POST /accounts/ master_account_id/channels/ channel_name Update channels settings
List channel affiliates GET /accounts/ master_account_id/channels/default/members Get the affiliates for a channel
Add affiliates PUT /accounts/ master_account_id/channels/default/members Add affiliates to a channel
Remove affiliate DELETE /accounts/ master_account_id/channels/default/members/ affiliate_account_id Removes an affiliate from a channel
Affiliate operations
Operation Method/Endpoint Description
List available contracts GET /accounts/ affiliate_account_id/contracts Gets all contracts available to the account
Get contract for a specific account GET /accounts/ affiliate_account_id/contracts/ master_account_id Gets a contract, if any, from a specific account
Approve a contract PATCH /accounts/ affiliate_account_id/contracts/ master_account_id Accept and configure acceptance conditions of contract

Notes

  • [2-1] Currently there is only one channel named default

Sharing videos

Video sharing operations are performed by the Master account. The Affiliate account can accept the share (if auto_accept is set to false) and can update shared video metadata and images using the standard Update Video operation.

Here are the sharing operations that can be performed once a relationship is set up (click on an operation name for more details):

Sharing Operations
Master operations
Operation Method/Endpoint Description
List existing shares GET /accounts/ master_account_id/videos/ video_id/shares Get a list of existing shares for a video - this is important because of the consequences of re-sharing a video when it has already be shared
Share a video POST /accounts/ master_account_id/videos/ video_id/shares Share a video to one or more affiliates - note that if the video has already been shared, this operation will re-share it - that is probably not what you want to do
Un-share a video for an Affiliate DELETE /accounts/ master_account_id/videos/ video_id/shares Un-shares a video for a specific Affiliates - note that un-sharing and re-sharing will result in the shared video having a new video id in the Affiliate account
Affiliate operations
Operation Method/Endpoint Description
Accept a shared video PATCH /accounts/ affiliate_account_id/videos/ video_id Accept a shared video (if auto_accept is turned off)

CMS API requests - setup

This section lists the CMS API operations involved in setting up media sharing.

Master operations

List channel(s)

List Channels
Method GET
Endpoint /accounts/ master_account_id/channels
Request body  
Sample response
[
	{
		"account_id": "57838016001",
		"name": "default",
		"enforce_custom_fields": false,
		"enforce_geo": false,
		"account_name": "BrightcoveLearning",
		"created_at": "2017-08-23T17:11:18.474Z",
		"updated_at": "2017-08-23T17:11:18.474Z"
	}
]

Get channel details

Get channel details
Method GET
Endpoint https://cms.api.brightcove.com/v1/accounts/ master_account_id/channels/ channel_name [5-1]
Request body  
Sample response
{
  "account_id": "57838016001",
  "name": "default",
  "enforce_custom_fields": false,
  "enforce_geo": false,
  "account_name": "BrightcoveLearning",
  "created_at": "2017-08-23T17:11:18.474Z",
  "updated_at": "2017-08-23T17:11:18.474Z"
}
Notes
  • [5-1] Currently there is only one channel named default

Update channel

Create Channel
Method PATCH
Endpoint /accounts/ master_account_id/channels/ channel_name [6-1]
Request body
{
	"enforce_custom_fields" : true,
	"enforce_geo" : true
}
Sample response
{
	"account_id": "57838016001",
	"name": "default",
	"enforce_custom_fields": true,
	"enforce_geo": true,
	"account_name": "BrightcoveLearning",
	"created_at": "2017-08-23T17:11:18.474Z",
	"updated_at": "2017-12-30T15:06:27.015Z"
}
Notes
  • [6-1] Currently there is only one channel named default

List affiliates for channel

List Channel Affiliates
Method GET
Endpoint /accounts/ master_account_id/channels/default/members
Request body  
Sample response
[
	{
		"account_id": "20318290001",
		"approved": false,
    "account_name": "Brightcove Training"
	},
	{
		"account_id": "1485884786001",
		"approved": true,
    "account_name": "Brightcove Learning Doc Samples"
	},
	{
		"account_id": "1752604059001",
		"approved": true,
    "account_name": "BC Training Videos"
	}
]

The value of the approved field indicates whether or not the Affiliate has approved the contract.

Add affiliate to channel

Add Affiliate
Method PUT
Endpoint /accounts/ master_account_id/channels/default/members/ affiliate_account_id
Request body
{
  "account_id":"affiliate_account_id"
}
Sample response
{
	"account_id": "1485884786001"
}

Remove affiliate from channel

Remove Affiliate
Method DELETE
Endpoint /accounts/ master_account_id/channels/default/members/ affiliate_account_id
Request body  
Sample response 204 NO CONTENT (empty response body)

Affiliate operations

List available contracts

List Contracts
Method GET
Endpoint /accounts/ affiliate_account_id/contracts
Request body  
Sample response
[
	{
		"account_id": "1485884786001",
		"channel": {
			"account_id": "57838016001",
			"name": "default"
		},
		"approved": false,
		"auto_accept": false,
		"approved_at": null,
		"updated_at": "2017-08-23T17:45:41.556Z",
		"created_at": "2017-08-23T17:45:41.556Z"
	}
]

The two essential fields in the response are:

  • approved - when set to true, the contract is accepted by the Affiliate
  • auto-accept - when set to true, videos shared through this contract will be automatically accepted by the Affiliate; otherwise, they must be approved one by one

We will see how to update the contract below.

Get contract for a specific account

Get Contract
Method GET
Endpoint /accounts/ affiliate_account_id/contracts/ master_account_id
Request body  
Sample response
{
	"account_id": "1485884786001",
	"channel": {
		"account_id": "57838016001",
		"name": "default"
	},
	"approved": false,
	"auto_accept": false,
	"approved_at": null,
	"created_at": "2017-08-23T17:45:41.556Z",
	"updated_at": "2017-08-23T17:45:41.556Z"
}

Approve contract

Approve Contract
Method PATCH
Endpoint /accounts/ affiliate_account_id/contracts/ master_account_id
Request body
{
  "approved": true,
  "auto_accept": true
}
Sample response
{
	"account_id": "1485884786001",
	"channel": {
		"account_id": "57838016001",
		"name": "default"
	},
    "approved": true,
	"auto_accept": true,
	"approved_at": "2017-08-27T12:27:21.582Z",
	"created_at": "2017-08-23T17:45:41.556Z",
	"updated_at": "2017-08-27T12:27:21.582Z"
}

If you include only "approved":true, each video will have to be approved individually.

CMS API requests - sharing

This section details the CMS API requests used in sharing videos. Media sharing operations are performed by the Master account. The Affiliate account can accept shares if auto_accept is turned off.

Master operations

List existing shares

To find out if a video has already been shared to other accounts, you can use the request below.

List Shares
Method GET
Endpoint /accounts/ master_account_id/videos/ video_id/shares
Request body  
Sample response
[
	{
		"video_id": "5553744346001",
		"affiliate_id": "1752604059001",
		"affiliate_video_id": "5553754248001",
		"status": "COMPLETE",
		"shared_at": "2017-08-27T14:35:01.890Z",
		"updated_at": "2017-08-27T14:35:25.630Z"
	},
	{
		"video_id": "5553744346001",
		"affiliate_id": "1485884786001",
		"affiliate_video_id": "5553758415001",
		"status": "COMPLETE",
		"shared_at": "2017-08-27T14:34:34.919Z",
		"updated_at": "2017-08-27T14:35:25.212Z"
	}
]

Sharing (or resharing) a video

The request described below will share a video to one or more Affiliate accounts.

Share Video
Method POST
Endpoint /accounts/ master_account_id/videos/ video_id/shares
Request body
[
  { "id": "affiliate_account_id_1" },
  { "id": "affiliate_account_id_2" }
]
Sample response

Success response

[
	{
		"video_id": "5553744346001",
		"affiliate_id": "1485884786001",
		"affiliate_video_id": null,
		"status": "PROCESSING",
		"shared_at": "2017-08-27T14:25:55.710Z",
		"updated_at": "2017-08-27T14:25:55.710Z"
	}
]

Failure response

{
"video_id": "5553744346001",
"affiliate_id": "1485884786001",
"affiliate_video_id": null,
"status": "ERROR",
"error_message": "[{\"error_code\":\"MISSING_CUSTOM_FIELDS\",\"error_message\":\"Affiliate account is missing custom fields: [myfieldname]\"}]",
"shared_at": "2017-10-23T15:21:38.541Z",
"updated_at": "2017-10-23T15:22:58.519Z"
}

Sharing will create a new video in the Affiliate's account. The state of the video share will be PROCESSING until the share is complete and the video is created in the Affiliate account. The Affiliate may still need to accept the video (if auto_accept is set to false on the contract by the Affiliate - see the previous section on setting up sharing).

Unsharing a video for an Affiliate

Unshare Video
Method DELETE
Endpoint /accounts/ master_account_id/videos/ video_id/shares/ affiliate_account_id
Request body  
Sample response 202 ACCEPTED (empty response body) - the response indicates that the request has been accepted for processing, but the operation may not be completed for a couple of minutes

Affiliate operations

Accept shared video

To accept a shared video, the Affiliate updates the shared video, setting its state to ACTIVE. (Setting the state to INACTIVE rejects the share.)

Accept Shared Video
Method PATCH
Endpoint /accounts/ affiliate_account_id/videos/ affiliate_video_id
Request body

	{
	  "state": "ACTIVE"
	}
Sample response
{
	"id": "5557656136001",
	"account_id": "1485884786001",
	"ad_keys": null,
	"clip_source_video_id": null,
	"complete": true,
	"created_at": "2017-08-30T13:35:51.796Z",
	"cue_points": [
	],
	"custom_fields": {
	},
	"delivery_type": "dynamic_origin",
	"description": null,
	"digital_master_id": "4728546275001",
	"duration": 11111,
	"economics": "AD_SUPPORTED",
	"folder_id": null,
	"geo": null,
	"has_digital_master": true,
	"images": {
		"thumbnail": {
			"asset_id": "5473683978001",
			"remote": false,
			"src": "http://brightcove.vo.llnwd.net/e1/pd/57838016001/57838016001_5473683978001_4728519374001-th.jpg?pubId=1485884786001&videoId=5557656136001",
			"sources": [
				{
					"src": "http://brightcove.vo.llnwd.net/e1/pd/57838016001/57838016001_5473683978001_4728519374001-th.jpg?pubId=1485884786001&videoId=5557656136001",
					"height": 90,
					"width": 160
				},
				{
					"src": "https://brightcove.hs.llnwd.net/e1/pd/57838016001/57838016001_5473683978001_4728519374001-th.jpg?pubId=1485884786001&videoId=5557656136001",
					"height": 90,
					"width": 160
				}
			]
		},
		"poster": {
			"asset_id": "5473684427001",
			"remote": false,
			"src": "http://brightcove.vo.llnwd.net/e1/pd/57838016001/57838016001_5473684427001_4728519374001-vs.jpg?pubId=1485884786001&videoId=5557656136001",
			"sources": [
				{
					"src": "http://brightcove.vo.llnwd.net/e1/pd/57838016001/57838016001_5473684427001_4728519374001-vs.jpg?pubId=1485884786001&videoId=5557656136001",
					"height": 720,
					"width": 1280
				},
				{
					"src": "https://brightcove.hs.llnwd.net/e1/pd/57838016001/57838016001_5473684427001_4728519374001-vs.jpg?pubId=1485884786001&videoId=5557656136001",
					"height": 720,
					"width": 1280
				}
			]
		}
	},
	"link": null,
	"long_description": null,
	"name": "oystercatcher.mp4",
	"original_filename": "57838016001_4728546275001_4728519374001.mp4",
	"projection": null,
	"published_at": "2017-08-30T13:41:13.974Z",
	"reference_id": "2016-01-29T21:41:33.225Z-screencast-1280",
	"schedule": null,
	"sharing": {
		"by_external_acct": true,
		"by_id": "57838016001",
		"source_id": "4728519374001",
		"to_external_acct": false,
		"by_reference": true
	},
	"state": "ACTIVE",
	"tags": [
		"newtag",
		"foo"
	],
	"text_tracks": [
	],
	"updated_at": "2017-08-30T13:41:14.075Z"
}

Set the state to INACTIVE to reject the share.

Note that there is no special notification indicating that a video has been shared to your account. However, if you search videos for state:pending, that will find any unaccepted shares. Alternatively, you can use the Shares Pending list in the Studio Media module to see and accept/reject pending shares:

Pending Shares
Pending Shares

Errors

Media sharing errors are not returned as a separate error response to the API request, but rather in an error_message field in the normal response:

[
  {
    "video_id" : "1239817239128",
    "affiliate_id" : "32871239",
    "affiliate_video_id" : "30308254055202",
    "status" : "COMPLETE",
    "shared_at" : "2017-12-11T17:57:45.530Z",
    "updated_at" : "2017-12-11T18:03:32.789Z",
    "error_message" : "[{"error_code":"MISSING_CUSTOM_FIELDS","error_message":"Affiliate account is missing custom fields: [whisky]"}]"
  }
]

See the CMS API Error Reference for more details.

Limitations

Currently, media sharing has the following limitations:

  • DRM: media sharing via the CMS API is currently not supported for DRM-enabled accounts.
  • If the channel defined by the master account has set enforce_custom_fields to true, and then shares a video that has a custom field with a value that is not allowed by the affiliate account, that share attempt will fail. The share status will be updated with an error message something like this:

    [{"error_code": "ILLEGAL_CUSTOM_FIELD_VALUE", "error_message": "Illegal value for custom fields: [topic]"}]
    

    If the channel defined by the master account has set enforce_custom_fields to false, and then shares a video that has a custom field with a value that is not allowed by the affiliate account, then the share attempt will work, but the field with the bad value will not be included on the affiliate copy of the video.