Activate/Deactivate or Schedule Videos

This topic shows how to activate, deactivate, or schedule a video using the CMS API.

Introduction

There are several reasons why you might want to make a video unplayable until some time later. For example:

  • It is still being reviewed
  • It is a trailer for film that has not been released yet
  • It is part of a marketing campaign that has not begun or is over
  • It is part of news story not yet published

If you haven't yet put the video embed code in a public page or app, it cannot be viewed, of course, but there are ways a video can be accidentally published, the most obvious being that its tags or other properties fit a smart playlist that is published.

There are two ways to be sure that a Video Cloud video cannot be viewed:

  • Deactivate it
  • Schedule it to be playable at some time in the future

Both of these changes can be implemented through the Media module in Studio, but here we will cover how to implement them using the CMS API. Both of these actions are performed using a video update request.

Authentication

Requests to the CMS API require an authorization header which contain your access tokens. For details on how to obtain client credentials and use them to retrieve access tokens, see the Brightcove OAuth Overview.

You can create client credentials using the Studio admin pages or the OAuth API

You can also use the OAuth API directly to retrieve access tokens, or if you are using the Postman or Insomnia app or make your requests, see our tutorials on how to set these up to fetch access tokens:

The update video request

To update a video, send a PATCH request to

https://cms.api.brightcove.com/v1/accounts/account_id/videos/video_id

In general, the request body only needs to contain those fields you want to update, though you can include others as well with the current values. We will look at the request bodies for activation/deactivation and scheduling in the sections that follow.

Activate/Deactivate a video

A video is made active (viewable) or inactive (not viewable) by setting its state. By default, videos are ACTIVE once they are ingested (unless there are required fields that were omitted when the video was created, or uploaded using the Upload module).

To deactivate a video then, you just need to send the following request body with the update video request:

{
  "state": "INACTIVE"
}

You can verify that the video is now inactive by checking the state field in the API response

Sample response 
{
  "id": "1698990613556232930",
  "account_id": "57838016001",
  "ad_keys": null,
  "clip_source_video_id": null,
  "complete": true,
  "created_at": "2021-05-06T06:48:31.963Z",
  "created_by": {
    "type": "unknown"
  },
  "cue_points": [
  ],
  "custom_fields": {
  },
  "delivery_type": "dynamic_origin",
  "description": "Updated at: 2021-05-07T22:37:46.492Z",
  "digital_master_id": null,
  "duration": 41259,
  "economics": "AD_SUPPORTED",
  "folder_id": null,
  "geo": null,
  "has_digital_master": true,
  "images": {
    "poster": {
      "src": "https://cf-images.us-east-1.prod.boltdns.net/v1/jit/57838016001/1494916a-e8a7-45ac-882f-6e0aa3489846/main/1280x720/20s629ms/match/image.jpg",
      "sources": [
        {
          "src": "https://cf-images.us-east-1.prod.boltdns.net/v1/jit/57838016001/1494916a-e8a7-45ac-882f-6e0aa3489846/main/1280x720/20s629ms/match/image.jpg",
          "height": 720,
          "width": 1280
        }
      ]
    },
    "thumbnail": {
      "src": "https://cf-images.us-east-1.prod.boltdns.net/v1/jit/57838016001/1494916a-e8a7-45ac-882f-6e0aa3489846/main/160x90/20s629ms/match/image.jpg",
      "sources": [
        {
          "src": "https://cf-images.us-east-1.prod.boltdns.net/v1/jit/57838016001/1494916a-e8a7-45ac-882f-6e0aa3489846/main/160x90/20s629ms/match/image.jpg",
          "height": 90,
          "width": 160
        }
      ]
    }
  },
  "link": null,
  "long_description": null,
  "name": "Great Horned Owl",
  "original_filename": "greathornedowl.mp4",
  "projection": null,
  "published_at": "2021-05-06T06:48:31.963Z",
  "reference_id": "greathornedowl.mp4_1620283704192",
  "schedule": null,
  "sharing": null,
  "state": "INACTIVE",
  "tags": [
    "bird",
    "air",
    "nature"
  ],
  "text_tracks": [
  ],
  "updated_at": "2021-05-16T22:54:09.168Z",
  "updated_by": {
    "type": "api_key",
    "email": "rcrooks@brightcove.com"
  },
  "offline_enabled": false,
  "playback_rights_id": "primary"
}

To make the video active again, simply send another update video request with the request body:

{
  "state": "ACTIVE"
}

Schedule a video

The second way to make a video playable or unplayable is to use the schedule object in the video update request. The schedule object has two properties:

  • starts_at the ISO-8601 date-time when the video becomes playable (required)
  • ends_at the ISO-8601 date-time when the video is no longer playable (optional)

Here's a sample request body that makes a video playable at 6:00 AM (UTC) on 16 May 2021 and makes it unplayable again exactly one year later:

{
  "schedule": {
    "starts_at": "2021-05-16T06:00:00.000Z",
    "ends_at": "2022-05-16T06:00:00.000Z"
  }
}
Sample response 
{
  "id": "1698990613556232930",
  "account_id": "57838016001",
  "ad_keys": null,
  "clip_source_video_id": null,
  "complete": true,
  "created_at": "2021-05-06T06:48:31.963Z",
  "created_by": {
    "type": "unknown"
  },
  "cue_points": [
  ],
  "custom_fields": {
  },
  "delivery_type": "dynamic_origin",
  "description": "Updated at: 2021-05-07T22:37:46.492Z",
  "digital_master_id": null,
  "duration": 41259,
  "economics": "AD_SUPPORTED",
  "folder_id": null,
  "geo": null,
  "has_digital_master": true,
  "images": {
    "poster": {
      "src": "https://cf-images.us-east-1.prod.boltdns.net/v1/jit/57838016001/1494916a-e8a7-45ac-882f-6e0aa3489846/main/1280x720/20s629ms/match/image.jpg",
      "sources": [
        {
          "src": "https://cf-images.us-east-1.prod.boltdns.net/v1/jit/57838016001/1494916a-e8a7-45ac-882f-6e0aa3489846/main/1280x720/20s629ms/match/image.jpg",
          "height": 720,
          "width": 1280
        }
      ]
    },
    "thumbnail": {
      "src": "https://cf-images.us-east-1.prod.boltdns.net/v1/jit/57838016001/1494916a-e8a7-45ac-882f-6e0aa3489846/main/160x90/20s629ms/match/image.jpg",
      "sources": [
        {
          "src": "https://cf-images.us-east-1.prod.boltdns.net/v1/jit/57838016001/1494916a-e8a7-45ac-882f-6e0aa3489846/main/160x90/20s629ms/match/image.jpg",
          "height": 90,
          "width": 160
        }
      ]
    }
  },
  "link": null,
  "long_description": null,
  "name": "Great Horned Owl",
  "original_filename": "greathornedowl.mp4",
  "projection": null,
  "published_at": "2021-05-06T06:48:31.963Z",
  "reference_id": "greathornedowl.mp4_1620283704192",
  "schedule": {
    "ends_at": "2022-05-16T06:00:00.000Z",
    "starts_at": "2021-05-16T06:00:00.000Z"
  },
  "sharing": null,
  "state": "ACTIVE",
  "tags": [
    "bird",
    "air",
    "nature"
  ],
  "text_tracks": [
  ],
  "updated_at": "2021-05-17T00:42:45.172Z",
  "updated_by": {
    "type": "api_key",
    "email": "rcrooks@brightcove.com"
  },
  "offline_enabled": false,
  "playback_rights_id": "primary"
}