Brightcove Labels API

openapi: 3.2.0
info:
  title: Brightcove CMS API Reference Labels API
  description: 'Reference for the Brightcove CMS API, used to access and manage your media library. To test API requests, you can use our API Testing Tools. For permissions needed for OAuth credentials, see API Operations. For information on authenticating API requests, see the OAuth Overview.


    For additional in-depth guides to features of the API, see the **general documentation**.


    **Base URL**: https://cms.api.brightcove.com'
  version: 1.0.0
  x-bc-access: public
servers:
- url: https://cms.api.brightcove.com
  variables: {}
tags:
- name: Labels
  description: Operations for managing folders to organize your videos. See Working with Labels for more information.
paths:
  /v1/accounts/{{account_id}}/labels:
    post:
      tags:
      - Labels
      summary: Create a Label
      description: Create a new label for the account
      operationId: CreateLabel
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - $ref: '#/components/parameters/ContentType'
      - $ref: '#/components/parameters/Authorization'
      requestBody:
        description: Create a new label for the account
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LabelPath'
        required: true
      responses:
        '201':
          description: Label created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LabelPath'
        '401':
          description: 'UNAUTHORIZED: Authentication failed; check to make sure your client credentials were correct for the access token'
        '403':
          description: 'NOT_AVAILABLE: The resource you are requesting is temporarily unavailable'
        '404':
          description: 'RESOURCE_NOT_FOUND: The api could not find the resource you requested'
        '405':
          description: 'METHOD_NOT_ALLOWED: The HTTP method specified is not allowed for this endpoint'
        '429':
          description: 'TOO_MANY_REQUESTS: You are submitting too many simultaneous requests or too many requests per second'
        '500':
          description: 'UNKNOWN: Issue in Brightcove system; try again later.

            TIMEOUT: Server likely too busy; try again later.'
      deprecated: false
      security:
      - BC_OAuth2:
        - video-cloud/video/create
      x-operation-settings:
        CollectParameters: false
        AllowDynamicQueryParameters: false
        AllowDynamicFormParameters: false
        IsMultiContentStreaming: false
    get:
      tags:
      - Labels
      summary: Get Labels
      description: Gets list of labels for the account
      operationId: GetLabels
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - $ref: '#/components/parameters/Authorization'
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LabelsList'
        '401':
          description: 'UNAUTHORIZED: Authentication failed; check to make sure your client credentials were correct for the access token'
        '403':
          description: 'NOT_AVAILABLE: The resource you are requesting is temporarily unavailable'
        '404':
          description: 'RESOURCE_NOT_FOUND: The api could not find the resource you requested'
        '405':
          description: 'METHOD_NOT_ALLOWED: The HTTP method specified is not allowed for this endpoint'
        '429':
          description: 'TOO_MANY_REQUESTS: You are submitting too many simultaneous requests or too many requests per second'
        '500':
          description: 'UNKNOWN: Issue in Brightcove system; try again later.

            TIMEOUT: Server likely too busy; try again later.'
      deprecated: false
      security:
      - BC_OAuth2:
        - video-cloud/video/read
      x-operation-settings:
        CollectParameters: false
        AllowDynamicQueryParameters: false
        AllowDynamicFormParameters: false
        IsMultiContentStreaming: false
  /v1/accounts/{{account_id}}/labels/by_path/{{label_path}}:
    patch:
      tags:
      - Labels
      summary: Update a Label
      description: Update a label for the account
      operationId: UpdateLabel
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - $ref: '#/components/parameters/ContentType'
      - $ref: '#/components/parameters/Authorization'
      - $ref: '#/components/parameters/label_path'
      requestBody:
        description: Update a label for the account
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LabelUpdate'
        required: true
      responses:
        '201':
          description: Label updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LabelPath'
        '401':
          description: 'UNAUTHORIZED: Authentication failed; check to make sure your client credentials were correct for the access token'
        '403':
          description: 'NOT_AVAILABLE: The resource you are requesting is temporarily unavailable'
        '404':
          description: 'RESOURCE_NOT_FOUND: The api could not find the resource you requested'
        '405':
          description: 'METHOD_NOT_ALLOWED: The HTTP method specified is not allowed for this endpoint'
        '429':
          description: 'TOO_MANY_REQUESTS: You are submitting too many simultaneous requests or too many requests per second'
        '500':
          description: 'UNKNOWN: Issue in Brightcove system; try again later.

            TIMEOUT: Server likely too busy; try again later.'
      deprecated: false
      security:
      - BC_OAuth2:
        - video-cloud/video/create
      x-operation-settings:
        CollectParameters: false
        AllowDynamicQueryParameters: false
        AllowDynamicFormParameters: false
        IsMultiContentStreaming: false
    delete:
      tags:
      - Labels
      summary: Delete Label
      description: Delete a label
      operationId: deleteLabel
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - $ref: '#/components/parameters/Authorization'
      - $ref: '#/components/parameters/label_path'
      responses:
        '204':
          description: 204 No Content
        '401':
          description: 'UNAUTHORIZED: Authentication failed; check to make sure your client credentials were correct for the access token'
        '403':
          description: 'NOT_AVAILABLE: The resource you are requesting is temporarily unavailable'
        '404':
          description: 'RESOURCE_NOT_FOUND: The api could not find the resource you requested'
        '405':
          description: 'METHOD_NOT_ALLOWED: The HTTP method specified is not allowed for this endpoint'
        '429':
          description: 'TOO_MANY_REQUESTS: You are submitting too many simultaneous requests or too many requests per second'
        '500':
          description: 'UNKNOWN: Issue in Brightcove system; try again later.

            TIMEOUT: Server likely too busy; try again later.'
      deprecated: false
      security:
      - BC_OAuth2:
        - video-cloud/video/read
      x-operation-settings:
        CollectParameters: false
        AllowDynamicQueryParameters: false
        AllowDynamicFormParameters: false
        IsMultiContentStreaming: false
components:
  parameters:
    AccountId:
      description: Video Cloud account ID.
      explode: false
      in: path
      name: account_id
      required: true
      schema:
        type: string
      style: simple
    Authorization:
      description: 'Authorization: Bearer {access_token} - see [Getting Access Tokens](/oauth/code-samples/oauth-api-sample-get-access-token.html)'
      explode: false
      in: header
      name: Authorization
      required: true
      schema:
        type: string
      style: simple
    ContentType:
      description: 'Content-Type: application/json'
      example: application/json
      explode: false
      in: header
      name: Content-Type
      required: true
      schema:
        default: application/json
        type: string
      style: simple
    label_path:
      description: '''The path for a label to update or delete. Note that the operation performed is on the last item in the path, so for example, if you specify the path `/nature/birds/seabirds`, only the `seabirds` label will be updated/deleted, but if you specify the path as `/nature/birds`, `birds` and any sub-labels of `birds` will be updated/deleted.'''
      explode: false
      in: path
      name: label_path
      required: true
      schema:
        type: string
      style: simple
  schemas:
    LabelUpdate:
      description: Update Label request body
      title: label
      type: object
      properties:
        new_label:
          type: string
          description: The new label which will replace **the last item in the label path**
      example:
        new_label: forest_birds
    LabelsList:
      description: A list of labels for the account
      type: object
      properties:
        account_id:
          type: string
          description: The Video Cloud account id
          example: '57838016001'
        labels:
          type: array
          description: Array of labels that exist for the account
          items:
            type: string
            description: a full label path
          example:
          - /nature/birds
          - /nature/birds/shorebirds
          - /nature/birds/forestbirds
          - /nature/mammals/seamammals
        version:
          type: integer
          description: An internal version tracker
    LabelPath:
      description: The full path for a label that can be assigned to videos
      title: label
      type: object
      properties:
        path:
          type: string
      example:
        path: /nature/mammals/seamammals
  securitySchemes:
    BC_OAuth2:
      type: oauth2
      description: Brightcove OAuth API. See the [support documentation](/oauth/index.html) or [Getting Access Tokens](/oauth/code-samples/oauth-api-sample-get-access-token.html) to learn more
      flows:
        clientCredentials:
          tokenUrl: https://oauth.brightcove.com/v4/access_token
          scopes:
            video-cloud/video/read: Video Read
            video-cloud/video/create: Video Create
            video-cloud/video/update: Video Update
            video-cloud/video/delete: Video Delete
            video-cloud/video/all: Video ALL
            video-cloud/asset/delete: Digital Master Delete
            video-cloud/playlist/read: Playlist Read
            video-cloud/playlist/create: Playlist Create
            video-cloud/playlist/update: Playlist Update
            video-cloud/playlist/delete: Playlist Delete
            video-cloud/playlist/all: Playlist All
            video-cloud/sharing-relationships/read: Sharing Relationships Read
            video-cloud/sharing-relationships/create: Sharing Relationships Create
            video-cloud/sharing-relationships/update: Sharing Relationships Update
            video-cloud/sharing-relationships/delete: Sharing Relationships Delete
            video-cloud/sharing-relationships/all: Sharing Relationships All
            video-cloud/notifications/all: Notifications All
            video-cloud/video/clear-sources: Read clear sources
x-bc-implicit-head: true
x-bc-implicit-options: true
x-bc-upstream: https://backend_server