openapi: '3.0.0'
x-bc-implicit-head: true
x-bc-implicit-options: true
x-bc-upstream: 'http://backend_server'
info:
  description: |-
    API for Brightcove Social

    For additional in-depth guides to features of the API, see the **[Overview](/social/getting-started/overview-social-api.html)**.

    **Base URL:** https://edge.social.api.brightcove.com/v1
  version: 1.0.0
  title: Brightcove Social API
  x-bc-access: public
servers:
  - url: 'https://social.api.brightcove.com/v1'
    variables: {}
tags:
  - name: Status
    description: Operations for getting the status of all or a specific video.
  - name: History
    description: Operations for getting the history of all or a specific video.
paths:
  '/accounts/{account_id}/videos/status':
    get:
      tags:
        - Status
      summary: List the current status for every video on the account
      description: |-
        Gets the current status of every video Social has ever attempted to distribute to a social platform.  Note that this endpoint has pagination.
      operationId: getAccountVideosStatus
      security:
        - BC_OAuth2:
          - video-cloud/social/status/read
      parameters:
        - $ref: '#/components/parameters/AccountId'
        - $ref: '#/components/parameters/Platform'
        - $ref: '#/components/parameters/DestinationId'
        - $ref: '#/components/parameters/Status'
        - $ref: '#/components/parameters/Before'
        - $ref: '#/components/parameters/Since'
        - $ref: '#/components/parameters/PageKey'
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/PrettyPrint'
      responses:
        '200':
          description: A list of videos.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VideoList'
        '403':
          description: Forbidden
        '422':
          description: Invalid query parameters
        '500':
          description: Server error
  '/accounts/{account_id}/videos/{video_id}/status':
    get:
      tags:
        - Status
      summary: List the current status for the video.
      description: >-
        Gets the current status of the requested video for every Social Destination is has ever been distributed to.  Note that this endpoint has pagination.
      operationId: getAccountVideoStatus
      security:
        - BC_OAuth2:
          - video-cloud/social/status/read
      parameters:
        - $ref: '#/components/parameters/AccountId'
        - $ref: '#/components/parameters/VideoId'
        - $ref: '#/components/parameters/Platform'
        - $ref: '#/components/parameters/DestinationId'
        - $ref: '#/components/parameters/Status'
        - $ref: '#/components/parameters/Before'
        - $ref: '#/components/parameters/Since'
        - $ref: '#/components/parameters/PageKey'
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/PrettyPrint'
      responses:
        '200':
          description: A list of videos.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VideoList'
        '403':
          description: Forbidden
        '422':
          description: Invalid query parameters
        '500':
          description: Server error
  '/accounts/{account_id}/videos/history':
    get:
      tags:
        - History
      summary: List the lifetime social history for every video on the account.
      description: >-
        Gets the lifetime history of every video Social has ever attempted to distribute to a social platform.  Note that this endpoint has pagination.
      operationId: getAccountVideosHistory
      security:
        - BC_OAuth2:
          - video-cloud/social/status/read
      parameters:
        - $ref: '#/components/parameters/AccountId'
        - $ref: '#/components/parameters/Platform'
        - $ref: '#/components/parameters/DestinationId'
        - $ref: '#/components/parameters/Status'
        - $ref: '#/components/parameters/Before'
        - $ref: '#/components/parameters/Since'
        - $ref: '#/components/parameters/PageKey'
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/PrettyPrint'
      responses:
        '200':
          description: A list of videos.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VideoList'
        '403':
          description: Forbidden
        '422':
          description: Invalid query parameters
        '500':
          description: Server error
  '/accounts/{account_id}/videos/{video_id}/history':
    get:
      tags:
        - History
      summary: List the lifetime social history the video.
      description: >-
        Gets the lifetime history of the requested video for every Social Destination is has ever been distributed to.  Note that this endpoint has pagination.
      operationId: getAccountVideoHistory
      security:
        - BC_OAuth2:
          - video-cloud/social/status/read
      parameters:
        - $ref: '#/components/parameters/AccountId'
        - $ref: '#/components/parameters/VideoId'
        - $ref: '#/components/parameters/Platform'
        - $ref: '#/components/parameters/DestinationId'
        - $ref: '#/components/parameters/Status'
        - $ref: '#/components/parameters/Before'
        - $ref: '#/components/parameters/Since'
        - $ref: '#/components/parameters/PageKey'
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/PrettyPrint'
      responses:
        '200':
          description: A list of videos.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VideoList'
        '403':
          description: Forbidden
        '422':
          description: Invalid query parameters
        '500':
          description: Server error
components:
  schemas:
    Error:
      type: object
      properties:
        error_code:
          type: string
          description: The error code returned recorded by the server, from the social platform, if any.
        error_message:
          type: string
          description: The error message recorded by the server, or returned from the social platform, if any.
        platform_error:
          type: string
          description: JSON representation of the error object returned from the social platform, if any.
    Video:
      type: object
      properties:
        id:
          type: string
          description: Brightcove ID for the video
        account_id:
          type: string
          description: Brightcove ID of the account that owns this video
        destination_id:
          type: string
          description: >-
            Brightcove ID for the Social destination for which this status is
            reported
        remote_id:
          type: string
          description: Remote social platoforms ID for this video
        remote_url:
          type: string
          format: url
          description: >-
            URL to the video on the remote social platform. Optional. Only exists
            if the video has PUBLISHED or SYNCED status.
        status:
          type: string
          description: Socials last known status for the video on the remote platform
          enum:
            - PUBLISHED
            - DELETED
            - ERROR
            - HIDDEN
            - NOT_FOUND
            - SCHEDULED
            - SYNCED
            - ABANDONED
        timetamp:
          type: string
          format: date-time
          description: Timestamp at which this status was reported
        published_at:
          type: string
          format: date-time
          description: >-
            Timestamp at which the video was scheduled to be made visible on the remote social platform.  May be the same as `timestamp` if the video
            was to be made visible immediately.
        distribution_method:
          type: string
          description: >-
            The mechanism which initiated the operation that put the video in this status.  `SYNC` if the most recent video operation was initiated by an AutoSync.  `MANUAL` if the video was distribution manually through the Social Studio module.
          enum:
            - MANUAL
            - SYNC
        autosync_id:
          type: string
          description: >-
            Brightcove ID of the AutoSync that triggered this status.  Optional. Only exists if the `distribution_method` is `SYNC`
        error:
          $ref: '#/components/schemas/Error'
        warning:
          $ref: '#/components/schemas/Error'
        action:
          type: string
          description: >-
            The action attempted during this operation.
          enum:
            - UPLOAD
            - UPDATE_SYNC
            - UPDATE_UNSYNC
            - DELETE
        result:
          type: string
          description: >-
            The result of this operation.
          enum:
            - SUCCESS
            - ERROR
    VideoList:
      type: object
      properties:
        total_hits:
          type: integer
        page_key:
          type: string
        videos:
          type: array
          items:
            $ref: '#/components/schemas/Video'
      example: {
          "total_hits": 117,
          "page_key": "1506960062695:5382545592001_-T6xvfm_ebE",
          "videos": [
            {
              "id": "5667310879001",
              "account_id": "1486906377",
              "destination_id": "c1243033-fbfd-4f1d-80e4-00ed027db9ec",
              "remote_id": "hWESxu2PZFU",
              "remote_url": "https://www.youtube.com/watch?v=hWESxu2PZFU",
              "status": "PUBLISHED",
              "timestamp": "Jan 26, 2018 6:59:16 PM",
              "published_at": "Jan 26, 2018 6:59:16 PM",
              "distribution_method": "MANUAL",
              "action": "YOUTUBE_UPLOAD",
              "result": "SUCCESS"
            },
            {
              "id": "5263118111001",
              "account_id": "1486906377",
              "destination_id": "9b67c5f2-5fed-4b61-8383-7bb6e4456b8e",
              "remote_id": "1434615919981329",
              "remote_url": "https://www.facebook.com/1434615919981329",
              "status": "SYNCED",
              "timestamp": "Jan 24, 2018 3:35:24 PM",
              "published_at": "Jan 24, 2018 3:35:24 PM",
              "distribution_method": "SYNC",
              "autosync_id": "4d09778b-0043-4be6-8dd7-011863607f0c",
              "action": "FACEBOOK_UPDATE",
              "result": "SUCCESS"
            },
            {
              "id": "5363058704001",
              "account_id": "1486906377",
              "destination_id": "9b67c5f2-5fed-4b61-8383-7bb6e4456b8e",
              "status": "ERROR",
              "timestamp": "Dec 8, 2017 6:44:49 PM",
              "published_at": "Dec 8, 2017 6:44:49 PM",
              "distribution_method": "MANUAL",
              "errors": [
                {
                  "error_code": "UPLOAD_FAILURE",
                  "message": "Upload error: Received Facebook error response of type OAuthException: (#100) sponsor_id requires publishing profile/page to be verified or branding partner. (code 100, subcode null)"
                }
              ],
              "action": "FACEBOOK_UPLOAD",
              "result": "ERROR"
            },
            {
              "id": "5630023626001",
              "account_id": "1486906377",
              "destination_id": "69cac3e2-4e71-489f-86f4-c00ae7e9e235",
              "remote_id": "GcFEO8hEiw8",
              "remote_url": "https://www.youtube.com/watch?v=GcFEO8hEiw8",
              "status": "PUBLISHED",
              "timestamp": "Oct 31, 2017 3:49:02 PM",
              "published_at": "Oct 31, 2017 3:49:02 PM",
              "distribution_method": "MANUAL",
              "action": "YOUTUBE_UPLOAD",
              "result": "SUCCESS"
            },
            {
              "id": "5382545592001",
              "account_id": "1486906377",
              "destination_id": "7d6a1691-317e-4142-a59c-a2bbc28bf08d",
              "remote_id": "8z9uAFW24Zs",
              "remote_url": "https://www.youtube.com/watch?v=8z9uAFW24Zs",
              "status": "ABANDONED",
              "timestamp": "Oct 2, 2017 5:07:48 PM",
              "published_at": "Oct 2, 2017 5:07:48 PM",
              "distribution_method": "SYNC",
              "autosync_id": "83440ca9-ca3b-43d4-b75f-a606efe03433",
              "action": "YOUTUBE_UPDATE_UNSYNC",
              "result": "SUCCESS"
            },
            {
              "id": "5382545592001",
              "account_id": "1486906377",
              "destination_id": "7d6a1691-317e-4142-a59c-a2bbc28bf08d",
              "remote_id": "-T6xvfm_ebE",
              "remote_url": "https://www.youtube.com/watch?v=-T6xvfm_ebE",
              "status": "DELETED",
              "timestamp": "Oct 2, 2017 4:01:02 PM",
              "published_at": "Oct 2, 2017 4:01:02 PM",
              "distribution_method": "SYNC",
              "autosync_id": "83440ca9-ca3b-43d4-b75f-a606efe03433",
              "action": "YOUTUBE_DELETE",
              "result": "SUCCESS"
            }
          ]
        }
  parameters:
    AccountId:
      name: account_id
      in: path
      description: ID of the account to query video statuses for
      required: true
      schema:
        type: string
    VideoId:
      name: video_id
      in: path
      description: ID of the video to query video statuses for
      required: true
      schema:
        type: string
    Platform:
      name: platform
      in: query
      description: |-
        Limit the list of videos to a single social platform.  Valid values for this property are
        - YOUTUBE
        - FACEBOOK
        - TWITTER

        Note that this may conflict with `destination_id`, below.
      required: false
      schema:
        type: string
        enum:
          - YOUTUBE
          - FACEBOOK
          - TWITTER
    DestinationId:
      name: destination_id
      in: query
      description: >
        Limit the list of videos to a single Social destination, by it's ID. Note that this may conflict with `platform`, above. (e.g., Specifying `platform=YOUTUBE` and passing the ID of a Twitter destination will result in no statuses.)  Generally if you are passing a `destination_id` you probably don't want to be passing a `platform` as well, as destinations imply a platform.
      required: false
      schema:
        type: string
        format: uuid
    Status:
      name: status
      in: query
      description: |-
        Limit the list of videos to those with a specific status.  Valid values for this property are
          - DELETED
          - ERROR
          - HIDDEN
          - PROCESSING
          - PUBLISHED
          - SCHEDULED
          - SYNCED
          - ABANDONED
      schema:
        type: string
    Before:
      name: before
      in: query
      description: >-
        Limit the list of videos to those whose last status change occurred before the specified date time.  Can accept either a full timestamp, or just a datestamp.  If passed just a datestamp, assumes 00:00:00 for the time, and the filter will be exclusive of the date specified.
      required: false
      schema:
        type: string
        format: date-time
    Since:
      name: since
      in: query
      description: >-
        Limit the list of videos to those whose last status change occurred since the specified date time.  Can accept either a full timestamp, or just a datestamp.  If passed just a datestamp, assumes 00:00:00 for the time, and the filter will be inclusive of the date specified.
      required: false
      schema:
        type: string
        format: date-time
    PageKey:
      name: page_key
      in: query
      description: >-
        Fetch the next page of data.  If the previous call to this endpoint returned a `page_key`, a subsequent call can be made with the same parameters and including the `page_key` to retrieve the next page.
      required: false
      schema:
        type: string
    PageSize:
      name: page_size
      in: query
      description: >-
        The number of entries to fetch in the next page of data.  Must be a number between 1 and 100, inclusive.  Defaults to 20.
      required: false
      schema:
        type: integer
        format: int32
        minimum: 1
        maximum: 100
    PrettyPrint:
      name: pretty_print
      in: query
      description: >-
        Whether or not to pretty-print the JSON response.  Defaults to false.
      required: false
      schema:
        type: boolean
  securitySchemes:
    BC_OAuth2:
      type: oauth2
      description: >-
        Brightcove OAuth API. See the [support documentation](https://apis.support.brightcove.com/oauth/) or [Getting Access Tokens](https://apis.support.brightcove.com/oauth/guides/getting-access-tokens.html) to learn more
      flows:
        clientCredentials:
          tokenUrl: 'https://oauth.brightcove.com/v4/access_token'
          scopes:
            video-cloud/social/status/read: Read social sharing status and history
