support Contact Support | system status System Status
Page Contents

    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

    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

    Page last updated on 10 Aug 2020