The Content-Length header is automatically populated by curl. If using another method to access the API, you must calculate and populate the Content-Length header.
Request Headers
Header
Description
Authorization (required)
Use HTTP Basic Authentication with your applicationId and secret
Request Fields
Field
Description
channel (required)
Channel Object
Channel Object
Field
Description
alias (required)
A user friendly unique identifier for the channel. An empty string is required if you want the Streaming platform to generate an alias for your channel.
name (required)
Unique name of the channel.
description (required)
A description for the channel.
options (required)
An array of options for the channel. An empty array is required if there are no options.
Creating a Channel Response
The platform will return a successful response that contains a "status" field. The HTTP status code is set according to the "status" field.
The streaming platform was not able to authorize the provided credentials.
409 Conflict
already-exists
never
The channel already exists.
4XX
varies
never
Indicates an issue with the request.
503 Service Unavailable
capacity
once
The system is temporarily overloaded. Please try again later.
504 Gateway Timeout
rate-limited
once immediately, then exponential backoff
The system is temporarily overloaded. Please try again later.
5XX
varies
once immediately, then exponential backoff
A transient server error.
Error Responses: Please be aware that some server errors 5XX and request validation errors 400 and 401 may result in an arbitrary response body not encoded in JSON.
Encoding: Channel ID may contain characters that are unsafe for URLs. Be sure to encode the ChannelId in the URL path. For example, the URL encoding of `us-central#us-central` is `us-central%23us-central`
Request URI
Component
Description
urlEncodedChannelId (required)
URL encoded ID of the channel
Request Headers
Header
Description
Authorization (required)
Use HTTP Basic Authentication with your applicationId and secret
Fetching a Channel Response
The platform will return a successful response that contains a "status" field. The HTTP status code is set according to the "status" field.
The streaming platform was not able to authorize the provided credentials.
404 Not Found
not-found
never
The channel does not exist.
4XX
varies
never
Indicates an issue with the request.
503 Service Unavailable
capacity
once
The system is temporarily overloaded. Please try again later.
504 Gateway Timeout
rate-limited
once immediately, then exponential backoff
The system is temporarily overloaded. Please try again later.
5XX
varies
once immediately, then exponential backoff
A transient server error.
Error Responses: Please be aware that some server errors 5XX and request validation errors 400 and 401 may result in an arbitrary response body not encoded in JSON.
Encoding: Channel ID may contain characters that are unsafe for URLs. Be sure to encode the ChannelId in the URL path. For example, the URL encoding of `us-central#us-central` is `us-central%23us-central`
Request URI
Component
Description
urlEncodedRoomId (required)
ID of the channel.
Request Headers
Header
Description
Authorization (required)
Use HTTP Basic Authentication with your applicationId and secret
Fetching Members of a Channel Response
The API call returns an HTTP response per the following:
The streaming platform was not able to authorize the provided credentials.
404 Not Found
not found
never
The channel was not found.
4XX
varies
never
Indicates an issue with the request.
503 Service Unavailable
capacity
once
The system is temporarily overloaded. Please try again later.
504 Gateway Timeout
rate-limited
once immediately, then exponential backoff
The system is temporarily overloaded. Please try again later.
504 Gateway Timeout
time-exceeded
once immediately, then exponential backoff
The request took to long to execute. Please try again later.
5XX
varies
once immediately, then exponential backoff
A transient server error.
Error Responses: Please be aware that some server errors 5XX and request validation errors 400 and 401 may result in an arbitrary response body not encoded in JSON.
Encoding: Channel ID may contain characters that are unsafe for URLs. Be sure to encode the ChannelId in the URL path. For example, the URL encoding of `us-central#us-central` is `us-central%23us-central`
The Content-Length header is automatically populated by curl. If using another method to access the API, you must calculate and populate the Content-Length header.
Request URI
Component
Description
urlEncodedChannelId (required)
URL encoded ID of the channel
Request Headers
Header
Description
Authorization (required)
Use HTTP Basic Authentication with your applicationId and secret
Deleting a Channel Response
The platform will return a successful response that contains a "status" field. The HTTP status code is set according to the "status" field.
HTTP
1HTTP/1.1 200 OK
2Content-Type: application/json; charset=utf-8
3Content-Length: 15
4
5{"status":"ok"}
cURL
1{
2"status":"ok"
3}
Delete Channel API Status Codes
HTTP
Status
Retry
Description
200 OK
ok
never
Channel was successfully deleted.
400 Bad Request
varies
never
Indicates an issue with the request.
401 Unauthorized
unauthorized
never
The streaming platform was not able to authorize the provided credentials.
4XX
varies
never
Indicates an issue with the request.
503 Service Unavailable
capacity
once
The system is temporarily overloaded. Please try again later.
5XX
varies
once immediately, then exponential backoff
A transient server error.
Error Responses: Please be aware that some server errors 5XX and request validation errors 400 and 401 may result in an arbitrary response body not encoded in JSON.
This API allows the caller to copy the active members (that is, the publishers) from one channel to another channel. Both the source and destination channels must have previously been created.
A stream will be associated with the destination channel which is a fork of the stream being published to the source channel with the same content.
Fork a Channel Request
Send a PUT request to the /pcast/channel/<urlEncodedDestinationChannelId>/fork/<urlEncodedSourceChannelId> endpoint as shown:
Encoding: Channel ID may contain characters that are unsafe for URLs. Be sure to encode the ChannelId in the URL path. For example, the URL encoding of `us-central#us-central` is `us-central%23us-central`
The Content-length header is automatically populated by curl. If using another method to access the API, you must calculate and populate the Content-length header.
Request URI
Component
Description
urlEncodedSourceChannelId (required)
URL encoded Channel ID of the source channel to fork from.
urlEncodedDestinationChannelId (required)
URL encoded Channel ID of the destination channel to fork into.
Request Headers
Header
Description
Authorization (required)
Use HTTP Basic Authentication with your applicationId and secret
Request Fields
Field
Description
streamTags (optional)
An array of tags (strings) to apply to the destination streams.
streamCapabilities (optional)
An array of capabilities (strings) to apply to the newly forked stream.
options (optional)
An array of options (strings) for the channel. Current valid options are: "force", "additive" and "keep-streams". The default behavior is not touch the stream(s) with matching session IDs that are already publishing to the destination channel. With the "force" option, the stream(s) will be terminated and replaced. With the "additive" option, the stream(s) will be added to any existing members in the channel. "keep-streams" removes the members but leaves the streams alive. Clients will receive the member update, but they are not securely terminated from the stream. In Phenix client implementations the default is to end the client stream, but customer client implementations may vary.
Fork a Channel Response
The API call returns an HTTP response per the following:
Indicates an issue with the request. Eg: Options must be an array of strings.
401 Unauthorized
unauthorized
never
The streaming platform was not able to authorize the provided credentials.
404 Not Found
not found
never
One or both of the source and destination channels are not found.
4XX
varies
never
Indicates an issue with the request.
503 Service Unavailable
capacity
once
The system is temporarily overloaded. Please try again later.
504 Gateway Timeout
rate-limited
once immediately, then exponential backoff
The system is temporarily overloaded. Please try again later.
504 Gateway Timeout
time-exceeded
once immediately, then exponential backoff
The request took to long to execute. Please try again later.
5XX
varies
once immediately, then exponential backoff
A transient server error.
Error Responses: Please be aware that some server errors 5XX and request validation errors 400 and 401 may result in an arbitrary response body not encoded in JSON.
Encoding: Channel ID may contain characters that are unsafe for URLs. Be sure to encode the ChannelId in the URL path. For example, the URL encoding of `us-central#us-central` is `us-central%23us-central`
The Content-length header is automatically populated by curl. If using another method to access the API, you must calculate and populate the Content-length header.
Request URI
Component
Description
urlEncodedChannelId (required)
ID of the channel to kill.
Request Headers
Header
Description
Authorization (required)
Use HTTP Basic Authentication with your applicationId and secret
Request Fields
Field
Description
reason (optional)
Arbitrary text string for recording why the stream was killed.
options (optional)
An array of options (strings). Valid options are: "keep-streams". "keep-streams" removes the members but leaves the streams alive. Clients will receive the member update, but they are not securely terminated from the stream. In Phenix client implementations the default is to end the client stream, but customer client implementations may vary.
Kill a Channel Response
The API call returns an HTTP response per the following:
Indicates an issue with the request. Eg: Options must be an array of strings.
401 Unauthorized
unauthorized
never
The streaming platform was not able to authorize the provided credentials or Field "reason" must be a string.
404 Not Found
not found
never
The channel was not found.
4XX
varies
never
Indicates an issue with the request.
503 Service Unavailable
capacity
once
The system is temporarily overloaded. Please try again later.
504 Gateway Timeout
rate-limited
once immediately, then exponential backoff
The system is temporarily overloaded. Please try again later.
504 Gateway Timeout
time-exceeded
once immediately, then exponential backoff
The request took to long to execute. Please try again later.
5XX
varies
once immediately, then exponential backoff
A transient server error while processing the request.
Error Responses: Please be aware that some server errors 5XX and request validation errors 400 and 401 may result in an arbitrary response body not encoded in JSON.
Encoding: Channel ID may contain characters that are unsafe for URLs. Be sure to encode the ChannelId in the URL path. For example, the URL encoding of `us-central#us-central` is `us-central%23us-central`
The Content-Length header is automatically populated by curl. If using another method to access the API, you must calculate and populate the Content-Length header.
Request URI
Component
Description
urlEncodedChannelId (required)
URL encoded ID of the channel
Request URI Parameters
Parameter
Description
failIfLess (optional)
The number of required publishers that meet all criteria for the channel.
withStreams (optional)
The number of streams required per publisher to be considered active in the channel. Defaults to 1.
withScreenName (optional)
Only consider publishers with the given screen name. By default all screen names are considered.
Checking the State of a Channel Response
The platform will return a successful response that contains a "status" field. The HTTP status code is set according to the "status" field.
HTTP
1HTTP/1.1 200 OK
2Content-Type: application/json; charset=utf-8
3Content-Length: 1
4
51
cURL
11
Health Channel API Status Codes
HTTP
status
Retry
Description
200 OK
ok
never
Number of publishers was successfully reported.
400 Bad Request
varies
never
Indicates an issue with the request.
404 Not Found
not-found
never
Indicates the channel was not found.
4XX
varies
never
Indicates an issue with the request.
412 Precondition Failed
none
never
There is fewer than the required number of publishers.
503 Service Unavailable
capacity
once
The system is temporarily overloaded. Please try again later.
504 Gateway Timeout
rate-limited
once immediately, then exponential backoff
The system is temporarily overloaded. Please try again later.
504 Gateway Timeout
time-exceeded
once immediately, then exponential backoff
The request took to long to execute. Please try again later.
5XX
varies
once immediately, then exponential backoff
A transient server error.
Error Responses: Please be aware that some server errors 5XX and request validation errors 400 and 401 may result in an arbitrary response body not encoded in JSON.
Channel API Response fields
The response body is a text field with the number of publishers actively publishing a stream to the channel.
Universal Live Manifest for a Channel
This API allows to retrieve a live manifest of any type for a channel. The URL is valid for the lifetime of the channel and always points to the most recent stream in the channel. In order for this to work, the stream must have enabled streaming capability.
Universal Live Manifest for a Channel Request
Send a GET request to the /pcast/channel/<urlEncodedChannelId>/<manifest> endpoint as shown:
Encoding: Channel ID may contain characters that are unsafe for URLs. Be sure to encode the ChannelId in the URL path. For example, the URL encoding of `us-central#us-central` is `us-central%23us-central`
The Content-Length header is automatically populated by curl. If using another method to access the API, you must calculate and populate the Content-Length header.
Request URI
Component
Description
urlEncodedChannelId (required)
URL encoded ID of the channel
manifest (required)
The manifest ID such as live.m3u8 for HLS and live.mpd for DASH.
Request URI Parameters
Parameter
Description
streamToken (optional)
Streams protected with token-auth require a valid edge auth token to be provided. An edge auth token issued for the channel ID or alias will grant access to the playlist for the channel. Alternatively, if the origin stream ID is known, access can be restricted to just a stream itself.
Universal Live Manifest for a Channel Response
The platform will return a successful response that contains the content of the manifest. The HTTP status code is set according to if the manifest exists or not.
Encoding: Channel ID may contain characters that are unsafe for URLs. Be sure to encode the ChannelId in the URL path. For example, the URL encoding of `us-central#us-central` is `us-central%23us-central`
The Content-Length header is automatically populated by curl. If using another method to access the API, you must calculate and populate the Content-Length header.
Request Headers
Header
Description
Authorization (required)
Use HTTP Basic Authentication with your applicationId and secret
The streaming platform was not able to authorize the provided credentials.
404 Not Found
not-found
never
The channel does not exist.
413 Payload Too Large
varies
never
One of the fields exceeds the limits. The size limit for messages is 1024 bytes. The total limit for all tags is 512 bytes. The screen name and mime type each must not exceed 128 bytes.
4XX
varies
never
Indicates an issue with the request.
503 Service Unavailable
capacity
once
The system is temporarily overloaded. Please try again later.
504 Gateway Timeout
rate-limited
once immediately, then exponential backoff
The system is temporarily overloaded. Please try again later.
5XX
varies
once immediately, then exponential backoff
A transient server error.
Error Responses: Please be aware that some server errors 5XX and request validation errors 400 and 401 may result in an arbitrary response body not encoded in JSON.
Encoding: Channel ID may contain characters that are unsafe for URLs. Be sure to encode the ChannelId in the URL path. For example, the URL encoding of `us-central#us-central` is `us-central%23us-central`
Request Headers
Header
Description
Authorization (required)
Use HTTP Basic Authentication with your applicationId and secret
Request URI Parameters
Parameter
Description
limit (optional)
The number of messages to fetch. Defaults to 100.
beforeMessageId (optional)
The upper bound of the fetch range represented by another message ID.
afterMessageId (optional)
The lower bound of the fetch range represented by another message ID.
mimeTypes (optional)
Comma separated list of mime types. When provided only messages with the specified mime types will be returned. Note the search range is still the same so if no messages within the underlying range match then the result might be zero or less than the requested limit.
Fetching Messages Response
The platform will return a successful response that contains a "status" field. The HTTP status code is set according to the "status" field.
The streaming platform was not able to authorize the provided credentials.
404 Not Found
not-found
never
The channel does not exist.
413 Payload Too Large
limit-too-large
never
Too many messages are requested. The maximal limit is 128 messages per request.
4XX
varies
never
Indicates an issue with the request.
503 Service Unavailable
capacity
once
The system is temporarily overloaded. Please try again later.
504 Gateway Timeout
rate-limited
once immediately, then exponential backoff
The system is temporarily overloaded. Please try again later.
5XX
varies
once immediately, then exponential backoff
A transient server error.
Error Responses: Please be aware that some server errors 5XX and request validation errors 400 and 401 may result in an arbitrary response body not encoded in JSON.
Encoding: Channel ID may contain characters that are unsafe for URLs. Be sure to encode the ChannelId in the URL path. For example, the URL encoding of `us-central#us-central` is `us-central%23us-central`
The Content-Length header is automatically populated by curl. If using another method to access the API, you must calculate and populate the Content-Length header.
Request URI
Component
Description
urlEncodedChannelId (required)
URL encoded ID of the channel
Request Headers
Header
Description
Authorization (required)
Use HTTP Basic Authentication with your applicationId and secret
Purging Messages of a Channel Response
The platform will return a successful response that contains a "status" field. The HTTP status code is set according to the "status" field.
HTTP
1HTTP/1.1 200 OK
2Content-Type: application/json; charset=utf-8
3Content-Length: 32
4
5{"status":"ok","deletedCount":1}
cURL
1{
2"status":"ok",
3"deletedCount":1
4}
Purge Channel Messages API Status Codes
HTTP
Status
Retry
Description
200 OK
ok
never
Channel was successfully deleted.
400 Bad Request
varies
never
Indicates an issue with the request.
401 Unauthorized
unauthorized
never
The streaming platform was not able to authorize the provided credentials.
404 Not Found
not-found
never
The channel does not exist.
4XX
varies
never
Indicates an issue with the request.
503 Service Unavailable
capacity
once
The system is temporarily overloaded. Please try again later.
5XX
varies
once immediately, then exponential backoff
A transient server error.
Error Responses: Please be aware that some server errors 5XX and request validation errors 400 and 401 may result in an arbitrary response body not encoded in JSON.