Skip to main contentIBM Video Streaming Developers

Basic video management

List the videos of the user

Returns data on the videos of the current user.

GET https://api.video.ibm.com/users/self/videos.json

Parameters

The query parameters for the GET request:

PARAMETERTYPEIMPORTANCEDESCRIPTION
pageintegerOPTIONALRequested page number (value is 1 by default)
pagesizeintegerOPTIONALRequested page size (value is 50 by default, max. 50)
qstringOPTIONALSearch for text in video related data. Only works for public videos, and if no filter parameter is set.
sortstringOPTIONALSet sorting order of the videos. Possible values: "recent" – orders based on the created_at field; "popular" – orders based on the views field. The default value is recent.
filter[protect]setOPTIONALFilter videos by protection levels. Values: public, private (default: empty). The values should be comma separated without whitespace included.

Success response

Upon success a response with HTTP status “200 OK” is returned with the following key-value pairs under a videos element.

The media_urls field is being deprecated. For video download URLs please see the Downloading videos section.

KEYTYPEDESCRIPTION
idstringUnique ID of the video
titlestringVideo title
descriptionstringVideo description
urlstringVideo URL
lengthstringVideo length in seconds
created_atnumberThe date and time when the video was created (Unix timestamp). By default, it has the same value as the added_at field, but it can be edited by channel admins to better reflect the real content creation date and time for the viewers.
added_atnumberThe date and time when the video was added (uploaded or recorded) to IBM Video Streaming (Unix timestamp)
file_sizestringVideo file size in bytes
viewsnumberNumber views on the video
thumbnailobjectA set of key-value pairs containing URLs of the thumbnail images. Attributes: default and various image sizes (e.g. image_112x63, … , image_320x180, image_640x360, image_1920x1080)
media_urlsobject(This field is being deprecated.)
caption_matchesarrayThis field is only present if the q parameter is used. The result set contains captions (as string value for a caption attribute) matching the search query along with their start and end time (values as numbers for start_sec and end_sec attributes). Only maximum of 100 matching captions are returned.

Example of a success response:

{
"videos": [
{
"id": "111",
"title": "Title of video",
"description": "Description of video",
"url": "http://video.ibm.com/recorded/111",
"length": "12345.123456",
"created_at": 1399388736,

The paging information can be found under the paging key. Example:

{
"paging": {
"previous": "https://api.video.ibm.com/CHANNEL_ID/videos.json?pagesize=PAGE_SIZE&page=PREVIOUS_PAGE",
"next": "https://api.video.ibm.com/channels/CHANNEL_ID/videos.json?pagesize=PAGE_SIZE&page=NEXT_PAGE"
}
}

Error responses

Possible error responses:

HTTP RESPONSE CODEERROR VALUEERROR CONDITIONS
401 Unauthorizedinvalid_tokenThe provided access token is missing, revoked, expired or malformed
503 Service UnavailableThere is a temporary error on the server which makes it impossible to serve the request

List the videos of a channel

Returns data of videos on a specific channel.

GET https://api.video.ibm.com/channels/{channel_id}/videos.json

Parameters

The query parameters for the GET request:

PARAMETERTYPEIMPORTANCEDESCRIPTION
pageintegerOPTIONALRequested page number (value is 1 by default)
pagesizeintegerOPTIONALRequested page size (value is 50 by default, max. 50)
qstringOPTIONALSearch for text in video related data. Only works for public videos, and if no filter parameter is set.
sortstringOPTIONALSet sorting order of the videos. Possible values: recent – orders based on the created_at field; popular – orders based on the views field. The default value is recent.
filter[protect]setOPTIONALFilter videos by protection levels. Values: public, private (default: public). The values should be comma separated without whitespace included.

Success response

Upon success a response with HTTP status “200 OK” is returned with the following key-value pairs under a videos element. The media_urls field is being deprecated. For video download URLs please see the Downloading videos section.

KEYTYPEDESCRIPTION
idstringUnique ID of the video
titlestringVideo title
descriptionstringVideo description
urlstringVideo URL
lengthstringVideo length in seconds
created_atnumberThe date and time when the video was created (Unix timestamp). By default, it has the same value as the added_at field, but it can be edited by channel admins to better reflect the real content creation date and time for the viewers.
added_atnumberThe date and time when the video was added (uploaded or recorded) to IBM Video Streaming (Unix timestamp)
file_sizestringVideo file size in bytes
viewsnumberNumber views on the video
thumbnailobjectA set of key-value pairs containing URLs of the thumbnail images. Attributes: default and various image sizes (e.g. image_112x63, … , image_320x180, image_640x360, image_1920x1080)
media_urlsobject(This field is being deprecated.)
caption matchesarrayThis field is only present if the q parameter is used. The result set contains captions (as string value for a caption attribute) matching the search query along with their start and end time (values as numbers for start_sec and end_sec attributes). Only maximum of 100 matching captions are returned.

Example of a success response:

{
"videos": [
{
"id": "111",
"title": "Title of video",
"description": "Description of video",
"url": "http://video.ibm.com/recorded/111",
"length": "12345.123456",
"created_at": 1399388736,

The paging information can be found under the paging key. Example:

{
"paging": {
"previous": "https://api.video.ibm.com/CHANNEL_ID/videos.json?pagesize=PAGE_SIZE&page=PREVIOUS_PAGE",
"next": "https://api.video.ibm.com/channels/CHANNEL_ID/videos.json?pagesize=PAGE_SIZE&page=NEXT_PAGE"
}
}

Error responses

Possible error responses:

HTTP RESPONSE CODEERROR VALUEERROR CONDITIONS
401 Unauthorizedinvalid_tokenThe provided access token is missing, revoked, expired or malformed
404 Not Foundnot_foundChannel does not exist
503 Service UnavailableThere is a temporary error on the server which makes it impossible to serve the request

Get video details

Returns data of a specific video.

GET https://api.video.ibm.com/videos/{video_id}.json

Parameters

The query parameters for the GET request:

PARAMETERTYPEIMPORTANCEDESCRIPTION
detail_levelstringOPTIONALVerbosity level. Possible values: minimal – The result set is limited to the id, title, owner, picture and locks fields. owner – Requires a valid access token, and it will also return more sensitive information about the channel (for example the DHLS link if this feature is available for you). If the channel is protected (see Security section), only minimal data can be retrieved without a valid access token.

Success response

Upon success a response with HTTP status “200 OK” is returned with the following key-value pairs under a videos element. Note that the media_urls field is being deprecated. For video download URLs please see the Downloading videos section.

KEYTYPEDESCRIPTION
idstringUnique ID of the video
titlestringVideo title
descriptionstringVideo description
urlstringVideo URL
lengthstringVideo length in seconds
created_atnumberThe date and time when the video was created (Unix timestamp). By default, it has the same value as the added_at field, but it can be edited by channel admins to better reflect the real content creation date and time for the viewers.
added_atnumberThe date and time when the video was added (uploaded or recorded) to IBM Video Streaming (Unix timestamp)
file_sizestringVideo file size in bytes
viewsnumberNumber views on the video
protectstringProtection level (visibility) of the video. Possible values: private or public
thumbnailobjectA set of key-value pairs containing URLs of the thumbnail images. Attributes: default and various image sizes (e.g. image_112x63, … , image_320x180, image_640x360, image_1920x1080)
media_urlsobject(This field is being deprecated.)
linksobject
links.channelobject
links.channel.hrefstring
links.channel.idstring
chaptersarray
tinyurlstring
schedule
ownerobjectA set of key-value pairs containing information about the owner with the following attributes: id, username, picture
owner.idstringThe user ID of the channel owner
owner.usernamestringThe username of the channel owner
owner.picturestringThe URL of the image
locksarray
locks.embedstring

Error responses

Possible error responses:

HTTP RESPONSE CODEERROR VALUEERROR CONDITIONS
401 UnauthorizedThe provided access token is missing, revoked, expired or malformed
404 Not Foundnot_foundVideo not found
503 Service UnavailableThere is a temporary error on the server which makes it impossible to serve the request

Modify video details

Change title, description or protection level of a video.

PUT https://api.video.ibm.com/videos/{video_id}.json

Parameters

The parameters for the PUT request:

PARAMETERTYPEIMPORTANCEDESCRIPTION
titlestringOPTIONALVideo title
descriptionstringOPTIONALVideo description
protectstringOPTIONALVideo protection level. Supported values: public, private

Success response

Upon success a response with HTTP status “200 OK” is returned.

Error responses

Possible error responses:

HTTP RESPONSE CODEERROR VALUEERROR CONDITIONS
400 Bad Requestinvalid_valueThe specified value is invalid or unsupported
401 Unauthorizedinvalid_tokenThe provided access token is missing, revoked, expired or malformed
403 Forbiddenlack_of_ownershipThe API user is not allowed to manage the given channel
404 Not Foundnot_foundVideo was not found
503 Service UnavailableThere is a temporary error on the server which makes it impossible to serve the request

Delete a video

Delete a video from the current account permanently.

DELETE https://api.video.ibm.com/videos/{video_id}.json

Parameters

This request has no parameters.

Success response

Upon success a response with HTTP status “200 OK” is returned.

Error responses

Possible error responses:

HTTP RESPONSE CODEERROR VALUEERROR CONDITIONS
401 Unauthorizedinvalid_tokenThe provided access token is missing, revoked, expired or malformed
403 Forbiddenlack_of_ownershipThe API user is not allowed to manage the given channel
404 Not Foundnot_foundVideo was not found
503 Service UnavailableThere is a temporary error on the server which makes it impossible to serve the request