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
Copy to clipboard

Parameters

The parameters for the GET request:

PARAMETER	TYPE	IMPORTANCE	DESCRIPTION
`q`	string	OPTIONAL	Search for text in channel related data
`p`	integer	OPTIONAL	Requested page number (1 by default)
`pagesize`	integer	OPTIONAL	Requested page size (100 by default)

Success response

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

KEY	TYPE	DESCRIPTION
`id`	string	Identifier of the channel
`title`	string	Title of the channel
`url`	string	Long web URL of the channel: `https://video.ibm.com/channel/{channel_id}`
`broadcast_urls`	array	Array 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.
`status`	string	Possible values: `online` or `offline`. `online` means that the stream is viewable on the IBM Video Streaming website.
`description`	string	Channel description
`default`	boolean	Key is returned with `true` value if this is the default channel for the user.
`owner`	object	A set of key-value pairs containing information about the owner with the following attributes: `id`, `username`, `picture`
`owner`.`id`	string	The user ID of the channel owner
`owner`.`username`	string	The username of the channel owner
`owner`.`picture`	string	The URL of the image
`authority`	object	A set of key-value pairs containing information about the authority of the user to access the channel. Includes the following attributes: `reason`
`authority`.`reason`	string	Possible values are: `own`, `shared`
`picture`	object	A set of key-value pairs, each parameter corresponding to an image size (defined in the key). Values are the image URLs.
`live_thumbnail`	string	Listed 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": {
Copy to clipboard

The previous and next elements are optional.

Error responses

Possible error responses:

HTTP RESPONSE CODE	ERROR VALUE	ERROR CONDITIONS
401 Unauthorized		The provided access token is missing, revoked, expired or malformed
503 Service Unavailable		There 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
Copy to clipboard

Parameters

The parameters for the GET request:

PARAMETER	TYPE	IMPORTANCE	DESCRIPTION
`detail_level`	string	OPTIONAL	Verbosity 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.

NAME	TYPE	DESCRIPTION
`id`	string	Identifier of the channel
`title`	string	Title of the channel
`picture`	object	A set of key-value pairs, each parameter corresponding to an image size (defined in the key). Values are the image URLs.
`description`	string	The description of the channel
`tags`	array	Array of strings containing the tags applied to the channel
`url`	string	Long web URL of the channel: https://video.ibm.com/channel/{channel_id}
`status`	string	Possible values are live or offair
`last_broadcast_at`	number	Time of last broadcast returned as a Unix timestamp
`tinyurl`	string	Shortened web URL of the channel (https://ustre.am/{channel_id}) - suitable for sharing on Twitter or Facebook
`stats`	object	A set of key-value pairs containing information about the autorecord settings with the following attributes: follower, viewer_total, viewer, video
`stats`.`viewer_total`	number	Total viewer number returned as an integer
`stats`.`viewer`	number	Number of current viewers returned as an integer
`thumbnail`.`live`	string
`autorecord`	object	A set of key-value pairs containing information about the autorecord settings with the following attributes: type, days
`autorecord`.`type`
`autorecord`.`days`
`stream`	object	A set of key-value pairs containing information about the stream settings with the following attributes: hls, dhls
`stream`.`hls`	string	HLS url
`stream`.`dhls`	string	DHLS url
`owner`	object	A set of key-value pairs containing information about the owner with the following attributes: id, username, picture
`owner`.`id`	string	The user id of the channel owner
`owner`.`username`	string	The username of the channel owner
`owner`.`picture`	string	The URL of the owner’s profile picture
`locks`	object	A 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`.`embed`	array
`locks`.`hash`	array	3rd 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 `registration_gate`, `samlsso`, `googlesso`, `oidc` or `otp` for IBM Video Streaming supported authentication schemes or `custom` for other authentication methods.
`locks`.`password`	array	Empty 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,
Copy to clipboard

Error responses

Possible error responses:

HTTP RESPONSE CODE	ERROR VALUE	ERROR CONDITIONS
401 Unauthorized		The provided access token is missing, revoked, expired, or malformed
429 Too Many Requests	`too_many_requests`	Rate limit exceeded (Read more)
503 Service Unavailable		There 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
Copy to clipboard

Parameters

The parameters for the POST request:

PARAMETER	TYPE	IMPORTANCE	DESCRIPTION
`title`	string	REQUIRED	Channel title
`description`	string	OPTIONAL	Channel description
`tags`	string	OPTIONAL	Comma 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
Copy to clipboard

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.

KEY	TYPE	DESCRIPTION
`id`	string	The unique id of the channel
`title`	string	Channel title
`url`	string	URL of the channel with string id: https://video.ibm.com/channel/{channel_id:string}
`tiny_url`	string	URL of the channel with numeric id: https:/video.ibm.com/channel/id/{channel_id:num}

Error responses

Possible error responses:

HTTP RESPONSE CODE	ERROR VALUE	ERROR CONDITIONS
400 Bad Request	`input_validation_error`	The channel title is not valid.
401 Unauthorized		The provided access token is missing, revoked, expired or malformed
409 Conflict		The channel title or the channel URL is already in use
503 Service Unavailable		There 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
Copy to clipboard

Parameters

The parameters for the PUT request:

PARAMETER	TYPE	IMPORTANCE	DESCRIPTION
`title`	string	REQUIRED	Channel title
`description`	string	OPTIONAL	Channel description
`tags`	string	OPTIONAL	Comma 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 CODE	ERROR VALUE	ERROR CONDITIONS
400 Bad Request	`input_validation_error`	Validation failed
401 Unauthorized		The provided access token is missing, revoked, expired or malformed
403 Forbidden	`lack_of_ownership`	The API user is not allowed to manage the given channel
404 Not Found	`not_found`	Channel not found
503 Service Unavailable		There 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
Copy to clipboard

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 CODE	ERROR VALUE	ERROR CONDITIONS
401 Unauthorized		The provided access token is missing, revoked, expired or malformed
403 Forbidden	`lack_of_ownership`	The API user is not allowed to manage the given channel
404 Not Found	`not_found`	Channel not found
503 Service Unavailable		There is a temporary error on the server which makes it impossible to serve the request

Edit this page on GitHub

Rate limits

Broadcast settings: Broadcasting devices

Basic channel management

Get list of the user’s channels

Parameters

Success response

Error responses

Get channel details

Parameters

Success response

Error responses

Create a channel

Parameters

Success response

Error responses

Modify channel details

Parameters

Success response

Error responses

Delete a channel

Parameters

Success response

Error responses