• Skip to Search
  • Skip to Content
  • Skip to Side Navigation
Getting StartedSDK ReferenceGlossary
  • Home
  • Getting Started
  • SDK Reference
  • Portal
  • How-To
  • Troubleshooting
  • FAQs
  • Reference
  • Glossary
REST API
Web SDK
Android SDK
iOS SDK
Unity SDK
React Native SDK
EdgeAuth SDK
  • Overview
  • Channel
  • Room
  • Stream
  • RTMP
  • Transformation
  • Reporting
  • Analytics
  • Notification
  • Live and On-Demand

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:

HTTP
1PUT /pcast/channel HTTP/1.1
2Host: pcast.phenixrts.com
3Accept: application/json
4Authorization: Basic YXBwbGljYXRpb25JZDpzZWNyZXQ=
5Content-Type: application/json
6Content-Length: 172
7
8{
9 "channel": {
10 "alias": "<channelAlias>",
11 "name": "<channelName>",
12 "description": "<channelDescription>",
13 "options": [<channelOptions>]
14 }
15}
cURL
1$ curl https://pcast.phenixrts.com/pcast/channel \
2-u applicationId:secret \
3-H "Accept: application/json" \
4-H "Content-Type: application/json" \
5-X PUT \
6-d '{
7 "channel": {
8 "alias": "<channelAlias>",
9 "name": "<channelName>",
10 "description": "<channelDescription>",
11 "options": [<channelOptions>]
12 }
13 }'

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

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

Request Fields

FieldDescription
channel (required)Channel Object

Channel Object

FieldDescription
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.

HTTP
1HTTP/1.1 200 OK
2Content-Type: application/json; charset=utf-8
3Content-Length: 427
4
5{"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":[]}}
cURL
1{
2 "status" : "ok",
3 "channel" : {
4 "channelId" : "us-central#test#channel1",
5 "alias" : "morningNews",
6 "applicationId" : "test",
7 "name" : "Morning News",
8 "description" : "Morning News Channel - Chicago",
9 "type" : "Channel",
10 "streamKey" : "mRq5pZFuQf21lDgLsip1KhNgXC1CVvzJqftZBOW5vX1Kq06YtosMYyeIppPCC41h34bO1NFBbk4f6YLCHXvGYBvX6UoGYwxL",
11 "created" : "2018-02-05T18:21:28.280000000Z",
12 "lastUpdate" : "2018-02-05T18:21:28.280000000Z",
13 "estimatedSize": 0,
14 "options" : []
15 }
16}

Create Channel API Status Codes

HTTPStatusRetryDescription
200 OKokneverChannel has been successfully created.
400 Bad RequestvariesneverIndicates an issue with the request.
401 UnauthorizedunauthorizedneverThe streaming platform was not able to authorize the provided credentials.
409 Conflictalready-existsneverThe channel already exists.
4XXvariesneverIndicates an issue with the request.
503 Service UnavailablecapacityonceThe system is temporarily overloaded. Please try again later.
504 Gateway Timeoutrate-limitedonce immediately, then exponential backoffThe system is temporarily overloaded. Please try again later.
5XXvariesonce immediately, then exponential backoffA 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

FieldDescription
statusSee Status Codes
channelSee Channel fields

Channel fields

FieldDescription
channelIdUnique identifier for the channel.
aliasA user friendly unique identifier for the channel.
applicationIdApplication ID.
nameUnique name of the channel.
descriptionDescription of the channel.
typeType of the channel. This is always set to Channel.
streamKeyPush your RTMP feed to rtmp://ingest.phenixrts.com:80/ingest/ using this stream key. Stream Key must not be shared.
createdRFC 3339 compliant creation time of the channel.
lastUpdateRFC 3339 compliant last update time of the channel.
estimatedSizeNumber of members in the Channel. The size is eventual consistent with typical lag of a few seconds.
optionsOptions for the channel.

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:

HTTP
1GET /pcast/channel/<urlEncodedChannelId> HTTP/1.1
2Host: pcast.phenixrts.com
3Accept: application/json
4Authorization: Basic YXBwbGljYXRpb25JZDpzZWNyZXQ=
5Content-Type: application/json
cURL
1$ curl https://pcast.phenixrts.com/pcast/channel/<urlEncodedChannelId> \
2-H "Accept: application/json" \
3-H "Content-Type: application/json" \
4-u applicationId:secret \
5-X GET
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

ComponentDescription
urlEncodedChannelId (required)URL encoded ID of the channel

Request Headers

HeaderDescription
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
1HTTP/1.1 200 OK
2Content-Type: application/json; charset=utf-8
3Content-Length: 412
4
5{"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":[]}}
cURL
1{
2 "status" : "ok",
3 "channel" : {
4 "channelId" : "local#test#channel1",
5 "alias" : "channel1",
6 "applicationId" : "test",
7 "name" : "channel 1",
8 "description" : "a channel description",
9 "type" : "Channel",
10 "streamKey" : "F4CIbURu34oYH1OikqZsqaEkK1wgCJ2Lmn4xaJlXGA24ptLip4wKSWnfFeAjj9HDSEJ4b7EafGrEp1d9G3L1A9h0avUC7HPc",
11 "created" : "2018-02-05T22:20:25.304000000Z",
12 "lastUpdate" : "2018-02-05T22:20:25.304000000Z",
13 "estimatedSize": 13741,
14 "options" : []
15 }
16}

Fetching a Channel API Status Codes

HTTPStatusRetryDescription
200 OKokneverChannel was successfully returned.
400 Bad RequestvariesneverIndicates an issue with the request.
401 UnauthorizedunauthorizedneverThe streaming platform was not able to authorize the provided credentials.
404 Not Foundnot-foundneverThe channel does not exist.
4XXvariesneverIndicates an issue with the request.
503 Service UnavailablecapacityonceThe system is temporarily overloaded. Please try again later.
504 Gateway Timeoutrate-limitedonce immediately, then exponential backoffThe system is temporarily overloaded. Please try again later.
5XXvariesonce immediately, then exponential backoffA 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

FieldDescription
statusSee Status Codes
channelChannel 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:

HTTP
1GET /pcast/channel/<urlEncodedRoomId>/members HTTP/1.1
2Host: pcast.phenixrts.com
3Accept: application/json
4Content-Type: application/json
5Authorization: Basic YmlsbHk6c2VjcmV0cGFzc3dvcmQ=
cURL
1$ curl https://pcast.phenixrts.com/pcast/channel/<urlEncodedRoomId>/members \
2-u <applicationId>:<secret> \
3-H "Accept: application/json" \
4-H "Content-Type: application/json" \
5-X GET

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

ComponentDescription
urlEncodedRoomId (required)ID of the channel.

Request Headers

HeaderDescription
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
1HTTP/2 200 OK
2Content-Type: application/json; charset=utf-8
3Content-Length: 642
4
5{
6 "status": "ok",
7 "members": [
8 {
9 "sessionId": "us-southwest#DpMPWP3YQu8dmJCN9Vfn2v",
10 "screenName": "Primary-mrvwman-438728",
11 "role": "Presenter",
12 "streams": [
13 {
14 "type": "Presentation",
15 "uri": "pcast://phenixrts.com/us-southwest#us-west2-c.XfFVcxNg.20200205.PYIyIFS4?capabilities=multi-bitrate%2Cfhd",
16 "audioState": "TrackEnabled",
17 "videoState": "TrackEnabled"
18 }
19 ],
20 "state": "Passive",
21 "lastUpdate": 1580913727128
22 }
23 ]
24}
cURL
1{
2 "status": "ok",
3 "members": [
4 {
5 "sessionId": "us-southwest#DpMPWP3YQu8dmJCN9Vfn2v",
6 "screenName": "Primary-mrvwman-438728",
7 "role": "Presenter",
8 "streams": [
9 {
10 "type": "Presentation",
11 "uri": "pcast://phenixrts.com/us-southwest#us-west2-c.XfFVcxNg.20200205.PYIyIFS4?capabilities=multi-bitrate%2Cfhd",
12 "audioState": "TrackEnabled",
13 "videoState": "TrackEnabled"
14 }
15 ],
16 "state": "Passive",
17 "lastUpdate": 1580913727128
18 }
19 ]
20}

Fetch Channel Member API Status Codes

HTTPStatusRetryDescription
200 OKokneverChannel members were successfully listed.
400 Bad RequestvariesneverIndicates an issue with the request.
401 UnauthorizedunauthorizedneverThe streaming platform was not able to authorize the provided credentials.
404 Not Foundnot foundneverThe channel was not found.
4XXvariesneverIndicates an issue with the request.
503 Service UnavailablecapacityonceThe system is temporarily overloaded. Please try again later.
504 Gateway Timeoutrate-limitedonce immediately, then exponential backoffThe system is temporarily overloaded. Please try again later.
504 Gateway Timeouttime-exceededonce immediately, then exponential backoffThe request took to long to execute. Please try again later.
5XXvariesonce immediately, then exponential backoffA 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

FieldDescription
statusSee Status Codes.
membersArray of member objects. See Channel Member object.

Channel Member Object

FieldDescription
sessionIdThe session ID of the member.
screenNameThe screen name of the member.
roleThe role of the member. Valid values are: Participant, Moderator, Presenter, and Audience.
streamsArray of streams for the member. See Channel Stream object.
stateThe state of the member. Valid values are: Active, Passive, HandRaised, Inactive, Offline
lastUpdateUNIX timestamp of the last member update.

Channel Stream Object

FieldDescription
typeThe type of the stream. Valid values are: User, Presentation, Audio.
uriThe uri of the stream.
audioStateThe state of the audio track. Valid values are: TrackEnabled, TrackDisabled, TrackEnded.
videoStateThe 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:

HTTP
1GET /pcast/channels HTTP/1.1
2Host: pcast.phenixrts.com
3Accept: application/json
4Authorization: Basic YXBwbGljYXRpb25JZDpzZWNyZXQ=
5Content-Type: application/json
cURL
1$ curl https://pcast.phenixrts.com/pcast/channels \
2-H "Accept: application/json" \
3-H "Content-Type: application/json" \
4-u applicationId:secret \
5-X GET

Request Headers

HeaderDescription
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
1HTTP/1.1 200 OK
2Content-Type: application/json; charset=utf-8
3Content-Length: 830
4
5{"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":[]}]}
cURL
1{
2 "status": "ok",
3 "channels": [{
4 "channelId": "us-central#test#channel1",
5 "alias": "morningNews",
6 "applicationId": "test",
7 "name": "Morning News",
8 "description": "Morning News Channel - Chicago",
9 "type": "Channel",
10 "streamKey": "mRq5pZFuQf21lDgLsip1KhNgXC1CVvzJqftZBOW5vX1Kq06YtosMYyeIppPCC41h34bO1NFBbk4f6YLCHXvGYBvX6UoGYwxL",
11 "created": "2018-02-04T18:21:28.280000000Z",
12 "lastUpdate": "2018-02-04T18:21:28.280000000Z",
13 "estimatedSize": null,
14 "options": []
15 },{
16 "channelId": "us-central#test#channel2",
17 "alias": "EveningNews",
18 "applicationId": "test",
19 "name": "Evening News",
20 "description": "Evening News Channel - Chicago",
21 "type": "Channel",
22 "streamKey": "8oJgHdxCWht13CdBlmWev6BUm4D1hfiamsX0gpLNFaTCbJBN0Ty8jQiAa0mzmDuCA89AYYXjG8bp0pCFq3ehHFy1DJTbvGfr",
23 "created": "2018-02-05T18:21:28.280000000Z",
24 "lastUpdate": "2018-02-05T18:21:28.280000000Z",
25 "estimatedSize": null,
26 "options": []
27 }]
28}

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:

HTTP
1DELETE /pcast/channel/<urlEncodedChannelId> HTTP/1.1
2Host: pcast.phenixrts.com
3Accept: application/json
4Content-Type: application/json
5Content-Length: 0
cURL
1$ curl https://pcast.phenixrts.com/pcast/channel/<urlEncodedChannelId> \
2-H "Accept: application/json" \
3-H "Content-Type: application/json" \
4-u applicationId:secret \
5-X DELETE
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

ComponentDescription
urlEncodedChannelId (required)URL encoded ID of the channel

Request Headers

HeaderDescription
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

HTTPStatusRetryDescription
200 OKokneverChannel was successfully deleted.
400 Bad RequestvariesneverIndicates an issue with the request.
401 UnauthorizedunauthorizedneverThe streaming platform was not able to authorize the provided credentials.
4XXvariesneverIndicates an issue with the request.
503 Service UnavailablecapacityonceThe system is temporarily overloaded. Please try again later.
5XXvariesonce immediately, then exponential backoffA 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

FieldDescription
statusSee 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:

HTTP
1PUT /pcast/channel/<urlEncodedDestinationChannelId>/fork/<urlEncodedSourceChannelId> HTTP/1.1
2Host: pcast.phenixrts.com
3Accept: application/json
4Content-Type: application/json
5Content-Length: 86
6Authorization: Basic YmlsbHk6c2VjcmV0cGFzc3dvcmQ=
7
8{
9 "streamCapabilities": [],
10 "streamTags": ["my-channel-fork"],
11 "options": []
12}
cURL
1$ curl https://pcast.phenixrts.com/pcast/channel/<urlEncodedDestinationChannelId>/fork/<urlEncodedSourceChannelId> \
2-u <applicationId>:<secret> \
3-H "Accept: application/json" \
4-H "Content-Type: application/json" \
5-X PUT \
6-d '{
7 "streamCapabilities": [],
8 "streamTags": ["my-channel-fork"],
9 "options": []
10 }'

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

ComponentDescription
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

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

Request Fields

FieldDescription
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
1HTTP/2 200 OK
2Content-Type: application/json; charset=utf-8
3Content-Length: 623
4
5{
6 "status": "ok",
7 "members": [
8 {
9 "sessionId": "us-southwest#DpMPWP3YQu8dmJCN9Vfn2v",
10 "screenName": "Primary-mrvwman-438728",
11 "role": "Presenter",
12 "streams": [
13 {
14 "type": "Presentation",
15 "uri": "pcast://phenixrts.com/us-southwest#us-west2-c.XfFVcxNg.20200205.PYIyIFS4?capabilities=multi-bitrate%2Cfhd",
16 "audioState": "TrackEnabled",
17 "videoState": "TrackEnabled"
18 }
19 ],
20 "state": "Passive",
21 "lastUpdate": 1580913727128
22 }
23 ]
24}
cURL
1{
2 "status": "ok",
3 "members": [
4 {
5 "sessionId": "us-southwest#DpMPWP3YQu8dmJCN9Vfn2v",
6 "screenName": "Primary-mrvwman-438728",
7 "role": "Presenter",
8 "streams": [
9 {
10 "type": "Presentation",
11 "uri": "pcast://phenixrts.com/us-southwest#us-west2-c.XfFVcxNg.20200205.PYIyIFS4?capabilities=multi-bitrate%2Cfhd",
12 "audioState": "TrackEnabled",
13 "videoState": "TrackEnabled"
14 }
15 ],
16 "state": "Passive",
17 "lastUpdate": 1580913727128
18 }
19 ]
20}

Fork Channel API Status Codes

HTTPStatusRetryDescription
200 OKokneverChannel was successfully forked.
400 Bad RequestvariesneverIndicates an issue with the request. Eg: Options must be an array of strings.
401 UnauthorizedunauthorizedneverThe streaming platform was not able to authorize the provided credentials.
404 Not Foundnot foundneverOne or both of the source and destination channels are not found.
4XXvariesneverIndicates an issue with the request.
503 Service UnavailablecapacityonceThe system is temporarily overloaded. Please try again later.
504 Gateway Timeoutrate-limitedonce immediately, then exponential backoffThe system is temporarily overloaded. Please try again later.
504 Gateway Timeouttime-exceededonce immediately, then exponential backoffThe request took to long to execute. Please try again later.
5XXvariesonce immediately, then exponential backoffA 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

FieldDescription
statusSee Status Codes.
membersArray 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:

HTTP
1PUT /pcast/channel/<urlEncodedChannelId>/kill HTTP/1.1
2Host: pcast.phenixrts.com
3Accept: application/json
4Content-Type: application/json
5Content-Length: 47
6Authorization: Basic YmlsbHk6c2VjcmV0cGFzc3dvcmQ=
7
8{
9 "reason": "kill-reason",
10 "options": []
11}
cURL
1$ curl https://pcast.phenixrts.com/pcast/channel/<urlEncodedChannelId>/kill \
2-u <applicationId>:<secret> \
3-H "Accept: application/json" \
4-H "Content-Type: application/json" \
5-X PUT \
6-d '{
7 "reason": "kill-reason",
8 "options": []
9 }'

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

ComponentDescription
urlEncodedChannelId (required)ID of the channel to kill.

Request Headers

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

Request Fields

FieldDescription
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
1HTTP/2 200 OK
2Content-Type: application/json; charset=utf-8
3Content-Length: 629
4
5{
6 "status": "ok",
7 "killedMembers": [
8 {
9 "sessionId": "us-southwest#DpMPWP3YQu8dmJCN9Vfn2v",
10 "screenName": "Primary-mrvwman-438728",
11 "role": "Presenter",
12 "streams": [
13 {
14 "type": "Presentation",
15 "uri": "pcast://phenixrts.com/us-southwest#us-west2-c.XfFVcxNg.20200205.PYIyIFS4?capabilities=multi-bitrate%2Cfhd",
16 "audioState": "TrackEnabled",
17 "videoState": "TrackEnabled"
18 }
19 ],
20 "state": "Passive",
21 "lastUpdate": 1580913727128
22 }
23 ]
24}
cURL
1{
2 "status": "ok",
3 "killedMembers": [
4 {
5 "sessionId": "us-southwest#DpMPWP3YQu8dmJCN9Vfn2v",
6 "screenName": "Primary-mrvwman-438728",
7 "role": "Presenter",
8 "streams": [
9 {
10 "type": "Presentation",
11 "uri": "pcast://phenixrts.com/us-southwest#us-west2-c.XfFVcxNg.20200205.PYIyIFS4?capabilities=multi-bitrate%2Cfhd",
12 "audioState": "TrackEnabled",
13 "videoState": "TrackEnabled"
14 }
15 ],
16 "state": "Passive",
17 "lastUpdate": 1580913727128
18 }
19 ]
20}

Kill Channel API Status Codes

HTTPStatusRetryDescription
200 OKokneverChannel was successfully killed.
400 Bad RequestvariesneverIndicates an issue with the request. Eg: Options must be an array of strings.
401 UnauthorizedunauthorizedneverThe streaming platform was not able to authorize the provided credentials or Field "reason" must be a string.
404 Not Foundnot foundneverThe channel was not found.
4XXvariesneverIndicates an issue with the request.
503 Service UnavailablecapacityonceThe system is temporarily overloaded. Please try again later.
504 Gateway Timeoutrate-limitedonce immediately, then exponential backoffThe system is temporarily overloaded. Please try again later.
504 Gateway Timeouttime-exceededonce immediately, then exponential backoffThe request took to long to execute. Please try again later.
5XXvariesonce immediately, then exponential backoffA 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

FieldDescription
statusSee Status Codes.
killedMembersArray 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:

HTTP
1GET /pcast/channel/<urlEncodedChannelId>/publishers/count HTTP/1.1
2Host: pcast.phenixrts.com
3Accept: application/json
cURL
1$ curl https://pcast.phenixrts.com/pcast/channel/<urlEncodedChannelId>/publishers/count?failIfLess=<numberOfRequiredPublishers> \
2-H "Accept: application/json" \
3-X GET
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

ComponentDescription
urlEncodedChannelId (required)URL encoded ID of the channel

Request URI Parameters

ParameterDescription
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

HTTPstatusRetryDescription
200 OKokneverNumber of publishers was successfully reported.
400 Bad RequestvariesneverIndicates an issue with the request.
404 Not Foundnot-foundneverIndicates the channel was not found.
4XXvariesneverIndicates an issue with the request.
412 Precondition FailednoneneverThere is fewer than the required number of publishers.
503 Service UnavailablecapacityonceThe system is temporarily overloaded. Please try again later.
504 Gateway Timeoutrate-limitedonce immediately, then exponential backoffThe system is temporarily overloaded. Please try again later.
504 Gateway Timeouttime-exceededonce immediately, then exponential backoffThe request took to long to execute. Please try again later.
5XXvariesonce immediately, then exponential backoffA 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:

HTTP
1GET /pcast/channel/<urlEncodedChannelId>/live.m3u8 HTTP/1.1
2Host: pcast.phenixrts.com
3Accept: */*
cURL
1$ curl https://pcast.phenixrts.com/pcast/channel/<urlEncodedChannelId>/live.m3u8 \
2-H "Accept: */*" \
3-X GET
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

ComponentDescription
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

ParameterDescription
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
1HTTP/1.1 200 OK
2Content-Type: application/json; charset=utf-8
3Content-Length: 891
4
5#EXTM3U
6
7#EXT-X-STREAM-INF:PROGRAM-ID=1,CODECS="avc1.42c01f,mp4a.40.2",BANDWIDTH=1728000,AVERAGE-BANDWIDTH=1728000,FRAME-RATE=30
8live-720.m3u8
9#EXT-X-STREAM-INF:PROGRAM-ID=1,CODECS="avc1.42c01f,mp4a.40.2",BANDWIDTH=958000,AVERAGE-BANDWIDTH=958000,FRAME-RATE=30
10live-480.m3u8
11#EXT-X-STREAM-INF:PROGRAM-ID=1,CODECS="avc1.42c01f,mp4a.40.2",BANDWIDTH=584000,AVERAGE-BANDWIDTH=584000,FRAME-RATE=15
12live-360.m3u8
13#EXT-X-STREAM-INF:PROGRAM-ID=1,CODECS="avc1.42c01f,mp4a.40.2",BANDWIDTH=414000,AVERAGE-BANDWIDTH=414000,FRAME-RATE=15
14live-240.m3u8
15#EXT-X-STREAM-INF:PROGRAM-ID=1,CODECS="avc1.42c01e,mp4a.40.2",BANDWIDTH=144000,AVERAGE-BANDWIDTH=144000,FRAME-RATE=15
16live-144.m3u8
17#EXT-X-STREAM-INF:PROGRAM-ID=1,CODECS="mp4a.40.2",BANDWIDTH=128000,AVERAGE-BANDWIDTH=128000,FRAME-RATE=0
18live-ahi.m3u8
19#EXT-X-STREAM-INF:PROGRAM-ID=1,CODECS="mp4a.40.2",BANDWIDTH=64000,AVERAGE-BANDWIDTH=64000,FRAME-RATE=0
20live-alo.m3u8
cURL
1Found. Redirecting to /video/<applicationId>/<streamId>/live.m3u8

Manifest Channel API Status Codes

HTTPStatusRetryDescription
302 FoundokneverThe manifest was successfully located and a redirect URL is provided.
400 Bad RequestvariesneverIndicates an issue with the request.
404 Not Foundnot foundneverIndicates the channel or the manifest was not found.
415 Unsupported Media TypevariesneverThe channel does not support streaming.
4XXvariesneverIndicates an issue with the request.
503 Service UnavailablecapacityonceThe system is temporarily overloaded. Please try again later.
504 Gateway Timeoutrate-limitedonce immediately, then exponential backoffThe system is temporarily overloaded. Please try again later.
504 Gateway Timeouttime-exceededonce immediately, then exponential backoffThe request took to long to execute. Please try again later.
5XXvariesonce immediately, then exponential backoffA 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:

HTTP
1PUT /pcast/channel/<urlEncodedChannelId>/message HTTP/1.1
2Host: pcast.phenixrts.com
3Accept: application/json
4Authorization: Basic YXBwbGljYXRpb25JZDpzZWNyZXQ=
5Content-Type: application/json
6Content-Length: 303
7
8{
9 "message": {
10 "from": {
11 "screenName": "Screen Name",
12 "role": "Moderator",
13 "lastUpdate": 0
14 },
15 "mimeType": "text/plain",
16 "message": "My message",
17 "tags": ["my-tag", "my-other-tag"]
18 }
19}
cURL
1$ curl https://pcast.phenixrts.com/pcast/channel/<urlEncodedChannelId>/message \
2-u applicationId:secret \
3-H "Accept: application/json" \
4-H "Content-Type: application/json" \
5-X PUT \
6-d '{
7 "message": {
8 "from": {
9 "screenName": "Screen Name",
10 "role": "Moderator",
11 "lastUpdate": 0
12 },
13 "mimeType": "text/plain",
14 "message": "My message",
15 "tags": ["my-tag", "my-other-tag"]
16 }
17 }'
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

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

Request Fields

FieldDescription
message (required)Message Object

Message Object

FieldDescription
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

FieldDescription
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
1HTTP/1.1 200 OK
2Content-Type: application/json; charset=utf-8
3Content-Length: 310
4
5{"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"]}}
cURL
1{
2 "status": "ok",
3 "message": {
4 "messageId": "us-central#room|test#testing.xV1OVWEkOxZm|0000000009",
5 "timestamp": 1596088080439,
6 "deletedTimestamp": 0,
7 "from": {
8 "sessionId": "api",
9 "screenName": "Screen Name",
10 "role": "Moderator",
11 "lastUpdate": 0
12 },
13 "mimeType": "text/plain",
14 "message": "My message",
15 "tags": [
16 "my-tag",
17 "my-other-tag"
18 ]
19 }
20}

Send Channel Message API Status Codes

HTTPStatusRetryDescription
200 OKokneverMessage has been successfully sent.
400 Bad RequestvariesneverIndicates an issue with the request.
401 UnauthorizedunauthorizedneverThe streaming platform was not able to authorize the provided credentials.
404 Not Foundnot-foundneverThe channel does not exist.
413 Payload Too LargevariesneverOne 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.
4XXvariesneverIndicates an issue with the request.
503 Service UnavailablecapacityonceThe system is temporarily overloaded. Please try again later.
504 Gateway Timeoutrate-limitedonce immediately, then exponential backoffThe system is temporarily overloaded. Please try again later.
5XXvariesonce immediately, then exponential backoffA 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

FieldDescription
statusSee Status Codes
messageSee Message Object

Send Channel Message fields

FieldDescription
messageIdUnique identifier for the message.
timestampUNIX timestamp when the message was sent.
deletedTimestampUNIX timestamp when the message was deleted. 0 indicates that the message was not deleted.
fromUser Object
mimeTypeThe mime type of the content.
messageThe message.
tagsAn 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:

HTTP
1GET /pcast/channel/<urlEncodedChannelId>/messages?limit=100 HTTP/1.1
2Host: pcast.phenixrts.com
3Accept: application/json
4Authorization: Basic YXBwbGljYXRpb25JZDpzZWNyZXQ=
5Content-Type: application/json
cURL
1$ curl https://pcast.phenixrts.com/pcast/channel/<urlEncodedChannelId>/messages?limit=100 \
2-u applicationId:secret \
3-H "Accept: application/json" \
4-H "Content-Type: application/json" \
5-X GET
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

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

Request URI Parameters

ParameterDescription
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
1HTTP/1.1 200 OK
2Content-Type: application/json; charset=utf-8
3Content-Length: 395echo
4
5{"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}
cURL
1{
2 "status": "ok",
3 "messages": [
4 {
5 "messageId": "us-central#room|test#testing.xV1OVWEkOxZm|0000000243",
6 "timestamp": 1596089241062,
7 "deletedTimestamp": 0,
8 "from": {
9 "sessionId": "local#IrGTKf0ztwN3H5xORrtD9e",
10 "screenName": "ScreenName58611",
11 "role": "Participant",
12 "lastUpdate": 1596089235915
13 },
14 "mimeType": "text/plain",
15 "message": "Test message 240:1596089241045",
16 "tags": []
17 }
18 ],
19 "hasMoreBefore": false,
20 "hasMoreAfter": false
21}

Fetch Channel Messages API Status Codes

HTTPStatusRetryDescription
200 OKokneverMessages have been successfully fetched.
400 Bad RequestvariesneverIndicates an issue with the request.
401 UnauthorizedunauthorizedneverThe streaming platform was not able to authorize the provided credentials.
404 Not Foundnot-foundneverThe channel does not exist.
413 Payload Too Largelimit-too-largeneverToo many messages are requested. The maximal limit is 128 messages per request.
4XXvariesneverIndicates an issue with the request.
503 Service UnavailablecapacityonceThe system is temporarily overloaded. Please try again later.
504 Gateway Timeoutrate-limitedonce immediately, then exponential backoffThe system is temporarily overloaded. Please try again later.
5XXvariesonce immediately, then exponential backoffA 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

FieldDescription
statusSee Status Codes
messagesArray of Message Object
hasMoreBeforeA boolean flag indicating if there is potentially more messages before the returned range.
hasMoreAfterA 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:

HTTP
1DELETE /pcast/channel/<urlEncodedChannelId>/messages HTTP/1.1
2Host: pcast.phenixrts.com
3Accept: application/json
4Content-Type: application/json
5Content-Length: 0
cURL
1$ curl https://pcast.phenixrts.com/pcast/channel/<urlEncodedChannelId>/messages \
2-H "Accept: application/json" \
3-H "Content-Type: application/json" \
4-u applicationId:secret \
5-X DELETE
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

ComponentDescription
urlEncodedChannelId (required)URL encoded ID of the channel

Request Headers

HeaderDescription
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

HTTPStatusRetryDescription
200 OKokneverChannel was successfully deleted.
400 Bad RequestvariesneverIndicates an issue with the request.
401 UnauthorizedunauthorizedneverThe streaming platform was not able to authorize the provided credentials.
404 Not Foundnot-foundneverThe channel does not exist.
4XXvariesneverIndicates an issue with the request.
503 Service UnavailablecapacityonceThe system is temporarily overloaded. Please try again later.
5XXvariesonce immediately, then exponential backoffA 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

FieldDescription
statusSee Status Codes
deletedCountThe number of deleted messages.
Page Content
    Copyright 2023 © Phenix RTS
    Privacy Policy | Terms of Service
    v2023-01-31T21:25:10