Working with Folders

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.

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.