openapi: '3.0.0' x-bc-implicit-head: true x-bc-implicit-options: true x-bc-upstream: 'https://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