Working with Folders

In this topic, you will learn how to add folders to your Video Cloud media library, and add videos to folders using the CMS API.

Introduction

Folders can be created used to organize videos in your video library. You may choose to organize videos by subject, author, product, region, etc. Having videos in folders makes them easier to manage in an account with hundreds or thousands of videos.

Get credentials for the CMS API

To use the CMS API you will need proper credentials.

The easiest way to get credentials in most cases is through the Studio Admin API Authentication section (requires admin permissions on your account). See Managing API Authentication Credentials for details. In this case, the permissions you need are for videos - you need both read and write permissions:

Sharing Relationship Permissions
Sharing Relationship Permissions

If the permissions you need are not available in Studio, or if you prefer to get them directly from the OAuth API, use your choice of the Get Client Credentials documents listed below. Whichever option you choose, you will need to ask for the correct operation permissions. The following can be used with cURL or Postman to get the proper permissions:

           "operations": [
           "video-cloud/videos/read",
           "video-cloud/videos/create",
           "video-cloud/videos/update"]

Creating folders

Here is the information you need to create a new folder.

Request URL

Make a POST request to:

      https://cms.api.brightcove.com/v1/accounts/account_id/folders

Request body

      {
        "name": folder_name
      }

Response

The response will look like this:

      {
        "id": "5a183efb10ab344b53775441",
        "account_id": "57838016001",
        "created_at": "2017-11-24T15:47:07.867Z",
        "name": "places",
        "updated_at": "2017-11-24T15:47:07.867Z",
        "video_count": 0
      }

The folder id and name (the name you set in the request body) are important, as you will need both to add a video to the folder. Don't worry if you forget the id, however, because you can always get this information again by getting the folders for the account.

Get folders

To get an array of the folders for an account, just make a GET request to:

      https://cms.api.brightcove.com/v1/accounts/account_id/folders

The response will look like this:

      [
        {
          "id": "5a17275782aca45b631295f9",
          "account_id": "57838016001",
          "created_at": "2017-11-23T19:53:59.687Z",
          "name": "birds",
          "updated_at": "2017-11-23T20:06:24.537Z",
          "video_count": 1
        },
        {
          "id": "560039e5e4b0e69e4b01cacd",
          "account_id": "57838016001",
          "created_at": "2015-09-21T17:09:57.260Z",
          "name": "fish",
          "updated_at": "2017-11-02T19:03:40.751Z",
          "video_count": 4
        },
        {
          "id": "5a183efb10ab344b53775441",
          "account_id": "57838016001",
          "created_at": "2017-11-24T15:47:07.867Z",
          "name": "places",
          "updated_at": "2017-11-24T15:47:07.867Z",
          "video_count": 0
        },
        {
          "id": "560039f1e4b0e69e4b01cad3",
          "account_id": "57838016001",
          "created_at": "2015-09-21T17:10:09.422Z",
          "name": "water",
          "updated_at": "2015-09-21T17:22:52.935Z",
          "video_count": 7
        }
      ]

Add video to folder

To add a video to a folder, make a PUT request to:

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

Request body

There is no request body for this operation.

Response

The response to this request will be 204 NO CONTENT.

Remove video from folder

To remove a video from a folder, make a DELETE request to the same URL as you use to add a video:

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

Request body

For this request, you must also include the folder name in the request body:

      {
        "name": folder_name
      }

Get videos in a folder

To get the videos in a folder, make a GET request to:

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

Request parameters

limit and offset

By default, this request returns the 20 videos most recently added to the folder. You can change this, and page through results for a folder that contains many videos, by adding one or both of these parameters to the request:

  • limit: the number of videos to return (default: 20; maximum: 100)
  • offset: the number of videos to skip (default: 0)

For example, this request will return videos 21-30 of the possible results (assuming the folder contains that many videos):

https://cms.api.brightcove.com/v1/accounts/:account_id/folders/folder_id/videos?limit=10&offset=20

sort

You can also sort the videos that are returned by using the sort parameter, setting it equal to any of these fields:

  • name
  • reference_id
  • updated_at
  • created_at
  • published_at
  • schedule_starts_at
  • schedule_ends_at
  • state
  • plays_total
  • plays_trailing_week

To sort in descending order, preface the field value with a minus sige (-created_at).

The default value for sort is -updated_at.