Skip to main contentIBM Video Streaming Developers

Basic channel management

Get list of the user’s channels

Get a detailed list of the user’s channels with information on various settings.

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

Parameters

The parameters for the GET request:

PARAMETERTYPEIMPORTANCEDESCRIPTION
qstringOPTIONALSearch for text in channel related data
pintegerOPTIONALRequested page number (1 by default)
pagesizeintegerOPTIONALRequested page size (100 by default)

Success response

Upon success, a set of key-value pairs is returned under a channel element.

KEYTYPEDESCRIPTION
idstringIdentifier of the channel
titlestringTitle of the channel
urlstringLong web URL of the channel: https://video.ibm.com/channel/{channel_id}
broadcast_urlsarrayArray of RTMP URLs (strings) where the client can broadcast. Client should fall-back to the second/third one if provided and the previous element seems to be failing. Provided only in case client explicitly asks for it through a broadcaster detail_level query parameter.
statusstringPossible values: online or offline. online means that the stream is viewable on the IBM Video Streaming website.
descriptionstringChannel description
defaultbooleanKey is returned with true value if this is the default channel for the user.
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
authorityobjectA set of key-value pairs containing information about the authority of the user to access the channel. Includes the following attributes: reason
authority.reasonstringPossible values are: own, shared
pictureobjectA set of key-value pairs, each parameter corresponding to an image size (defined in the key). Values are the image URLs.
live_thumbnailstringListed when the channel is online

Example of pagination data in success response:

{
"paging": {
"previous": {
"href": "https://api.video.ibm.com/users/self/channels.json?pagesize=PAGESIZE&p=PREVIOUS_PAGE"
},
"actual": {
"href": "https://api.video.ibm.com/users/self/channels.json?pagesize=PAGESIZE&p=PAGE"
},
"next": {

The previous and next elements are optional.

Error responses

Possible error responses:

HTTP RESPONSE CODEERROR VALUEERROR CONDITIONS
401 UnauthorizedThe 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

Get channel details

Get information on channel settings.

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

Parameters

The parameters for the GET request:

PARAMETERTYPEIMPORTANCEDESCRIPTION
detail_levelstringOPTIONALVerbosity level. Possible values: minimal, owner. In case of the minimal verbosity level, the result set is limited to the id, title, owner, picture and locks fields. If the channel is protected (see Security section), only minimal data can be retrieved without a valid access token. The owner detail level always 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).

Success response

Upon success a set of key-value pairs is returned under a channel element.

NAMETYPEDESCRIPTION
idstringIdentifier of the channel
titlestringTitle of the channel
pictureobjectA set of key-value pairs, each parameter corresponding to an image size (defined in the key). Values are the image URLs.
descriptionstringThe description of the channel
tagsarrayArray of strings containing the tags applied to the channel
urlstringLong web URL of the channel: https://video.ibm.com/channel/{channel_id}
statusstringPossible values are live or offair
last_broadcast_atnumberTime of last broadcast returned as a Unix timestamp
tinyurlstringShortened web URL of the channel (https://ustre.am/{channel_id}) - suitable for sharing on Twitter or Facebook
statsobjectA set of key-value pairs containing information about the autorecord settings with the following attributes: follower, viewer_total, viewer, video
stats.viewer_totalnumberTotal viewer number returned as an integer
stats.viewernumberNumber of current viewers returned as an integer
thumbnail.livestring
autorecordobjectA set of key-value pairs containing information about the autorecord settings with the following attributes: type, days
autorecord.type
autorecord.days
streamobjectA set of key-value pairs containing information about the stream settings with the following attributes: hls, dhls
stream.hlsstringHLS url
stream.dhlsstringDHLS url
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 owner’s profile picture
locksobjectA set of key-value pairs containing information about locks applied to the channel. It can be empty when none of the locks are enabled, or contains one or more of the following attributes: embed, hash, password
locks.embedarray
locks.hasharray3rd party viewer authentication is enabled for the channel. The value of the type attribute can be either basic or advanced. In case of advanced authentication, the auth_method attribute can contain twostepauth or samlsso for IBM Video Streaming supported authentication schemes or custom for other authentication methods.
locks.passwordarrayEmpty array if channel is password protected

Example of a success response:

{
"channel": {
"id": "1111",
"title": "Channel title",
"description": "Description of channel",
"tags": ["tag1", "tag2"],
"url": "channel-title",
"status": "offair",
"last_broadcast_at": 1400000000,

Error responses

Possible error responses:

HTTP RESPONSE CODEERROR VALUEERROR CONDITIONS
401 UnauthorizedThe 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

Create a channel

Create a new channel for the current account.

POST https://api.video.ibm.com/users/self/channels.json

Parameters

The parameters for the POST request:

PARAMETERTYPEIMPORTANCEDESCRIPTION
titlestringREQUIREDChannel title
descriptionstringOPTIONALChannel description
tagsstringOPTIONALComma separated list of channel tags

The Content-Type of the request should be application/x-www-form-urlencoded.

Example of the request:

POST users/self/channels.json HTTP/1.1
Host: api.video.ibm.com
Authorization: Bearer 3c2573673b782f6544405a22636f3d5d3b6f3950
Content-Type: application/x-www-form-urlencoded
title=API+Testing+Channel

The token in the above call is only an example.

Success response

Upon success a set of key-value pairs is returned under a channel element.

KEYTYPEDESCRIPTION
idstringThe unique id of the channel
titlestringChannel title
urlstringURL of the channel with string id: https://video.ibm.com/channel/{channel_id:string}
tiny_urlstringURL of the channel with numeric id: https:/video.ibm.com/channel/id/{channel_id:num}

Error responses

Possible error responses:

HTTP RESPONSE CODEERROR VALUEERROR CONDITIONS
400 Bad Requestinput_validation_errorThe channel title is not valid.
401 UnauthorizedThe provided access token is missing, revoked, expired or malformed
409 ConflictThe channel title or the channel URL is already in use
503 Service UnavailableThere is a temporary error on the server which makes it impossible to serve the request

Modify channel details

Change the title, description and tags of a channel.

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

Parameters

The parameters for the PUT request:

PARAMETERTYPEIMPORTANCEDESCRIPTION
titlestringREQUIREDChannel title
descriptionstringOPTIONALChannel description
tagsstringOPTIONALComma separated list of channel tags

Success response

Upon success a response with HTTP status “204 No Content” is returned. No body is returned for the response.

Error responses

Possible error responses:

HTTP RESPONSE CODEERROR VALUEERROR CONDITIONS
400 Bad Requestinput_validation_errorValidation failed
401 UnauthorizedThe 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_foundChannel not found
503 Service UnavailableThere is a temporary error on the server which makes it impossible to serve the request

Delete a channel

Delete the selected channel.

DELETE https://api.video.ibm.com/channels/{channel_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 UnauthorizedThe 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_foundChannel not found
503 Service UnavailableThere is a temporary error on the server which makes it impossible to serve the request