Reference Documentation

Basic actions

Getting channel's details

GET https://api.ustream.tv/channels/CHANNEL_ID.FORMAT (format can be json or xml)
Parameters
parameter type importance Description
detail_level string OPTIONAL Verbosity level. Possible value: "minimal". In case of minimal verbosity level the result set is limited to id, title, picture, owner and locks data. If the channel is protected (see security section), only minimal data can be retrieved without a valid access token.
Response

Key-value pairs under a "channel" key. Example:

{
	"channel": {
		"id": "1111",
		"title": "Channel title",
		"description": "Description of channel",
		"tags": [
			"tag1",
			"tag2"
		],
		"url": "channel-title",
		"status": "offair",
		"last_broadcast_at": 1400000000,
		"tinyurl": "http://ustre.am/asdasd1",
		"stats": {
			"viewer_total": 10000000,
			"viewer": 1000
		},
		"thumbnail": {
			"live": "https://ustvstaticcdn1-a.akamaihd.net/images/defaults/channel_192x108:1.png"
		},
		"owner": {
			"id": "1234",
			"username": "api-user",
			"picture": "https://ustvstaticcdn1-a.akamaihd.net/images/defaults/user_48x48:1.png"
		},
		"locks": []
	}
}

Minimal response example:

{
	"channel": {
		"id": "1111",
		"title": "Channel title",
		"owner": {
			"id": "1234",
			"username": "api-user",
			"picture": "https://ustvstaticcdn1-a.akamaihd.net/images/defaults/user_48x48:1.png"
		},
		"picture": {
			"90x90": "https://ustvstaticcdn1-a.akamaihd.net/images/defaults/channel_90x90:1.png",
			"66x66": ...
		},
		"locks": {
			"hash": {
				"type": "advanced",
				"auth_method": "custom"
			}
		}
	}
}

Explanation of some values:

key type Description
url string Channel url name
status string Possible values: "live" or "offair"
last_broadcast_at int Last broadcast time in UNIX timestamp format
stats.viewer_total int Total viewer number
stats.viewer int Current viewer number when channel is live
locks array
key type Description
hash array 3rd party viewer authentication is enabled for the channel. 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 Cloud Video supported authentication schemes or "custom" for other authentication methods.
password array Empty array if channel is password protected
Error codes
error value HTTP response code Error conditions
not_found 404 Not Found The given channel does not exist.
unauthorized 401 Unauthorized The channel is locked.

Creating a channel

Create a new channel for the current account.

Prerequisites

The caller must have an access token capable initializing channel creation. To obtain a token, the client must request one from the authorization server.

Clients can acquire tokens without expiration by asking for "offline" scope. By using this scope the token will never expire.

Example initialization of a web-server token-acquiring flow:

https://www.ustream.tv/oauth2/authorize?response_type=code&client_id=A...Z&redirect_uri=http://...

Example initialization of an implicit token-acquiring flow:

https://www.ustream.tv/oauth2/authorize?response_type=token&client_id=A...Z&redirect_uri=http://...

See more examples

Channel creation

POST https://api.ustream.tv/users/self/channels.json
Parameters
parameter type importance Description
title string REQUIRED Create the channel with this title
description string OPTIONAL Create the channel with this description

The body of the call should contain the channel title optionally it can contain channel description and tags. The Content-Type of the request should be application/x-www-form-urlencoded.

Example:

POST users/self/channels.json HTTP/1.1
Host: api.ustream.tv
Authorization: Bearer 3c2573673b782f6544405a22636f3d5d3b6f3950
Content-Type: application/x-www-form-urlencoded

title=API+Testing+Channel

The token in the above call is only an example.

Response
{
	"channel": {
		"id":"13091307",
		"title":"Whatever Test 1234",
		"url":"whatever-test-1234",
		"tiny_url":"http://ustre.am/SVE7"
	}
}
Possible negative responses
  • 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
  • 400 Bad Request: The channel title is invalid
  • 503 Service Unavailable: There is a temporary error on the server which makes it impossible to serve the request

Edit channel details

Edit a channel's title, description and tags.

PUT https://api.ustream.tv/channels/CHANNEL_ID.FORMAT (format can be json or xml)
Parameters
parameter type importance Description
title string REQUIRED Channel title
description string OPTIONAL Channel description
tags string OPTIONAL Comma separated list of channel tags
Response

On success a response with HTTP status 204 No Content is returned.

Error codes
error value HTTP response code Error conditions
lack_of_ownership 403 Forbidden The api user is not allowed to manage the given channel
input_validation_error 400 Bad request If validation fails
not_found 404 Not found Channel not found

Deleting a channel

Permanently delete a channel from the current account.

DELETE https://api.ustream.tv/channels/CHANNEL_ID.FORMAT (format can be json or xml)
Parameters

This request has no parameters.

Response

On success a response with HTTP status 200 OK is returned.

Error codes
error value HTTP response code Error conditions
lack_of_ownership 403 Forbidden The given channel does not belong to the user.
not_found 404 Not Found The given channel does not exist.

Listing the user's channels

Get a detailed list of the user's channels, including live status, thumbnail, and mobile and broadcast urls

GET https://api.ustream.tv/users/self/channels.FORMAT (format can be json or xml)
Parameters
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)
Response

A list of key-value pairs under a "channels" key. All of these elements are containing these informations:

key type Description
id string Identifier of the channel
title string Title of the channel
url string Long web URL of the channel (http://www.ustream.tv/channel/...)
tiny_url string Shortened web URL of the channel (http://ustre.am/...) - suitable for sharing on Twitter / Facebook
status string Possible values: "online" or "offline". "online" means that the stream is viewable on the IBM Cloud Video website.
broadcast_urls array of string Array of RTMP URLs (strings) where the client can broadcast. Client should fall-back to the second/third one if it provided and the previous element seems failing. Provided only in case of client explicitly asks for with a "broadcaster" detail_level query parameter.
default boolean, optional True if this is the default channel for the user. False or missing if it is not the default channel.
live_thumbnail string Listed when the channel is online.
picture map List of channel picture in different sizes. The key is the size (eg: 96x96) the value is the picture URL.

The paging information can be found inside the "paging" element. Example:

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

Device Passwords

Get device passwords

GET https://api.ustream.tv/users/self/device-passwords.FORMAT (format can be json or xml)
Parameters
parameter type importance Description
page integer OPTIONAL Requested page number (1 by default)
pagesize integer OPTIONAL Requested page size (50 by default)
Response

On success a response with HTTP status 200 OK is returned.

Explanation of some values:

key type Description
device_name string Name of the device password
user_name string Username of the device password
created_at timestamp Creation date
valid_from timestamp The time after which the device password can be used for logging in.
valid_until timestamp The time until the device password can be used for logging in.
Response example
{
  "device_passwords": [
    {
      "device_name": "Sample Device 1",
      "user_name": "xnwj3mseuka",
      "created_at": 1497441340,
      "valid_from": 1497443340,
      "valid_until": null
    },
    {
      "device_name": "Sample Device 2",
      "user_name": "ymvbk9bu7f8",
      "created_at": 1497341340,
      "valid_from": 1497341880,
      "valid_until": 1497381880
    }
  ],
  "paging": []
}

Paging information can be found under the "paging" element. Example:

"paging": {
	"previous": "https://api.ustream.tv/users/self/device-passwords.json?pagesize=PAGE_SIZE&page=PREVIOUS_PAGE",
	"next": "https://api.ustream.tv/users/self/device-passwords.json?pagesize=PAGE_SIZE&page=NEXT_PAGE"
}
Error codes
error value HTTP response code Error conditions
unauthorized 401 Unauthorized The provided Access Token is missing, revoked, expired or malformed

Create device password

POST https://api.ustream.tv/users/self/device-passwords.FORMAT (format can be json or xml)
Parameters

The body of the request must contain the device name and a "valid_from" timestamp.

parameter type importance Description
device_name string REQUIRED Name of the device
valid_from timestamp REQUIRED The time after which the device password can be used for logging in.
valid_until timestamp OPTIONAL The time until the device password can be used for logging in.
Response

On success a response with HTTP status 200 OK is returned.

Explanation of some values:

key type Description
device_name string Name of the device password
user_name string Username of the device password
password string Generated password
valid_from timestamp The time after which the device password can be used for logging in.
valid_until timestamp The time until the device password can be used for logging in.
Response example
{
  "device_name": "Sample Device 4",
  "user_name": "jgun36pdc79",
  "password": "jgcxathqhyqcdxp",
  "valid_from": 1497571200,
  "valid_until": 1500249600
}
Error codes
error value HTTP response code Error conditions
input_validation_error 400 Bad request In case of any required parameter is missing.
unauthorized 401 Unauthorized The provided Access Token is missing, revoked, expired or malformed

Delete device password

DELETE https://api.ustream.tv/users/self/device-passwords/USER_NAME.FORMATformat can be json or xml)
Parameters

This request has no parameters.

Response

On success a response with HTTP status 200 OK is returned.

Error codes
error value HTTP response code Error conditions
unauthorized 401 Unauthorized The provided Access Token is missing, revoked, expired or malformed

Security

Password protection

When enabled, viewers must enter a password to view the show. This feature is currently disabled in both the iOS and Android apps.

GET, PUT, DELETE https://api.ustream.tv/channels/CHANNEL_ID/locks/password.FORMAT (format can be json or xml)
Supported HTTP methods:
HTTP method Description
GET Returns the password protection status
PUT Sets the channel password and enables password protection as well
DELETE Removes the channel password, disables password protection status
Parameters

GET and DELETE requests have no parameters.
The parameters for the PUT request:

parameter type importance Description
password string REQUIRED The new channel password
Response

For DELETE and PUT an empty response is returned.
The result for the GET request:

key type Description
enabled boolean password protection status
Error codes
error value HTTP response code Error conditions
input_validation_error 400 Bad Request The given password is invalid.
lack_of_ownership 403 Forbidden The given channel does not belong to the user.
not_found 404 Not Found The given channel does not exist.

3rd party viewer authentication

Use third party authentication on viewing IBM Cloud Video content (live or recorded video). Technically it is a handshake mechanism between your service and the IBM Cloud Video infrastructure.

Basic authentication

PUT https://api.ustream.tv/channels/CHANNEL_ID/locks/hash/basic.FORMAT (format can be json or xml)
Parameters
parameter type importance Description
url string REQUIRED Third party url
secret string REQUIRED Secret key
Response

On success a response with HTTP status 201 Created is returned when new hash lock was inserted for the channel.
On success a response with HTTP status 204 No Content is returned when an old hash lock was updated for the channel.
Specific error codes:

error value HTTP response code Error conditions
invalid_request 400 Bad Request When one or more required parameters are missing or the user has no access to hash lock
invalid_type 400 Bad Request The specified type is invalid or unsupported

Advanced authentication

PUT https://api.ustream.tv/channels/CHANNEL_ID/locks/hash/advanced.FORMAT (format can be json or xml)
Parameters
parameter type importance Description
url string REQUIRED Third party url
secret string REQUIRED Secret key
message string REQUIRED Displayed message
button_caption string REQUIRED Button caption
popup_width int REQUIRED Popup width
popup_height string REQUIRED Popup height
Response

On success a response with HTTP status 201 Created is returned when new hash lock was inserted for the channel.
On success a response with HTTP status 204 No Content is returned when an old hash lock was updated for the channel.
Specific error codes:

error value HTTP response code Error conditions
invalid_request 400 Bad Request When one or more required parameters are missing or the user has no access to hash lock
invalid_type 400 Bad Request The specified type is invalid or unsupported

Getting the authentication

GET https://api.ustream.tv/channels/CHANNEL_ID/locks/hash.FORMAT (format can be json or xml)
Parameters

This request has no parameters.

Response

Key-value pairs under a "hashlock" key. Example:

{
"hashlock": {
		"type": "advanced",
		"url": "https://align.ustream.tv/auth/123",
		"message": null,
		"button_caption": null,
		"popup_width": "0",
		"popup_height": "0"
	}
}

Remove authentication

DELETE https://api.ustream.tv/channels/CHANNEL_ID/locks/hash.FORMAT (format can be json or xml)
Parameters

This request has no parameters.

Response

On success a response with HTTP status 200 OK is returned.

Embed restriction

By default all IBM Cloud Video channels can be embedded anywhere across the internet. By restricting the embed URLs, you can control the viewing experience and limit distribution to your own preferred partners.

Get embed lock status

GET https://api.ustream.tv/channels/CHANNEL_ID/locks/embed.FORMAT (format can be json or xml)
Parameters

This request has no parameters.

Response

On success a response with HTTP status 200

key type Description
locked string Returns TRUE if the embed lock is set to the channel, FALSE otherwise
Error codes
error value HTTP response code Error conditions
invalid_request 402 Payment Required If the user does not have the embed_restriction benefit

Edit embed lock

PUT https://api.ustream.tv/channels/CHANNEL_ID/locks/embed.FORMAT (format can be json or xml)
Parameters
parameter type importance Description
locked string REQUIRED Set embed lock on channel when parameter locked==TRUE, remove embed lock when locked==FALSE
Response

On success a response with HTTP status 204 No Content is returned.

Error codes
error value HTTP response code Error conditions
invalid_request 402 Payment Required If the user does not have the embed_restriction benefit
invalid_request 400 Bad Request If the request parameter is missing or invalid

Get embed lock url whitelist

GET https://api.ustream.tv/channels/CHANNEL_ID/locks/embed/allowed-urls.FORMAT (format can be json or xml)
Parameters

This request has no parameters.

Response

On success a response with HTTP status 200

key type Description
allowed_urls array Return the url list from the allowed urls embed lock list no matter where it was set. Return empty array if the lock is FALSE.
Error codes
error value HTTP response code Error conditions
invalid_request 402 Payment Required If the user does not have the embed_restriction benefit

Add url to embed lock url whitelist

POST https://api.ustream.tv/channels/CHANNEL_ID/locks/embed/allowed-urls.FORMAT (format can be json or xml)
Parameters
parameter type importance Description
url string REQUIRED Add the url to the url whitelist

You can only add one URL per API call.

Response

On success a response with HTTP status 201 Created is returned.

Error codes
error value HTTP response code Error conditions
invalid_request 402 Payment Required If the user does not have the embed_restriction benefit
invalid_request 400 Bad Request If the request parameter is missing or invalid

Empty the embed lock url whitelist

DELETE https://api.ustream.tv/channels/CHANNEL_ID/locks/embed/allowed-urls.FORMAT (format can be json or xml)
Parameters

This request has no parameters.

Response

On success a response with HTTP status 200 OK is returned.

Error codes
error value HTTP response code Error conditions
invalid_request 402 Payment Required If the user does not have the embed_restriction benefit

Sharing control

By turning this feature on the sharing feature will be removed from the viewer.

PUT https://api.ustream.tv/channels/CHANNEL_ID/settings/viewer.FORMAT (format can be json or xml)
Parameters
parameter type importance Description
sharing boolean REQUIRED Enable or disable sharing
Response

On success a response with HTTP status 200 OK is returned.

Error Codes
error value HTTP response code Error conditions
invalid_sharing 400 Bad Request The specified sharing is invalid or unsupported.
payment_required 402 Payment Required The user does not have access to control sharing

Whitelabel Broadcasting

Branding control

With co-branding, you can display your brand prominently in the player. With full branding, you can even remove the default IBM Cloud Video watermark. No-branding allows removing the IBM Cloud Video watermark and go with no watermark at all.

Set branding type

PUT https://api.ustream.tv/channels/CHANNEL_ID/branding.FORMAT (format can be json or xml)
Parameters
parameter type importance Description
type string REQUIRED Branding type

The type parameter must be passed in the HTTP body, not in the URL.

Available branding types
type Description
co Co-branding
full Full-branding
no No branding
Response

On success a response with HTTP status 200 OK is returned.

Error codes
error value HTTP response code Error conditions
invalid_type 400 Bad Request The specified type is invalid or unsupported.
payment_required 402 Payment Required The user does not have access to the specified branding type

Disable branding

DELETE https://api.ustream.tv/channels/CHANNEL_ID/branding.FORMAT (format can be json or xml)
Parameters

This request has no parameters.

Response

On success a response with HTTP status 200 OK is returned.

Update logo settings

PUT https://api.ustream.tv/channels/CHANNEL_ID/branding/logo/LOGO_ID/settings.FORMAT (format can be json or xml)

Only 0 is supported as LOGO_ID currently.

Parameters
parameter type importance Description
position string REQUIRED Logo position
Supported values: "top-left", "top-middle", "top-right", "middle-left", "middle-right", "bottom-left", "bottom-middle", "bottom-right"
margin unsigned int REQUIRED Amount of margin
link string REQUIRED Logo click url (valid url, or empty string)

The type parameter must be passed in the HTTP body, not in the URL.

Response

On success a response with HTTP status 200 OK is returned.

Error codes
error value HTTP response code Error conditions
invalid_position 400 Bad Request The specified position is invalid or unsupported.
invalid_margin 400 Bad Request The specified margin is invalid.
invalid_link 400 Bad Request The specified link is invalid.
payment_required 402 Payment Required The user does not have access to channel branding

Uploading logo

PUT https://api.ustream.tv/channels/CHANNEL_ID/branding/logo/LOGO_ID.FORMAT (format can be json or xml)

Only 0 is supported as LOGO_ID currently.

Request

The logo must be passed in the HTTP body.

Supported image types image/jpeg, image/png, image/gif
Maximum width 170px
Maximum height 170px
Response

On success a response with HTTP status 200 OK is returned.

Error codes
error value HTTP response code Error conditions
invalid_file 400 Bad Request The specified file is invalid or unsupported.
invalid_image 400 Bad Request The specified image is invalid.
payment_required 402 Payment Required The user does not have access to channel branding

Channel page control

Your channel and videos will not be found anywhere on ustream.tv. Viewers will only be able to watch embedded players on external websites. If you want the channel to appear only on your own website, make sure to restrict URL embeds to your site as well.

Get page lock setting

GET https://api.ustream.tv/channels/CHANNEL_ID/locks/page.FORMAT(format can be json or xml)
Parameters

This request has no parameters.

Response

On success a response with HTTP status 200

key type Description
locked string Returns TRUE if the page lock is set to the channel, FALSE otherwise
Error codes
error value HTTP response code Error conditions
invalid_request 402 Payment Required If the user does not have the page_lock benefit

Edit page lock

PUT https://api.ustream.tv/channels/CHANNEL_ID/locks/page.FORMAT (format can be json or xml)
Parameters
parameter type importance Description
locked string REQUIRED Set page lock on channel when parameter locked==TRUE, remove page lock when locked==FALSE
Response

On success a response with HTTP status 204 No Content is returned.

Error codes
error value HTTP response code Error conditions
invalid_request 402 Payment Required If the user does not have the page_lock benefit
invalid_request 400 Bad Request If the request parameter is missing or invalid

Hide viewer numbers

By setting this feature the viewer number of a live channel will not be visible in the viewer.

PUT https://api.ustream.tv/channels/CHANNEL_ID/settings/hide-viewers.FORMAT (format can be json or xml)
Parameters
parameter type importance Description
value boolean REQUIRED Enable or disable viewer number hiding
Response

On success a response with HTTP status 200 OK is returned.

Error codes
error value HTTP response code Error conditions
invalid_value 400 Bad Request The specified value is invalid or unsupported.
lack_of_ownership 403 Forbidden The given channel does not belong to the user.

Channel design

Channel page background

Get

Get current background color

GET https://api.ustream.tv/channels/CHANNEL_ID/design/background.FORMAT (format can be json or xml)
Parameters

This request has no parameters.

Response

Key-value pairs under a "background" key.

key type Description
color string Channel page background color in hex RGB format
Error codes
error value HTTP response code Error conditions
lack_of_ownership 403 Forbidden The api user is not allowed to manage the given channel
not_found 404 Not found Channel not found

Edit background color

PUT https://api.ustream.tv/channels/CHANNEL_ID/design/background.FORMAT (format can be json or xml)
Parameters
parameter type importance Description
color string REQUIRED Channel page background color in hex RGB format
Response

On success a response with HTTP status 200 OK is returned.

Error codes
error value HTTP response code Error conditions
lack_of_ownership 403 Forbidden The api user is not allowed to manage the given channel
bad_request 400 Bad request If validation fails
not_found 404 Not found Channel not found

Remove settings

DELETE https://api.ustream.tv/channels/CHANNEL_ID/design/background.FORMAT (format can be json or xml)
Parameters

This request has no parameters.

Response

On success a response with HTTP status 200 OK is returned.

Error codes
error value HTTP response code Error conditions
lack_of_ownership 403 Forbidden The api user is not allowed to manage the given channel
not_found 404 Not found Channel not found

Channel picture

Set channel picture

POST https://api.ustream.tv/channels/CHANNEL_ID/design/picture.FORMAT (format can be json or xml)
Parameters
parameter type importance Description
picture file REQUIRED The channel picture. The image must be square and less than 1MB
Response

On success a response with HTTP status 204 No Content is returned.

Error codes
error value HTTP response code Error conditions
lack_of_ownership 403 Forbidden The api user is not allowed to manage the given channel
bad_request 400 Bad request Image format or size is wrong

Remove channel picture

DELETE https://api.ustream.tv/channels/CHANNEL_ID/design/picture.FORMAT (format can be json or xml)
Parameters

This request has no parameters.

Response

On success a response with HTTP status 200 OK is returned.

Error codes
error value HTTP response code Error conditions
lack_of_ownership 403 Forbidden The api user is not allowed to manage the given channel

Channel managers

This feature enables a user (the master) to add managers to their channels with administrative rights. The activated managers receive benefits of managed channels, independently from their current plans. A managed channel can have at most 500 managers, but only 3 managers can be activated simultaneously by default.

Getting channel managers

GET https://api.ustream.tv/users/self/managers.FORMAT (format can be json or xml)
Parameters

This request has no parameters.

Response

On success a response with HTTP status 200 OK is returned.

key type Description
user_id string User identifier of the channel manager
email string E-mail address of the channel manager
alias string Alias name of the channel manager
active boolean Active flag.
channels array Array of managed channel identifiers
Error codes
error value HTTP response code Error conditions
invalid_request 402 Payment required The user does not have active subaccount benefit

Adding a new channel manager

POST https://api.ustream.tv/users/self/managers.FORMAT (format can be json or xml)
Parameters
parameter type importance Description
email string REQUIRED The e-mail address of a registered IBM Cloud Video user
alias string OPTIONAL Alias name for the channel manager
Response

On success a response with HTTP status 201 Created is returned.

key type Description
user_id string User identifier of the created channel manager
email string E-mail address of the channel manager
alias string Alias name of the channel manager
active boolean Active flag (false by default)
Error codes
error value HTTP response code Error conditions
invalid_request 402 Payment required The user does not have active subaccount benefit
bad_request 400 Bad request If validation fails, user not found or is already a channel manager

Modifying a channel manager

PUT https://api.ustream.tv/users/self/managers/MANAGER_ID.FORMAT (format can be json or xml)
Parameters
parameter type importance Description
alias string OPTIONAL Alias name for the channel manager
active boolean REQUIRED Sets the manager active flag
Response

On success a response with HTTP status 200 OK is returned.

Error codes
error value HTTP response code Error conditions
invalid_request 402 Payment required The user does not have active subaccount benefit
bad_request 400 Bad request If validation fails
not_found 404 Not found Channel manager not found
limit_reached 403 Forbidden The maximum active channel manager count has been reached, no more active managers allowed

Getting channel manager

GET https://api.ustream.tv/users/self/managers/MANAGER_ID.FORMAT (format can be json or xml)
Parameters

This request has no parameters.

Response

On success a response with HTTP status 200 OK is returned.

key type Description
user_id string User identifier of the channel manager
email string E-mail address of the channel manager
alias string Alias name of the channel manager
active boolean Active flag.
channels array Array of managed channel identifiers
Error codes
error value HTTP response code Error conditions
invalid_request 402 Payment required The user does not have active subaccount benefit

Deleting a channel manager

DELETE https://api.ustream.tv/users/self/managers/MANAGER_ID.FORMAT (format can be json or xml)
Parameters

This request has no parameters.

Response

On success a response with HTTP status 200 OK is returned.

Error codes
error value HTTP response code Error conditions
invalid_request 402 Payment required The user does not have active subaccount benefit
not_found 404 Not found Channel manager not found

Grant access to a user for a channel

PUT https://api.ustream.tv/channels/CHANNEL_ID/managers/MANAGER_ID.FORMAT (format can be json or xml)
Parameters

This request has no parameters.

Response

On success a response with HTTP status 200 OK is returned.

Error codes
error value HTTP response code Error conditions
invalid_request 402 Payment required The user does not have active subaccount benefit
lack_of_ownership 403 Forbidden The channel does not belong to the master user
not_found 404 Not found Channel manager not found

Revoke access from a user on a channel

DELETE https://api.ustream.tv/channels/CHANNEL_ID/managers/MANAGER_ID.FORMAT (format can be json or xml)
Parameters

This request has no parameters.

Response

On success a response with HTTP status 200 OK is returned.

Error Codes
error value HTTP response code Error conditions
invalid_request 402 Payment required The user does not have active subaccount benefit
lack_of_ownership 403 Forbidden The channel does not belong to the master user
not_found 404 Not found Channel manager not found

Channel featured videos

Channel featured videos is a list of videos that can be shown on the channel page, under the featured videos tab.

List the channel featured videos

GET https://api.ustream.tv/channels/CHANNEL_ID/featured-videos.FORMAT (format can be json or xml)
Parameters
parameter type importance Description
page integer OPTIONAL Requested page number (1 by default)
pagesize integer OPTIONAL Requested page size (50 by default, max 50)
detail_level string OPTIONAL Verbosity level. Possible value: "minimal". In case of minimal verbosity level the result set is limited to id, and links data. If the channel is protected (see security section), only minimal data can be retrieved without a valid access token.
Response

A list of key-value pairs under a "videos" key.

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

Example:

{
"videos": [{
		"id": "111",
		"title": "Title of video",
		"description": "Description of video",
		"url": "http://www.ustream.tv/recorded/111",
		"length": "12345.123456",
		"created_at": 1399388736,
		"file_size": "120000",
		"views": 0,
		"thumbnail": {
			"default": "https://ustvstaticcdn1-a.akamaihd.net/111.jpg"
		},
		"media_urls": {
			"flv": "http://tcdn.ustream.tv/video/111"
		},
		"links": {
			"channel": {
				"href": "https://api.ustream.tv/channels/1.json",
				"id": "1"
			}
		}
	},
	...
	]
}

Minimal response example:

{
"video": {
		"id": "111",
		"links": {
			"channel": {
				"href": "https://api.ustream.tv/channels/1.json",
				"id": "1"
			}
		}
	}
}

Explanation of some values:

key type Description
length string Video length in seconds
created_at int Video create date in UNIX timestamp
file_size string Video file size in bytes

The paging information can be found under the "paging" element. Example:

{
"paging": {
		"previous": "https://api.ustream.tv/channels/CHANNEL_ID/featured-videos.json?pagesize=PAGE_SIZE&page=PREVIOUS_PAGE",
		"next": "https://api.ustream.tv/channels/CHANNEL_ID/featured-videos.json?pagesize=PAGE_SIZE&page=NEXT_PAGE",
		"page_count": 8,
		"item_count": 38
	}
}
Error codes
error value HTTP response code Error conditions
not_found 404 Not found

This error code is returned in the following cases:

  • The channel does not exist.
  • The featured videos on the channel are not shown.

Update featured videos of the channel

PUT https://api.ustream.tv/channels/CHANNEL_ID/featured-videos.FORMAT (format can be json or xml)
Parameters
parameter type importance Description
video_ids array REQUIRED Video IDs to be added to the channel featured videos.

Example:

POST /channels/CHANNEL_ID/featured-videos.json HTTP/1.1
Host: api.ustream.tv
Authorization: Bearer 3c2573673b782f6544405a22636f3d5d3b6f3950
Content-Type: application/x-www-form-urlencoded

video_ids[]=111&video_ids[]=222

The token in the above call is only an example.

Successful response

The response will contain the following collection limit headers:

Header Type Description
X-Collection-Limit int The maximum number of videos that can be featured on a channel.
X-Collection-Remaining int How many more videos can be featured on the channel.
Error codes
error value HTTP response code Error conditions
invalid_token 401 Authorization required The provided Access Token is missing, revoked, expired or malformed.
permission_denied 403 Permission denied The authenticated user does not have access to the channel or one of the videos.
not_found 404 Not found The channel does not exist.
limit_reached 413 Request entity too large The number of videos in the featured videos list have reached the limit. Check the returned collection limit headers.

Stream settings

Multi quality streaming

By turning this feature on your stream will be transcoded to several versions with different quality settings.

PUT https://api.ustream.tv/channels/CHANNEL_ID/settings/multi-quality.FORMAT (format can be json or xml)
Parameters
parameter type importance Description
value boolean REQUIRED Enable or disable multi quality in viewer
Response

On success a response with HTTP status 200 OK is returned.

Error codes
error value HTTP response code Error conditions
invalid_value 400 Bad Request The specified value is invalid or unsupported.
payment_required 402 Payment Required The user does not have access to control multi quality

Recording

Start/stop recording

During broadcast clients can control recorder on an owned channel. There's no direct feedback on the results of the operation.

POST https://api.ustream.tv/channels/CHANNEL_ID/recorder.FORMAT (format can be json or xml)
Parameters
parameter type importance Description
command string REQUIRED The command should be "start" or "stop"
Response

On success a response with HTTP status "202 Accepted" is returned.

On the stop command the response body will contain information about the resulting video (id and API resource uri)

Example usage:

POST /channels/42/recorder.json HTTP/1.1
Host: api.ustream.tv
Authorization: Bearer 3c2573673b782f6544405a22636f3d5d3b6f3950
Content-Type: application/x-www-form-urlencoded

command=stop

Example reponse (for stop command):

{
	"video": {
		"id": 11111,
		"url": "https://api.ustream.tv/videos/11111.json"
	}
}

Getting recording status

During broadcast you can ask for that information using the GET HTTP method on the same resource.

GET https://api.ustream.tv/channels/CHANNEL_ID/recorder.FORMAT(format can be json or xml)

Example reponse:

{
	"video": {
		"id": "11111",
		"url": "https://api.ustream.tv/videos/11111.json"
	}
}

Autorecord

Videos can be automatically created when broadcasting. The behaviour can be controlled by this resource.

PUT https://api.ustream.tv/channels/CHANNEL_ID/settings/autorecord.FORMAT (format can be json or xml)
Parameters
parameter type importance Description
value string REQUIRED Possible values: disabled, private, public. If the value is disabled, no auto-recorded video gets created for the channel when broadcasting. If the value is private, then the new auto-record will be private by default. In case of public the created auto-records will be public by default.
Response

On success a response with HTTP status 200 OK is returned.

Error codes
error value HTTP response code Error conditions
invalid_value 400 Bad Request The specified value is invalid or unsupported.
payment_required 402 Payment Required The user does not have access to control autorecord settings

Getting record time limit

Gets the maximum allowed length of recorded videos for the channel.

GET https://api.ustream.tv/channels/CHANNEL_ID/limits/recording.FORMAT (format can be json or xml)
Parameters

This request has no parameters.

Response
key type Description
time integer record time limit in seconds
Error codes
error value HTTP response code Error conditions
lack_of_ownership 403 Forbidden The given channel does not belong to the user.
not_found 404 Not Found The given channel does not exist.

Video

Listing the videos of a channel

Get a detailed list of the videos of a channel

GET https://api.ustream.tv/channels/CHANNEL_ID/videos.FORMAT (format can be json or xml)
Parameters
parameter type importance Description
page integer OPTIONAL Requested page number (1 by default)
pagesize integer OPTIONAL Requested page size (50 by default, max 50)
q string OPTIONAL Search for text in video related data. Only works for public videos, and if no filter parameter is set.
sort string OPTIONAL Result order. Possible values: recent,popular (default: recent)
filter set OPTIONAL Filter videos by protection levels. Values: public, private (default: empty). The name of the parameter set should filter[protect], and the values should be comma separated without whitespace included.
Response

A list of key-value pairs under a "videos" key.

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

Example:

{
	"videos": [
		{
			"id": "111",
			"title": "Title of video",
			"description": "Description of video",
			"url": "http://www.ustream.tv/recorded/111",
			"length": "12345.123456",
			"created_at": 1399388736,
			"file_size": "120000",
			"views": 0,
			"thumbnail": {
				"default": "https://ustvstaticcdn1-a.akamaihd.net/111.jpg"
			},
			"media_urls": {
				"flv": "http://tcdn.ustream.tv/video/111"
			},
			"links": {
				"channel": {
					"href": "https://api.ustream.tv/channels/1.json"
				}
			}
		},
		...
	]
}

Explanation of some values:

key type Description
length string Video length in seconds
created_at int Video create date in UNIX timestamp
file_size string Video file size in bytes

The paging information can be found under the "paging" element. Example:

{
	"paging": {
		"previous": "https://api.ustream.tv/CHANNEL_ID/videos.json?pagesize=PAGE_SIZE&page=PREVIOUS_PAGE",
		"next": "https://api.ustream.tv/channels/CHANNEL_ID/videos.json?pagesize=PAGE_SIZE&page=NEXT_PAGE"
	}
}
Error codes
error value HTTP response code Error conditions
invalid_token 401 Authorization required The video list is protected, only the owner with a valid token can access it.
not_found 404 Not Found The given channel does not exist.

Listing the videos of the user

Get a detailed list of the videos of the user

GET https://api.ustream.tv/users/self/videos.FORMAT (format can be json or xml)
Parameters

For parameters and example response, please see the previous section, "Listing the videos of a channel", as it is the same in this case.

Video details

Get video details

GET https://api.ustream.tv/videos/VIDEO_ID.FORMAT (format can be json or xml)
Parameters
parameter type importance Description
detail_level string OPTIONAL Verbosity level. Possible value: "minimal". In case of minimal verbosity level the result set is limited to id, and links data. If the channel is protected (see security section), only minimal data can be retrieved without a valid access token.
Response

Key-value pairs under a "video" key.

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

Example:

{
	"video": {
		"id": "111",
		"title": "Title of video",
		"description": "Description of video",
		"url": "http://www.ustream.tv/recorded/111",
		"length": "12345.123456",
		"created_at": 1399388736,
		"file_size": "120000",
		"views": 0,
		"thumbnail": {
			"default": "https://ustvstaticcdn1-a.akamaihd.net/111.jpg"
		},
		"media_urls": {
			"flv": "http://tcdn.ustream.tv/video/111"
		},
		"links": {
			"channel": {
				"href": "https://api.ustream.tv/channels/1.json",
				"id": "1"
			}
		}
	}
}

Minimal response example:

{
	"video": {
		"id": "111",
		"links": {
			"channel": {
				"href": "https://api.ustream.tv/channels/1.json",
				"id": "1"
			}
		}
	}
}

Explanation of some values:

key type Description
length string Video length in seconds
created_at int Video create date in UNIX timestamp
file_size string Video file size in bytes
Error codes
error value HTTP response code Error conditions
not_found 404 Not Found The given video does not exist.

Edit video details

PUT https://api.ustream.tv/videos/VIDEO_ID.FORMAT (format can be json or xml)
Parameters
parameter type importance Description
title string OPTIONAL Video title
description string OPTIONAL Video description
protect string OPTIONAL Video protection level. Possible values: public, private
Response

On success a response with HTTP status 200 OK is returned.

Error codes
error value HTTP response code Error conditions
invalid_value 400 Bad Request The specified value is invalid or unsupported.
lack_of_ownership 403 Forbidden The given video does not belong to the user.
not_found 404 Not Found The given video does not exist.

Downloading videos

You can download your own videos using this API resource. It provides info on the downbloadable version of your video. You have to provide an access token since it only works for videos you own.

GET https://api.ustream.tv/videos/VIDEO_ID/downloadable/VIDEO_FORMAT.FORMAT (format can be json or xml)

The query parameter VIDEO_FORMAT could be mp4 or flv.

Response

Key-value pairs under a "downloadable" key with details of the status of the downloadable item. Example:

{
    "downloadable": {
        "download_url":"https://download.domain/example_download_path?download_parameters",
        "expires_at":1471363639,
        "status":"available"
    }
}

The property called download_url holds the download url could be used to download the video file. It could be null if the downloadable version is not available.

The expires_at property contains a unix timestamp of the moment when the downloadable version will expire. For downloadable videos never expire this property will be null.

status represents the state of the downloadable video, it could be:

  • available if the video is ready to download.
  • unavailable if the downloadable version is not (yet) available.
  • pending if the process of generation downloadable version is in progress.

Example call

GET /videos/123456/downloadable/mp4.json HTTP/1.1
Host: api.ustream.tv
Authorization: Bearer 782f6544405a22636f3d5d3b63c2573673bf3950

{
    "downloadable": {
        "download_url":"https://download.domain/example_download_path?download_parameters",
        "expires_at":1471363639,
        "status":"available"
    }
}

Requesting a downloadable version of a video

In some cases the downloadable version of a video is not always available. You have to request us to generate a temporary video file for download. The workflow is the following:

  1. Use this call to request a downloadable file
  2. Poll the same API resource for status updates
  3. Use the value of the download_url property as soon as it is available

You have 24 hours to download the video file right after it's available. Please refer the property expires_at for the proper timing.

Requesting a downloadable version is only an emtpy POST on the downloadable video resource. You have to provide an access token since it only works for videos you own.

POST https://api.ustream.tv/videos/VIDEO_ID/downloadable/VIDEO_FORMAT.FORMAT (format can be json or xml)

The query parameter VIDEO_FORMAT could be mp4 or flv .

If everything works as expected, you'll instantly get the same response format as the GET version provides, but the property status will be pending or available.

Example call

POST /videos/123456/downloadable/mp4.json HTTP/1.1
Host: api.ustream.tv
Authorization: Bearer 782f6544405a22636f3d5d3b63c2573673bf3950

{
    "downloadable": {
        "download_url":null,
        "expires_at":null,
        "status":"pending"
    }
}

Uploading videos

Videos can be uploaded by FTP. To upload a file you must do the following steps:

  1. Initiate an upload process by an API call. In the response you can find the details of the FTP connect.
  2. Upload the video.
  3. When the upload is finished, send a "file in place" signal, which tells to our server that it can start process the file.
  4. Call the API to check the status of the processing.

Initializing an upload

POST https://api.ustream.tv/channels/CHANNEL_ID/uploads.FORMAT?type=videoupload-ftp (format can be json or xml)
Parameters
parameter type importance Description
title string OPTIONAL Video title
description string OPTIONAL Video description
protect integer OPTIONAL Level of protection
Response

Key-value pairs with details of the ftp access. Example:

{
	"protocol":"ftp",
	"host":"red44.ustream.tv",
	"port":21,
	"path":"/1_12345_12345678901234",
	"user":"1_12345_1234567890",
	"password":"ftppw",
	"videoId":"52177361",
	"url":"ftp://1_1234_1234567890:ftppw@red44.ustream.tv/1_12345_12345678901234"
}
Error codes
error value HTTP response code Error conditions
not_found 404 Not Found The given channel does not exist.
protect_level_invalid 400 Bad request Invalid protect level has been sent

Uploading the video file

Using the credentials in the response above, you can upload your video file to our servers. Once you log in to the FTP server, you should put your file to the root, under a name that matches with the path value of the response, followed by the extension.

The url part of the response makes it easier to transfer files, with a single FTP command. For example if you have a file called test.mov, you can use the following FTP command to upload it:

ftp -u ftp://1_1234_1234567890:ftppw@red44.ustream.tv/1_12345_12345678901234.mov test.mov

Supported file extensions are: mkv, mp4, mov, flv, avi, wmv, ogm, mpeg2.

Don't forget to set your FTP client to binary file transfer mode, before uploading the video file.

Sending "file in place" signal

PUT https://api.ustream.tv/channels/CHANNEL_ID/uploads/VIDEO_ID.FORMAT (format can be json or xml)
Parameters
parameter type importance Description
status string REQUIRED Upload status (it should be "ready")
Response

On success a response with HTTP status 202 Accepted is returned.

Error codes
error value HTTP response code Error conditions
not_found 404 Not Found The given channel does not exist.

Check status of processing

GET https://api.ustream.tv/channels/CHANNEL_ID/uploads/VIDEO_ID.FORMAT (format can be json or xml)
Parameters

This request has no parameters.

Response

A key-value pair with details of the status. Example:

{
	"status":"transferred"
}
Available statuses
  • initiated
  • transferred
  • queued
  • pending
  • transcoding
  • complete
  • error
Error codes
error value HTTP response code Error conditions
not_found 404 Not Found The given channel does not exist.

Deleting a video

Permanently delete a video from the current account.

DELETE https://api.ustream.tv/videos/VIDOE_ID.FORMAT (format can be json or xml)
Parameters

This request has no parameters.

Response

On success a response with HTTP status 200 OK is returned.

Error codes
error value HTTP response code Error conditions
lack_of_ownership 403 Forbidden The given video does not belong to the user.
not_found 404 Not Found The given video does not exist.

Video expiration

A video gets deleted when expires. These videos can be saved by setting the time of the expiration.

Getting video expiration

GET https://api.ustream.tv/videos/VIDEO_ID/expiration.FORMAT (format can be json or xml)
Parameters

This request has no parameters.

Response

On success a response with HTTP status 200 OK is returned.

key type Description
rule string Valid values: never, at_given_time
expires_at integer If rule field is at_given_time, expires_at contains the UNIX timestamp of the expiration. If the rule is never, expires_at field is not provided.
Error codes
error value HTTP response code Error conditions
lack_of_ownership 403 Forbidden The api user is not allowed to manage the given channel
forbidden 403 Forbidden Managing the expiration is disabled at system level or user has no permission to manage the expiration of videos.
not_found 404 Not found The specified video_id does not exist

Setting video expiration

PUT https://api.ustream.tv/videos/VIDEO_ID/expiration.FORMAT (format can be json or xml)
Parameters
parameter type importance Description
rule string REQUIRED Supported value: never.
Response

On success a response with HTTP status 200 OK is returned.

Error codes
error value HTTP response code Error conditions
bad_request 400 Bad request Invalid request body: either rule is not provided or rule value is not valid.
lack_of_ownership 403 Forbidden The api user is not allowed to manage the given channel
forbidden 403 Forbidden Setting the expiration is disabled at system level or user has no permissions to modify the expiration of videos.
not_found 404 Not found The specified video_id does not exist

Video thumbnail

You can set a video thumbnail by uploading a picture or selecting a frame. The picture should be less than 10MB in size and smaller than 4000x4000px.

Uploading a thumbail

POST https://api.ustream.tv/videos/VIDEO_ID/thumbnail.FORMAT (format can be json or xml)
Parameters
parameter type importance Description
thumbnail file REQUIRED The thumbnail image.
Response

On success a response with HTTP status 204 No content is returned.

Selecting a frame

POST https://api.ustream.tv/videos/VIDEO_ID/thumbnail/frame.FORMAT (format can be json or xml)
Parameters
parameter type importance Description
position float REQUIRED The position of the selected frame in seconds.
Response

On success a response with HTTP status 204 No content is returned.

Video labels

A video can have multiple labels. With these API calls you can add and remove labels to/from a video.

Creating a new label

POST https://api.ustream.tv/users/self/labels.FORMAT (format can be json or xml)
Parameters
parameter type importance Description
label_name string REQUIRED The name of the label.
Response

A list of key-value pairs under a "label" key. Example:

{
	"label": {
		"18010": {
			"label_id": 18010,
			"label_name": "labelname",
			"label_color": "color-5"
		}
	}
  }

Listing labels

GET https://api.ustream.tv/users/self/labels.FORMAT (format can be json or xml)
Parameters

None.

Response

A list of key-value pairs under a "labels" key. Example:

{
	"labels": {
		"18010": {
		"label_id": 18010,
		"label_name": "labelname",
		"label_color": "color-5"
		},
		...
	}
}

Modifying a label

PUT https://api.ustream.tv/users/self/label/LABEL_ID.FORMAT (format can be json or xml)
Parameters
parameter type importance Description
label_name string REQUIRED The name of the label.
Response

On success a response with HTTP status 204 No content is returned.

Deleting a label

DELETE https://api.ustream.tv/users/self/label/LABEL_ID.FORMAT (format can be json or xml)
Parameters

None.

Response

On success a response with HTTP status 204 No content is returned.

Adding labels to a video

PUT https://api.ustream.tv/videos/VIDEO_ID/labels.FORMAT (format can be json or xml)
Parameters
parameter type importance Description
label_ids array REQUIRED The label ids to add to the video.
Response

On success a response with HTTP status 204 No content is returned.

Removing labels from a video

DELETE https://api.ustream.tv/videos/VIDEO_ID/labels.FORMAT (format can be json or xml)
Parameters
parameter type importance Description
label_ids array REQUIRED The label ids to remove from the video.
Response

On success a response with HTTP status 204 No content is returned.

Getting the labels of a video

GET https://api.ustream.tv/videos/VIDEO_ID/labels.FORMAT (format can be json or xml)
Parameters

None.

Response

A list of key-value pairs under a "labels" key. Example:

{
	"labels": {
		"18010": {
		"label_id": 18010,
		"label_name": "labelname",
		"label_color": "color-5"
		},
		...
	}
}

Video trim

You can set video playback start and end point in seconds. Trimming does not affect the original video file.

Set trim

Please note that unsaved auto-recorded videos will become saved when trimming them.

PUT https://api.ustream.tv/videos/VIDEO_ID/trim.FORMAT (format can be json or xml)
Parameters
parameter type importance Description
start integer REQUIRED Trim video from this second
end integer REQUIRED Trim video until this second
Response

On success a response with HTTP status 204 No content is returned.

Error codes
error value HTTP response code Error conditions
bad_request 400 Bad request Invalid start or end time (minimum trim length is 10 seconds)

Get trim

GET https://api.ustream.tv/videos/VIDEO_ID/trim.FORMAT (format can be json or xml)
Parameters

None.

Response

On success a response with HTTP status 200 OK is returned.

key type Description
start integer Video trimmed from this second
end integer Video trimmed until this second
{
	"trim": {
		"start": 323,
		"end": 252
  	}
}

Remove trim

DELETE https://api.ustream.tv/videos/VIDEO_ID/trim.FORMAT (format can be json or xml)
Parameters

None.

Response

On success a response with HTTP status 200 OK is returned.

Video copy

Save a part of on existing video as a new video. The new video will be available on same channel as the original one and it will be unpublished by default.

Create copy

Copy is an async process, you will get a request id in the response.

POST https://api.ustream.tv/videos/VIDEO_ID/copy.FORMAT (format can be json or xml)
Parameters
parameter type importance Description
start integer REQUIRED Copy video from this second
end integer REQUIRED Copy video until this second
title string REQUIRED Title of the new video
description string OPTIONAL Description of the new video
Response

On success a response with HTTP status 202 Accepted is returned.

key type Description
request_id string ID of the copy request
status_url string URL where you can check the status of the copy request
Error codes
error value HTTP response code Error conditions
bad_request 400 Bad request Invalid copy parameters (minimum copy length is 10 seconds)

Check copy status

GET https://api.ustream.tv/videos-copy-status/REQUEST_ID.FORMAT (format can be json or xml)
Response

On success a response with HTTP status 200 OK is returned.

key type Description
is_finished boolean Status of the copy process
video_id integer ID of the new video
video_url string The URL of the new video resource

Video chapters

Get video chapters

GET https://api.ustream.tv/videos/VIDEO_ID/chapters.FORMAT (format can be json or xml)
Response

A list of key-value pairs under a "chapters" key.

Example:

{
	"chapters": [
    	{
            "id": "1",
            "title": "First chapter",
            "position": 10
    	},
    	{
            "id": "2",
            "title": "Second chapter",
            "position": 60
    	}
	]
}

Explanation of some values:

key type Description
position float The beginning of the chapter, provided in seconds.
Error codes
error value HTTP response code Error conditions
unauthorized 401 Authorization required The video is protected, only the owner with a valid token can access it.
lack_of_ownership 403 Forbidden The given video does not belong to the user.
not_found 404 Not Found The given video does not exist.

Add new chapter to the video

POST https://api.ustream.tv/videos/VIDEO_ID/chapters.FORMAT (format can be json or xml)
parameter type importance Description
title string REQUIRED Chapter title
position int REQUIRED Chapter position
Response

On success a response with HTTP status 201 Created is returned.

Error codes
error value HTTP response code Error conditions
invalid_value 400 Bad Request The specified value is invalid or unsupported.
unauthorized 401 Authorization required Only the video's owner with a valid token can create new chapters.
lack_of_ownership 403 Forbidden The given video does not belong to the user.
not_found 404 Not Found The given video does not exist.

Delete all chapters of a video

DELETE https://api.ustream.tv/videos/VIDEO_ID/chapters.FORMAT (format can be json or xml)
Response

On success a response with HTTP status 200 OK is returned.

Error codes
error value HTTP response code Error conditions
unauthorized 401 Authorization required Only the video's owner with a valid token can delete chapters.
lack_of_ownership 403 Forbidden The given video does not belong to the user.
not_found 404 Not Found The given video does not exist.

Get chapter info

GET https://api.ustream.tv/videos/VIDEO_ID/chapters/CHAPTER_ID.FORMAT (format can be json or xml)
Response

Key-value pairs under a "chapter" key.

Example:

{
	"chapter": {
		"id": "1",
		"title": "First chapter",
		"position": 10
	}
}

Explanation of some values:

key type Description
position float The beginning of the chapter, provided in seconds.
Error codes
error value HTTP response code Error conditions
unauthorized 401 Authorization required The given video is private or the channel is protected. A valid token is required.
lack_of_ownership 403 Forbidden The given video is private or the channel is protected and the video does not belong to the user.
not_found 404 Not Found The given video chapter does not exist.

Modify video chapter

PUT https://api.ustream.tv/videos/VIDEO_ID/chapters/CHAPTER_ID.FORMAT (format can be json or xml)
parameter type importance Description
title string REQUIRED Chapter title
position int REQUIRED Chapter position
Response

On success a response with HTTP status 200 OK is returned.

Error codes
error value HTTP response code Error conditions
invalid_value 400 Bad Request The specified value is invalid or unsupported.
unauthorized 401 Authorization required Only the video's owner with a valid token can modify chapters.
lack_of_ownership 403 Forbidden The given video does not belong to the user.
not_found 404 Not Found The given video or chapter does not exist.

Delete video chapter

DELETE https://api.ustream.tv/videos/VIDEO_ID/chapters/CHAPTER_ID.FORMAT (format can be json or xml)
Response

On success a response with HTTP status 200 OK is returned.

Error codes
error value HTTP response code Error conditions
invalid_value 400 Bad Request The specified value is invalid or unsupported.
unauthorized 401 Authorization required Only the video's owner with a valid token can delete chapters.
lack_of_ownership 403 Forbidden The given video does not belong to the user.
not_found 404 Not Found The given video or chapter does not exist.

Playlists

List the user's playlists

Get the playlists of the authenticated user.

GET https://api.ustream.tv/playlists.FORMAT (format can be json or xml)
Parameters
parameter type importance Description
page integer OPTIONAL Requested page number (1 by default)
pagesize integer OPTIONAL Requested page size (50 by default, max 50)
filter_empty_playlists integer OPTIONAL If the value is 1 then empty playlists will not be returned (0 by default)
Response

Key-value pairs under a "playlists" key. Example:

{
	"playlists": [
		{
			"id": "111",
			"title": "Title of a playlist",
			"total_duration": "176.256",
			"created_at": 1484127917,
			"updated_at": 1486569501,
			"channel_id": 11223344
		},
		...
	]
}

Explanation of some values:

key type Description
total_duration string The sum of the duration of the videos added to the playlist in seconds.

The paging information can be found under the "paging" element. Example:

"paging": {
	"previous": "https://api.ustream.tv/playlists.json?pagesize=PAGE_SIZE&page=PREVIOUS_PAGE",
	"next": "https://api.ustream.tv/playlists.json?pagesize=PAGE_SIZE&page=NEXT_PAGE",
	"page_count": 8,
	"item_count": 38
}
Error codes
error value HTTP response code Error conditions
invalid_token 401 Authorization required The provided Access Token is missing, revoked, expired or malformed

Create a playlist

Create a new playlist for the authenticated user.

POST https://api.ustream.tv/playlists.FORMAT (format can be json or xml)
Parameters
parameter type importance Description
title string REQUIRED The title of the playlist.

The request body must contain the playlist title ("title" field).

Example:

POST playlists.json HTTP/1.1
Host: api.ustream.tv
Authorization: Bearer 3c2573673b782f6544405a22636f3d5d3b6f3950
Content-Type: application/x-www-form-urlencoded

title=API+Testing+Playlist

The token in the above call is only an example.

Successful response

The response will contain the following headers:

Header Type Meaning
Location string The URL of the new playlist.
{
	"playlist": {
		"id": "111",
		"title": "API Testing Playlist",
		"total_duration": "176.256",
		"created_at": 1484127917,
		"updated_at": 1486569501,
		"channel_id": 11223344
	}
}
Error codes
error value HTTP response code Error conditions
invalid_token 401 Unauthorized The provided Access Token is missing, revoked, expired or malformed
bad_request 400 Bad request The playlist title is missing

Playlist details

Get the details of a playlist

GET https://api.ustream.tv/playlists/PLAYLIST_ID.FORMAT (format can be json or xml)
Response

Key-value pairs under a "playlist" key. Example:

{
"playlist": {
		"id": "111",
		"title": "Title of a playlist",
		"total_duration": "176.256",
		"created_at": 1484127917,
		"updated_at": 1486569501,
		"channel_id": 11223344
	}
}

Explanation of some values:

key type Description
total_duration string The sum of the duration of the videos added to the playlist in seconds.
Error codes
error value HTTP response code Error conditions
invalid_token 401 Authorization required If the playlist does not belong to a channel then the request must include a valid access token.
permission_denied 403 Permission denied If the playlist does not belong to a channel then the authenticated user needs access to the playlist.
not_found 404 Not found This error code is returned in the following cases:
  • The playlist does not exist.
  • In case of a channel playlist and if either the channel does not exist or playlists on the channel page are not enabled.

Modify a playlist

Modify an existing playlist.

PUT https://api.ustream.tv/playlists/PLAYLIST_ID.FORMAT (format can be json or xml)
Parameters
parameter type importance Description
title string REQUIRED The title of the playlist.

The request body must contain the playlist title ("title" field).

Example:

PUT playlists/PLAYLIST_ID.json HTTP/1.1
Host: api.ustream.tv
Authorization: Bearer 3c2573673b782f6544405a22636f3d5d3b6f3950
Content-Type: application/x-www-form-urlencoded

title=API+Testing+Playlist+edited

The token in the above call is only an example.

Successful response
HTTP response code Description
200 OK The playlist has been successfully updated.
Error codes
error value HTTP response code Error conditions
bad_request 400 Bad request The playlist title is missing
invalid_token 401 Authorization required The provided Access Token is missing, revoked, expired or malformed
permission_denied 403 Permission denied The authenticated user does not have access to the playlist.
not_found 404 Not found The playlist does not exist.

Delete a playlist

Delete an existing playlist.

DELETE https://api.ustream.tv/playlists/PLAYLIST_ID.FORMAT (format can be json or xml)

Example:

DELETE playlists/PLAYLIST_ID.json HTTP/1.1
Host: api.ustream.tv
Authorization: Bearer 3c2573673b782f6544405a22636f3d5d3b6f3950
Content-Type: application/x-www-form-urlencoded

The token in the above call is only an example.

Successful response
HTTP response code Description
200 OK The playlist has been successfully deleted.
Error codes
error value HTTP response code Error conditions
invalid_token 401 Authorization required The provided Access Token is missing, revoked, expired or malformed
permission_denied 403 Permission denied The authenticated user does not have access to the playlist.
not_found 404 Not found The playlist does not exist.

Playlist videos

List playlist videos

GET https://api.ustream.tv/playlists/PLAYLIST_ID/videos.FORMAT (format can be json or xml)
Parameters
parameter type importance Description
page integer OPTIONAL Requested page number (1 by default)
pagesize integer OPTIONAL Requested page size (200 by default, max 200)
detail_level string OPTIONAL Verbosity level. Possible value: "minimal". In case of minimal verbosity level the result set is limited to id, and links data. If the channel is protected (see security section), only minimal data can be retrieved without a valid access token.
Response

A list of key-value pairs under a "videos" element.

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

Example:

{
"videos": [{
		"id": "111",
		"title": "Title of video",
		"description": "Description of video",
		"url": "http://www.ustream.tv/recorded/111",
		"length": "12345.123456",
		"created_at": 1399388736,
		"file_size": "120000",
		"views": 0,
		"thumbnail": {
			"default": "https://ustvstaticcdn1-a.akamaihd.net/111.jpg"
		},
		"media_urls": {
			"flv": "http://tcdn.ustream.tv/video/111"
		},
		"links": {
			"channel": {
				"href": "https://api.ustream.tv/channels/1.json",
				"id": "1"
			}
		}
	},
	...
	]
}

Minimal response example:

"video": {
	"id": "111",
	"links": {
		"channel": {
			"href": "https://api.ustream.tv/channels/1.json",
			"id": "1"
		}
	}
}

Explanation of some values:

key type Description
length string Video length in seconds
created_at int Video create date in UNIX timestamp
file_size string Video file size in bytes

The paging information can be found under the "paging" element. Example:

"paging": {
	"previous": "https://api.ustream.tv/playlists/PLAYLIST_ID/videos.json?pagesize=PAGE_SIZE&page=PREVIOUS_PAGE",
	"next": "https://api.ustream.tv/playlists/PLAYLIST_ID/videos.json?pagesize=PAGE_SIZE&page=NEXT_PAGE",
	"page_count": 8,
	"item_count": 38
}
Error codes
error value HTTP response code Error conditions
invalid_token 401 Authorization required If the playlist does not belong to a channel then the request must include a valid access token.
permission_denied 403 Permission denied If the playlist does not belong to a channel then the authenticated user needs access to the playlist.
not_found 404 Not found

This error code is returned in the following cases:

  • The playlist does not exist.
  • In case of a channel playlist the playlists on the channel page are not shown.

Playlist video

Get the details of a video in a playlist

GET https://api.ustream.tv/playlists/PLAYLIST_ID/videos/VIDEO_ID.FORMAT (format can be json or xml)
Response

Key-value pairs under a "video" key.

Example:

{
  "video": {
    "id": "92858030",
    "title": "SampleVideo 1280x720 30mb",
    "number_of_thumbnails": 1,
    "picture_revision": 2,
    "channel_id": "22818603",
    "video_views": 10,
    "thumbnail": "http://static-cdn1.ustream.tv/i/video/picture/0/1/92/92858/92858030/1_22818603_92858030,192x108,b,1:2.jpg",
    "created_at": 1479718322,
    "order": 1
  }
}

Explanation of some values:

key type Description
picture_revision int The revision of the thumbnail picture
created_at int Video create date in UNIX timestamp
order int The video's position in the playlist.
Error codes
error value HTTP response code Error conditions
invalid_token 401 Authorization required If the playlist does not belong to a channel then the request must include a valid access token.
permission_denied 403 Permission denied If the playlist does not belong to a channel then the authenticated user needs access to the playlist.
not_found 404 Not found

This error code is returned in the following cases:

  • The playlist does not exist.
  • In case of channel playlist, the channel does not exists or the playlists on the channel page are not enabled.
  • The given video is not in the playlist.

Add video to playlist

PUT https://api.ustream.tv/playlists/PLAYLIST_ID/videos/VIDEO_ID.FORMAT (format can be json or xml)
Successful response

The response will contain the following collection limit headers:

Header Type Description
X-Collection-Limit int The maximum number of videos that can be added to a playlist.
X-Collection-Remaining int How many more videos can be added to the playlist.
Error codes
error value HTTP response code Error conditions
invalid_token 401 Authorization required The provided Access Token is missing, revoked, expired or malformed.
permission_denied 403 Permission denied The authenticated user does not have access to the playlist or to the video.
not_found 404 Not found The playlist does not exist.
limit_reached 413 Request entity too large The number of videos in the playlist have reached the limit. Check the returned collection limit headers.

Delete a video from the playlist

DELETE https://api.ustream.tv/playlists/PLAYLIST_ID/videos/VIDEO_ID.FORMAT (format can be json or xml)
Successful response

The response will contain the following collection limit headers:

Header Type Description
X-Collection-Limit int The maximum number of videos that can be added to a playlist.
X-Collection-Remaining int How many more videos can be added to the playlist.
Error codes
error value HTTP response code Error conditions
invalid_token 401 Authorization required The provided Access Token is missing, revoked, expired or malformed.
permission_denied 403 Permission denied The authenticated user does not have access to the playlist.
not_found 404 Not found The playlist does not exist.

Reposition video on the playlist

PUT https://api.ustream.tv/playlists/PLAYLIST_ID/videos/VIDEO_ID/position.FORMAT (format can be json or xml)
Parameters
parameter type importance Description
position int REQUIRED The new position of the video in the playlist.

The body of the call must contain the video position. The Content-Type of the request should be application/x-www-form-urlencoded.

Example:

PUT playlists/PLAYLIST_ID/videos/VIDEO_ID/position.json HTTP/1.1
Host: api.ustream.tv
Authorization: Bearer 3c2573673b782f6544405a22636f3d5d3b6f3950
Content-Type: application/x-www-form-urlencoded

position=3

The token in the above call is only an example.

Successful response
HTTP response code Description
200 OK The video has been successfully been repositioned.
Error codes
error value HTTP response code Error conditions
bad_request 400 Bad request The position parameter is either missing or out of range
invalid_token 401 Authorization required The provided Access Token is missing, revoked, expired or malformed
permission_denied 403 Permission denied The authenticated user does not have access to the playlist or to the video
not_found 404 Not found The playlist does not exist or the video is not on the playlist

Channel playlists

Channel playlists do not directly belong to a user but to a channel and can be shown on the channel page.

List the playlists of a channel

GET https://api.ustream.tv/channels/CHANNEL_ID/playlists.FORMAT (format can be json or xml)
Parameters
parameter type importance Description
page integer OPTIONAL Requested page number (1 by default)
pagesize integer OPTIONAL Requested page size (50 by default, max 50)
filter_empty_playlists integer OPTIONAL If the value is 1 then empty playlists will not be returned (0 by default)
Response

Key-value pairs under a "playlists" key. Example:

{
"playlists": [
		{
			"id": "111",
			"title": "Title of a playlist",
			"total_duration": "176.256",
			"created_at": 1484127917,
			"updated_at": 1486569501,
			"channel_id": 11223344
		},
		...
	]
}

Explanation of some values:

key type Description
total_duration string The sum of the duration of the videos added to the playlist in seconds.

The paging information can be found under the "paging" element. Example:

"paging": {
	"previous": "https://api.ustream.tv/channels/CHANNEL_ID/playlists.json?pagesize=PAGE_SIZE&page=PREVIOUS_PAGE",
	"next": "https://api.ustream.tv/channels/CHANNEL_ID/playlists.json?pagesize=PAGE_SIZE&page=NEXT_PAGE",
	"page_count": 8,
	"item_count": 38
}
Error codes
error value HTTP response code Error conditions
not_found 404 Not found The channel does not exists or the playlists are not shown on the channel page.

Create a channel playlist

POST https://api.ustream.tv/channels/CHANNEL_ID/playlists.FORMAT (format can be json or xml)
Parameters
parameter type importance Description
title string REQUIRED The title of the playlist.
is_enabled int OPTIONAL Whether the playlist is enabled or not. Values: 1 (enabled), 0 (disabled). (1 by default)

Example:

POST playlists.json HTTP/1.1
Host: api.ustream.tv
Authorization: Bearer 3c2573673b782f6544405a22636f3d5d3b6f3950
Content-Type: application/x-www-form-urlencoded

title=API+Testing+Playlist&is_enabled=1

The token in the above call is only an example.

Successful response

The response will contain the following headers:

Header Type Meaning
Location string The URL of the new playlist.
Error codes
error value HTTP response code Error conditions
invalid_token 401 Unauthorized The provided Access Token is missing, revoked, expired or malformed
bad_request 400 Bad request The playlist title is missing
permission_denied 403 Permission denied The authenticated user does not have access to the channel.
not_found 404 Not found The channel could not be found.

Event

Listing the upcoming events of a channel

Get a detailed list of the events of a channel

GET https://api.ustream.tv/channels/CHANNEL_ID/upcoming-events.FORMAT (format can be json or xml)
Parameters
parameter type importance Description
page integer OPTIONAL Requested page number (1 by default)
pagesize integer OPTIONAL Requested page size (50 by default, max 50)
Response

A list of key-value pairs under an "events" key. Example:

{
	"events": [
		{
			"id": "111",
			"title": "Title of the event",
			"description": "Description of the event",
			"start": 1399388736,
			"duration": 900,
		},
		...
	]
}

Explanation of some values:

key type Description
start int Event start date in UNIX timestamp
duration int Expected duration of the event in seconds

The paging information can be found under the "paging" element. Example:

{
	"paging": {
		"previous": "https://api.ustream.tv/CHANNEL_ID/upcoming-events.json?pagesize=PAGE_SIZE&page=PREVIOUS_PAGE",
		"next": "https://api.ustream.tv/channels/CHANNEL_ID/upcoming-events.json?pagesize=PAGE_SIZE&page=NEXT_PAGE"
	}
}
Error codes
error value HTTP response code Error conditions
invalid_token 401 Authorization required The event list is protected, only the owner with a valid token can access it.
not_found 404 Not Found The given channel does not exist.

Channel hooks

Hooks can be registered for different channel events. When a channel event is fired, a HTTP POST request is sent to the registered hook recipient URL. You can use to these endpoints with Client Credentials.

Hook registration

PUT https://api.ustream.tv/channels/CHANNEL_ID/hooks/EVENT.FORMAT (format can be json or xml)
Parameters
parameter type importance Description
recipient string REQUIRED The URL where the event notifications will be sent.
Response

On success a response with HTTP status 204 No content is returned.

Error codes
error value HTTP response code Error conditions
not_found 404 Not found The given channel does not exist
bad_request 400 Bad request Some of the incoming parameters are invalid.

Getting a channel hook

GET https://api.ustream.tv/channels/CHANNEL_ID/hooks/EVENT.FORMAT (format can be json or xml)
Parameters

This request has no parameters.

Response

On success a response with HTTP status 200 OK is returned.

key type Description
recipient string the hook recipient URL
status string pending, active or suspended
Error codes
error value HTTP response code Error conditions
not_found 404 Not found Channel does not exist or no hook registered for the channel

Deleting a channel hook

DELETE https://api.ustream.tv/channels/CHANNEL_ID/hooks/EVENT.FORMAT (format can be json or xml)
Parameters

This request has no parameters.

Response

On success a response with HTTP status 200 OK is returned.

Error codes
error value HTTP response code Error conditions
not_found 404 Not found Channel not found
bad_request 400 Bad request Invalid event type.

Supported events

Event Description
channel.status.live A channel goes live
channel.status.offair A channel goes offair
video.create A video created (uploaded, recorded) on a channel
video.deleted A video deleted from a channel

Handshake method

A newly registered hook is inactive by default. In order to make it active, a basic handshake must be implemented at the recipient URL before the hook registration.

After the hook was registered a POST request is sent to the recipient URL with a X-Hook-Secret HTTP header. Recipients must reply to this request with the same secret string in their X-Hook-Secret response header to make sure that the registered recipient URL is owned by the API user. This handshake request will also contain an "event" and "channelId" in the body (JSON encoded) property with the corresponding values of your freshly registered hook. Using these values you can re-use the same hook to handle multiple secrets based on these identifiers.

Handshake example

Your app needs to be notified about channel 123 whenever it goes live, so the app initiates a new hook.

POST /channels/123/hooks/channel.status.live.json HTTP/1.1
Host: api.ustream.tv
Authorization: Bearer 782f6544405a22636f3d5d3b63c2573673bf3950
Content-Type: application/x-www-form-urlencoded

recipient=http://your-app.url/hook-receiver

If everything went smoothly, your app will get simply:

HTTP/1.1 204 No Content

Asynchronously, the handshake mechanism will start promptly, our hook server will call your hook to exchange a secret.

POST /hook-receiver HTTP/1.1
Host: your-app.url
Content-Type: application/json
Content-Length: 46
X-Hook-Secret: open-sesame!

{
	"event": "channel.status.live",
	"channelId": 123
}

Your hook implementation should store that secret and echo the X-Hook-Secret header in the response.

HTTP/1.1 200 OK
Content-Length: 0
X-Hook-Secret: open-sesame!

Receiving webhook events

On an event triggered interested by you, our hook server will call your receiver:

POST /hook-receiver HTTP/1.1
Host: your-app.url
Content-Type: application/json
Content-Length: 76
X-Hook-Signature: 61f34d324ac51dde1288825dab2111
Channel event example
{
	"event": "channel.status.live",
	"channelId": 123
}
Video event example
{
	"event": "video.create",
	"videoId": 456
}

Your receiver should verify the signature provided in the request X-Hook-Signature header, using HMAC-SHA1 algorithm with the the previously exchanged secret and the full request body as-is.