Channel API

APIs for channels let you Create, List, Fetch and Delete Channels.

Creating a Channel

This API allows to create a channel.

Creating a Channel Request

Send a PUT request to the /pcast/channel endpoint as shown:

PUT /pcast/channel HTTP/1.1
Host: pcast.phenixrts.com
Accept: application/json
Authorization: Basic YXBwbGljYXRpb25JZDpzZWNyZXQ=
Content-Type: application/json
Content-Length: 172
 
{
    "channel": {
        "alias": "<channelAlias>",
        "name": "<channelName>",
        "description": "<channelDescription>",
        "options": [<channelOptions>]
    }
}

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.
ingestOptions (optional)	An object that defines default values for ingest parameters.

Channel Object Ingest Options

ingestOptions Usage

The capabilities defined by ingestOptions are only applied when publishing via RTMP. When publishing to the Channel using any method other than RTMP (e.g., SRT or the Phenix Web SDK), the capabilities and tags set using this method are not applied.

Field	Description
capabilities (optional)	An array of capabilities.
tags (optional)	An array of tags applied to the published stream.
screenName (optional)	The screen name of the channel member representing this ingest. The screen name is automatically chosen to properly enable functionality such as HA publishing.
maxFps (optional)	[Advanced] Controls the maximal frame rate sampled from the source signal when using `source-uri-ingest`. Support of signals with more than 30 FPS is experimental.
buffer (optional)	[Advanced] The amount of buffer to use on the ingest side to compensate for network jitter when using `source-uri-ingest`.
prerollSkipDuration (optional)	[Experimental] Milliseconds to skip at the beginning of the stream when using `source-uri-ingest`.
jitterBuffer (optional)	[Experimental] The amount of jitter buffer to use after decoding and sampling of the ingest signal. This value should generally equal to or larger than the value of `buffer`.

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.

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 427
 
{"status":"ok","channel":{"channelId":"us-central#test#channe1","alias":"morningNews","applicationId":"test","name":"Morning News","description":"Morning News Channel - Chicago","type":"Channel","streamKey":"mRq5pZFuQf21lDgLsip1KhNgXC1CVvzJqftZBOW5vX1Kq06YtosMYyeIppPCC41h34bO1NFBbk4f6YLCHXvGYBvX6UoGYwxL","created":"2018-02-05T18:21:28.280000000Z","lastUpdate":"2018-02-05T18:21:28.280000000Z","estimatedSize":0,"options":[]}}

Create Channel API Status Codes

HTTP	Status	Retry	Description
200 OK	ok	never	Channel has been successfully created.
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.
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.

Create Channel API Response fields

Field	Description
status	See Status Codes
channel	See Channel fields

Channel fields

Field	Description
channelId	Unique identifier for the channel.
alias	A user friendly unique identifier for the channel.
applicationId	Application ID.
name	Unique name of the channel.
description	Description of the channel.
type	Type of the channel. This is always set to Channel.
streamKey	Push your RTMP feed to `rtmp://ingest.phenixrts.com:80/ingest/` using this stream key. Stream Key must not be shared.
created	RFC 3339 compliant creation time of the channel.
lastUpdate	RFC 3339 compliant last update time of the channel.
estimatedSize	Number of members in the Channel. The size is eventually consistent with typical lag of a few seconds.
options	Options for the channel.
ingestOptions	Ingest options object (when configured).

Ingest Options

Field	Description
capabilities	An array of capabilities.
tags	An array of tags applied to the published stream.
screenName	The screen name of the channel member representing this ingest. The screen name is automatically chosen to properly enable functionality like HA publishing.
maxFps	[Advanced] Controls the maximal frame rate sampled from the source signal when using `source-uri-ingest`. Support of signals with more than 30 FPS is experimental.
buffer	[Advanced] The amount of buffer to use on the ingest side to compensate for network jitter when using `source-uri-ingest`.
prerollSkipDuration	[Experimental] Milliseconds to skip at the beginning of the stream when using `source-uri-ingest`.
jitterBuffer	[Experimental] The amount of jitter buffer to use after decoding and sampling of the ingest signal. This value should generally equal or larger than `buffer`.

Fetching a Channel

This API allows to fetch a channel.

Fetching a Channel Request

Send a GET request to the /pcast/channel/<urlEncodedChannelId> endpoint as shown:

GET /pcast/channel/<urlEncodedChannelId> HTTP/1.1
Host: pcast.phenixrts.com
Accept: application/json
Authorization: Basic YXBwbGljYXRpb25JZDpzZWNyZXQ=
Content-Type: application/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.

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 412
 
{"status":"ok","channel":{"channelId":"local#test#channel1","alias":"channel1","applicationId":"test","name":"channel 1","description":"a channel description","type":"Channel","streamKey":"F4CIbURu34oYH1OikqZsqaEkK1wgCJ2Lmn4xaJlXGA24ptLip4wKSWnfFeAjj9HDSEJ4b7EafGrEp1d9G3L1A9h0avUC7HPc","created":"2018-02-05T22:20:25.304000000Z","lastUpdate":"2018-02-05T22:20:25.304000000Z","estimatedSize":13741,"options":[],"ingestOptions":{"capabilities":["multi-bitrate","aspect-ratio=9x16"],"tags":["realTime"]}}}

Fetching a Channel API Status Codes

HTTP	Status	Retry	Description
200 OK	ok	never	Channel was successfully returned.
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.
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.

Fetching a Channel API Response fields

Field	Description
status	See Status Codes
channel	Channel objects. See Channel fields.

Fetching Members of a Channel

This API allows the caller to retrieve all the publishers of a specified channel.

Fetching Members of a Channel Request

Send a GET request to the /pcast/channel/<urlEncodedRoomId>/members endpoint as shown:

GET /pcast/channel/<urlEncodedRoomId>/members HTTP/1.1
Host: pcast.phenixrts.com
Accept: application/json
Content-Type: application/json
Authorization: Basic YmlsbHk6c2VjcmV0cGFzc3dvcmQ=

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:

HTTP/2 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 642
 
{
    "status": "ok",
    "members": [
        {
            "sessionId": "us-southwest#DpMPWP3YQu8dmJCN9Vfn2v",
            "screenName": "Primary-mrvwman-438728",
            "role": "Presenter",
            "streams": [
                {
                    "type": "Presentation",
                    "uri": "pcast://phenixrts.com/us-southwest#us-west2-c.XfFVcxNg.20200205.PYIyIFS4?capabilities=multi-bitrate%2Cfhd",
                    "audioState": "TrackEnabled",
                    "videoState": "TrackEnabled"
                }
            ],
            "state": "Passive",
            "lastUpdate": 1580913727128
        }
    ]
}

Fetch Channel Member API Status Codes

HTTP	Status	Retry	Description
200 OK	ok	never	Channel members were successfully listed.
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 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 too 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.

Fetch Channel Member API Response fields

Field	Description
status	See Status Codes.
members	Array of member objects. See Channel Member object.

Channel Member Object

Field	Description
sessionId	The session ID of the member.
screenName	The screen name of the member.
role	The role of the member. Valid values are: Participant, Moderator, Presenter, and Audience.
streams	Array of streams for the member. See Channel Stream object.
state	The state of the member. Valid values are: Active, Passive, HandRaised, Inactive, Offline
lastUpdate	UNIX timestamp of the last member update.

Channel Stream Object

Field	Description
type	The type of the stream. Valid values are: User, Presentation, Audio.
uri	The uri of the stream.
audioState	The state of the audio track. Valid values are: TrackEnabled, TrackDisabled, TrackEnded.
videoState	The state of the video track. Valid values are: TrackEnabled, TrackDisabled, TrackEnded.

Listing Channels

This API allows to list existing channels.

Listing Channels Request

Send a GET request to the /pcast/channels endpoint as shown:

GET /pcast/channels HTTP/1.1
Host: pcast.phenixrts.com
Accept: application/json
Authorization: Basic YXBwbGljYXRpb25JZDpzZWNyZXQ=
Content-Type: application/json

Request Headers

Header	Description
Authorization (required)	Use HTTP Basic Authentication with your applicationId and secret

Listing Channels 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/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 830
 
{"status":"ok","channels":[{"channelId":"us-central#test#channel1","alias":"morningNews","applicationId":"test","name":"MorningNews","description":"MorningNewsChannel-Chicago","type":"Channel","streamKey":"mRq5pZFuQf21lDgLsip1KhNgXC1CVvzJqftZBOW5vX1Kq06YtosMYyeIppPCC41h34bO1NFBbk4f6YLCHXvGYBvX6UoGYwxL","created":"2018-02-04T18:21:28.280000000Z","lastUpdate":"2018-02-04T18:21:28.280000000Z","estimatedSize":null,"options":[]},{"channelId":"us-central#test#channel2","alias":"EveningNews","applicationId":"test","name":"EveningNews","description":"EveningNewsChannel-Chicago","type":"Channel","streamKey":"8oJgHdxCWht13CdBlmWev6BUm4D1hfiamsX0gpLNFaTCbJBN0Ty8jQiAa0mzmDuCA89AYYXjG8bp0pCFq3ehHFy1DJTbvGfr","created":"2018-02-05T18:21:28.280000000Z","lastUpdate":"2018-02-05T18:21:28.280000000Z","estimatedSize":null,"options":[]}]}

Deleting a Channel

This API allows to delete channels.

Deleting a Channel Request

Send a DELETE request to the /pcast/channel/<urlEncodedChannelId> endpoint as shown:

DELETE /pcast/channel/<urlEncodedChannelId> HTTP/1.1
Host: pcast.phenixrts.com
Accept: application/json
Content-Type: application/json
Content-Length: 0

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/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 15
 
{"status":"ok"}

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.

Delete Channel API Response fields

Field	Description
status	See Status Codes

Fork a Channel

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:

PUT /pcast/channel/<urlEncodedDestinationChannelId>/fork/<urlEncodedSourceChannelId> HTTP/1.1
Host: pcast.phenixrts.com
Accept: application/json
Content-Type: application/json
Content-Length: 86
Authorization: Basic YmlsbHk6c2VjcmV0cGFzc3dvcmQ=
 
{
    "streamCapabilities": [],
    "streamTags": ["my-channel-fork"],
    "options": []
}

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:

HTTP/2 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 623
 
{
    "status": "ok",
    "members": [
        {
            "sessionId": "us-southwest#DpMPWP3YQu8dmJCN9Vfn2v",
            "screenName": "Primary-mrvwman-438728",
            "role": "Presenter",
            "streams": [
                {
                    "type": "Presentation",
                    "uri": "pcast://phenixrts.com/us-southwest#us-west2-c.XfFVcxNg.20200205.PYIyIFS4?capabilities=multi-bitrate%2Cfhd",
                    "audioState": "TrackEnabled",
                    "videoState": "TrackEnabled"
                }
            ],
            "state": "Passive",
            "lastUpdate": 1580913727128
        }
    ]
}

Fork Channel API Status Codes

HTTP	Status	Retry	Description
200 OK	ok	never	Channel was successfully forked.
400 Bad Request	varies	never	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.

Fork Channel API Response fields

Field	Description
status	See Status Codes.
members	Array of session objects that have been forked.

Kill a Channel

This API allows the caller to remove all the publishers and terminate the corresponding streams within the specified channel.

Kill a Channel Request

Send a PUT request to the /pcast/channel/<urlEncodedChannelId>/kill endpoint as shown:

PUT /pcast/channel/<urlEncodedChannelId>/kill HTTP/1.1
Host: pcast.phenixrts.com
Accept: application/json
Content-Type: application/json
Content-Length: 47
Authorization: Basic YmlsbHk6c2VjcmV0cGFzc3dvcmQ=
 
{
    "reason": "kill-reason",
    "options": []
}

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:

HTTP/2 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 629
 
{
    "status": "ok",
    "killedMembers": [
        {
            "sessionId": "us-southwest#DpMPWP3YQu8dmJCN9Vfn2v",
            "screenName": "Primary-mrvwman-438728",
            "role": "Presenter",
            "streams": [
                {
                    "type": "Presentation",
                    "uri": "pcast://phenixrts.com/us-southwest#us-west2-c.XfFVcxNg.20200205.PYIyIFS4?capabilities=multi-bitrate%2Cfhd",
                    "audioState": "TrackEnabled",
                    "videoState": "TrackEnabled"
                }
            ],
            "state": "Passive",
            "lastUpdate": 1580913727128
        }
    ]
}

Kill Channel API Status Codes

HTTP	Status	Retry	Description
200 OK	ok	never	Channel was successfully killed.
400 Bad Request	varies	never	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.

Kill Channel API Response fields

Field	Description
status	See Status Codes.
killedMembers	Array of session objects that have been killed.

Checking the State of a Channel

This API allows to check the number of publishers in a channel. This can be used to verify the health of ingests, e.g. redundant RTMP ingests.

Checking the State of a Channel Request

Send a GET request to the /pcast/channel/<urlEncodedChannelId>/publishers/count endpoint as shown:

GET /pcast/channel/<urlEncodedChannelId>/publishers/count HTTP/1.1
Host: pcast.phenixrts.com
Accept: application/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/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 1
 
1

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:

GET /pcast/channel/<urlEncodedChannelId>/live.m3u8 HTTP/1.1
Host: pcast.phenixrts.com
Accept: */*

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.

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 891
 
#EXTM3U
 
#EXT-X-STREAM-INF:PROGRAM-ID=1,CODECS="avc1.42c01f,mp4a.40.2",BANDWIDTH=1728000,AVERAGE-BANDWIDTH=1728000,FRAME-RATE=30
live-720.m3u8
#EXT-X-STREAM-INF:PROGRAM-ID=1,CODECS="avc1.42c01f,mp4a.40.2",BANDWIDTH=958000,AVERAGE-BANDWIDTH=958000,FRAME-RATE=30
live-480.m3u8
#EXT-X-STREAM-INF:PROGRAM-ID=1,CODECS="avc1.42c01f,mp4a.40.2",BANDWIDTH=584000,AVERAGE-BANDWIDTH=584000,FRAME-RATE=15
live-360.m3u8
#EXT-X-STREAM-INF:PROGRAM-ID=1,CODECS="avc1.42c01f,mp4a.40.2",BANDWIDTH=414000,AVERAGE-BANDWIDTH=414000,FRAME-RATE=15
live-240.m3u8
#EXT-X-STREAM-INF:PROGRAM-ID=1,CODECS="avc1.42c01e,mp4a.40.2",BANDWIDTH=144000,AVERAGE-BANDWIDTH=144000,FRAME-RATE=15
live-144.m3u8
#EXT-X-STREAM-INF:PROGRAM-ID=1,CODECS="mp4a.40.2",BANDWIDTH=128000,AVERAGE-BANDWIDTH=128000,FRAME-RATE=0
live-ahi.m3u8
#EXT-X-STREAM-INF:PROGRAM-ID=1,CODECS="mp4a.40.2",BANDWIDTH=64000,AVERAGE-BANDWIDTH=64000,FRAME-RATE=0
live-alo.m3u8

Manifest Channel API Status Codes

HTTP	Status	Retry	Description
302 Found	ok	never	The manifest was successfully located and a redirect URL is provided.
400 Bad Request	varies	never	Indicates an issue with the request.
404 Not Found	not found	never	Indicates the channel or the manifest was not found.
415 Unsupported Media Type	varies	never	The channel does not support `streaming`.
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.

Manifest Channel API Response fields

The response is redirecting to the manifest file via a standard HTTP redirect response (302).

Sending a Message

This API allows to send a message.

Sending a Message Request

Send a PUT request to the /pcast/channel/<urlEncodedChannelId>/message endpoint as shown:

PUT /pcast/channel/<urlEncodedChannelId>/message HTTP/1.1
Host: pcast.phenixrts.com
Accept: application/json
Authorization: Basic YXBwbGljYXRpb25JZDpzZWNyZXQ=
Content-Type: application/json
Content-Length: 303
 
{
    "message": {
        "from": {
            "screenName": "Screen Name",
            "role": "Moderator",
            "lastUpdate": 0
        },
        "mimeType": "text/plain",
        "message": "My message",
        "tags": ["my-tag", "my-other-tag"]
    }
}

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

Request Fields

Field	Description
message (required)	Message Object

Message Object

Field	Description
from (required)	User Object representing the sender of the message.
mimeType (required)	The mime type of the content.
message (required)	The message. Binary messages should be base64 encoded.
tags (required)	An array of tags for the message.

User Object

Field	Description
sessionId (optional)	The session ID of the user.
screenName (required)	The screen name of the user.
role (required)	The role of the user. Valid values are: Participant, Moderator, Presenter, and Audience.
lastUpdate (required)	The last update of the user as a UNIX timestamp.

Sending a Message 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/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 310
 
{"status":"ok","message":{"messageId":"us-central#room|test#testing.xV1OVWEkOxZm|0000000009","timestamp":1596088080439,"deletedTimestamp":0,"from":{"sessionId":"api","screenName":"Screen Name","role":"Moderator","lastUpdate":0},"mimeType":"text/plain","message":"My message","tags":["my-tag","my-other-tag"]}}

Send Channel Message API Status Codes

HTTP	Status	Retry	Description
200 OK	ok	never	Message has been successfully sent.
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.
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.

Send Channel Message API Response fields

Field	Description
status	See Status Codes
message	See Message Object

Send Channel Message fields

Field	Description
messageId	Unique identifier for the message.
timestamp	UNIX timestamp when the message was sent.
deletedTimestamp	UNIX timestamp when the message was deleted. 0 indicates that the message was not deleted.
from	User Object
mimeType	The mime type of the content.
message	The message.
tags	An array of tags for the message.

Fetching Messages

This API allows to fetch messages.

Fetching Messages Request

Send a GET request to the /pcast/channel/<urlEncodedChannelId>/messages endpoint as shown:

GET /pcast/channel/<urlEncodedChannelId>/messages?limit=100 HTTP/1.1
Host: pcast.phenixrts.com
Accept: application/json
Authorization: Basic YXBwbGljYXRpb25JZDpzZWNyZXQ=
Content-Type: application/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.

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 395echo
 
{"status":"ok","messages":[{"messageId":"us-central#room|test#testing.xV1OVWEkOxZm|0000000243","timestamp":1596089241062,"deletedTimestamp":0,"from":{"sessionId":"local#IrGTKf0ztwN3H5xORrtD9e","screenName":"ScreenName58611","role":"Participant","lastUpdate":1596089235915},"mimeType":"text/plain","message":"Test message 240:1596089241045","tags":[]}],"hasMoreBefore":false,"hasMoreAfter":false}

Fetch Channel Messages API Status Codes

HTTP	Status	Retry	Description
200 OK	ok	never	Messages have been successfully fetched.
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.
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.

Fetch Channel Messages API Response fields

Field	Description
status	See Status Codes
messages	Array of Message Object
hasMoreBefore	A boolean flag indicating if there is potentially more messages before the returned range.
hasMoreAfter	A boolean flag indicating if there is potentially more messages after the returned range.

Purging Messages of a Channel

This API allows to purge all messages of a channel. By default, channel messages are retained for 90 days.

Purging Messages of a Channel Request

Send a DELETE request to the /pcast/channel/<urlEncodedChannelId>/messages endpoint as shown:

DELETE /pcast/channel/<urlEncodedChannelId>/messages HTTP/1.1
Host: pcast.phenixrts.com
Accept: application/json
Content-Type: application/json
Content-Length: 0

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/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 32
 
{"status":"ok","deletedCount":1}

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.

Purge Channel Messages API Response fields

Field	Description
status	See Status Codes
deletedCount	The number of deleted messages.

Page Content

v2024-11-19T17:31:40.000Z

Channel API

Creating a Channel#Copied URL

Creating a Channel Request#Copied URL

Request Headers

Request Fields

Channel Object

Channel Object Ingest Options

ingestOptions Usage

Creating a Channel Response#Copied URL

Create Channel API Status Codes

Error Responses

Create Channel API Response fields

Channel fields

Ingest Options

Fetching a Channel#Copied URL

Fetching a Channel Request#Copied URL

Encoding

Request URI

Request Headers

Fetching a Channel Response#Copied URL

Fetching a Channel API Status Codes

Error Responses

Fetching a Channel API Response fields

Fetching Members of a Channel#Copied URL

Fetching Members of a Channel Request#Copied URL

Encoding

Request URI

Request Headers

Fetching Members of a Channel Response#Copied URL

Fetch Channel Member API Status Codes

Error Responses

Fetch Channel Member API Response fields

Channel Member Object

Channel Stream Object

Listing Channels#Copied URL

Listing Channels Request#Copied URL

Request Headers

Listing Channels Response#Copied URL

Deleting a Channel#Copied URL

Deleting a Channel Request#Copied URL

Encoding

Request URI

Request Headers

Deleting a Channel Response#Copied URL

Delete Channel API Status Codes

Error Responses

Delete Channel API Response fields

Fork a Channel#Copied URL

Fork a Channel Request#Copied URL

Encoding

Request URI

Request Headers

Request Fields

Fork a Channel Response#Copied URL

Fork Channel API Status Codes

Error Responses

Fork Channel API Response fields

Kill a Channel#Copied URL

Kill a Channel Request#Copied URL

Encoding

Request URI

Request Headers

Request Fields

Kill a Channel Response#Copied URL

Kill Channel API Status Codes

Error Responses

Kill Channel API Response fields

Checking the State of a Channel#Copied URL

Checking the State of a Channel Request#Copied URL

Encoding

Request URI

Request URI Parameters

Checking the State of a Channel Response#Copied URL

Health Channel API Status Codes

Error Responses

Channel API Response fields

Universal Live Manifest for a Channel#Copied URL

Universal Live Manifest for a Channel Request#Copied URL

Encoding

Request URI

Creating a Channel

Creating a Channel Request

Creating a Channel Response

Fetching a Channel

Fetching a Channel Request

Fetching a Channel Response

Fetching Members of a Channel

Fetching Members of a Channel Request

Fetching Members of a Channel Response

Listing Channels

Listing Channels Request

Listing Channels Response

Deleting a Channel

Deleting a Channel Request

Deleting a Channel Response

Fork a Channel

Fork a Channel Request

Fork a Channel Response

Kill a Channel

Kill a Channel Request

Kill a Channel Response

Checking the State of a Channel

Checking the State of a Channel Request

Checking the State of a Channel Response

Universal Live Manifest for a Channel

Universal Live Manifest for a Channel Request

Universal Live Manifest for a Channel Response

Sending a Message

Sending a Message Request

Sending a Message Response

Fetching Messages

Fetching Messages Request

Fetching Messages Response

Purging Messages of a Channel

Purging Messages of a Channel Request

Purging Messages of a Channel Response