Page Content
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.12Host: pcast.phenixrts.com3Accept: application/json4Authorization: Basic YXBwbGljYXRpb25JZDpzZWNyZXQ=5Content-Type: application/json6Content-Length: 17278{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
| 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.
HTTP
1HTTP/1.1 200 OK2Content-Type: application/json; charset=utf-83Content-Length: 42745{"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
| 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 eventual consistent with typical lag of a few seconds. |
| options | Options 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.12Host: pcast.phenixrts.com3Accept: application/json4Authorization: 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
| 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
1HTTP/1.1 200 OK2Content-Type: application/json; charset=utf-83Content-Length: 41245{"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
| 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:
HTTP
1GET /pcast/channel/<urlEncodedRoomId>/members HTTP/1.12Host: pcast.phenixrts.com3Accept: application/json4Content-Type: application/json5Authorization: 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
| 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
1HTTP/2 200 OK2Content-Type: application/json; charset=utf-83Content-Length: 64245{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": 158091372712822 }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": 158091372712818 }19 ]20}
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 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.
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:
HTTP
1GET /pcast/channels HTTP/1.12Host: pcast.phenixrts.com3Accept: application/json4Authorization: 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
| 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
1HTTP/1.1 200 OK2Content-Type: application/json; charset=utf-83Content-Length: 83045{"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.12Host: pcast.phenixrts.com3Accept: application/json4Content-Type: application/json5Content-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
| 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 OK2Content-Type: application/json; charset=utf-83Content-Length: 1545{"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.
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:
HTTP
1PUT /pcast/channel/<urlEncodedDestinationChannelId>/fork/<urlEncodedSourceChannelId> HTTP/1.12Host: pcast.phenixrts.com3Accept: application/json4Content-Type: application/json5Content-Length: 866Authorization: Basic YmlsbHk6c2VjcmV0cGFzc3dvcmQ=78{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
| 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
1HTTP/2 200 OK2Content-Type: application/json; charset=utf-83Content-Length: 62345{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": 158091372712822 }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": 158091372712818 }19 ]20}
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:
HTTP
1PUT /pcast/channel/<urlEncodedChannelId>/kill HTTP/1.12Host: pcast.phenixrts.com3Accept: application/json4Content-Type: application/json5Content-Length: 476Authorization: Basic YmlsbHk6c2VjcmV0cGFzc3dvcmQ=78{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
| 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
1HTTP/2 200 OK2Content-Type: application/json; charset=utf-83Content-Length: 62945{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": 158091372712822 }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": 158091372712818 }19 ]20}
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:
HTTP
1GET /pcast/channel/<urlEncodedChannelId>/publishers/count HTTP/1.12Host: pcast.phenixrts.com3Accept: 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
| 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 OK2Content-Type: application/json; charset=utf-83Content-Length: 1451
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:
HTTP
1GET /pcast/channel/<urlEncodedChannelId>/live.m3u8 HTTP/1.12Host: pcast.phenixrts.com3Accept: */*
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
| 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
1HTTP/1.1 200 OK2Content-Type: application/json; charset=utf-83Content-Length: 89145#EXTM3U67#EXT-X-STREAM-INF:PROGRAM-ID=1,CODECS="avc1.42c01f,mp4a.40.2",BANDWIDTH=1728000,AVERAGE-BANDWIDTH=1728000,FRAME-RATE=308live-720.m3u89#EXT-X-STREAM-INF:PROGRAM-ID=1,CODECS="avc1.42c01f,mp4a.40.2",BANDWIDTH=958000,AVERAGE-BANDWIDTH=958000,FRAME-RATE=3010live-480.m3u811#EXT-X-STREAM-INF:PROGRAM-ID=1,CODECS="avc1.42c01f,mp4a.40.2",BANDWIDTH=584000,AVERAGE-BANDWIDTH=584000,FRAME-RATE=1512live-360.m3u813#EXT-X-STREAM-INF:PROGRAM-ID=1,CODECS="avc1.42c01f,mp4a.40.2",BANDWIDTH=414000,AVERAGE-BANDWIDTH=414000,FRAME-RATE=1514live-240.m3u815#EXT-X-STREAM-INF:PROGRAM-ID=1,CODECS="avc1.42c01e,mp4a.40.2",BANDWIDTH=144000,AVERAGE-BANDWIDTH=144000,FRAME-RATE=1516live-144.m3u817#EXT-X-STREAM-INF:PROGRAM-ID=1,CODECS="mp4a.40.2",BANDWIDTH=128000,AVERAGE-BANDWIDTH=128000,FRAME-RATE=018live-ahi.m3u819#EXT-X-STREAM-INF:PROGRAM-ID=1,CODECS="mp4a.40.2",BANDWIDTH=64000,AVERAGE-BANDWIDTH=64000,FRAME-RATE=020live-alo.m3u8
cURL
1Found. Redirecting to /video/<applicationId>/<streamId>/live.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:
HTTP
1PUT /pcast/channel/<urlEncodedChannelId>/message HTTP/1.12Host: pcast.phenixrts.com3Accept: application/json4Authorization: Basic YXBwbGljYXRpb25JZDpzZWNyZXQ=5Content-Type: application/json6Content-Length: 30378{9 "message": {10 "from": {11 "screenName": "Screen Name",12 "role": "Moderator",13 "lastUpdate": 014 },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": 012 },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
| 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
1HTTP/1.1 200 OK2Content-Type: application/json; charset=utf-83Content-Length: 31045{"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": 012 },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
| 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:
HTTP
1GET /pcast/channel/<urlEncodedChannelId>/messages?limit=100 HTTP/1.12Host: pcast.phenixrts.com3Accept: application/json4Authorization: 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
| 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
1HTTP/1.1 200 OK2Content-Type: application/json; charset=utf-83Content-Length: 395echo45{"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": 159608923591513 },14 "mimeType": "text/plain",15 "message": "Test message 240:1596089241045",16 "tags": []17 }18 ],19 "hasMoreBefore": false,20 "hasMoreAfter": false21}
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:
HTTP
1DELETE /pcast/channel/<urlEncodedChannelId>/messages HTTP/1.12Host: pcast.phenixrts.com3Accept: application/json4Content-Type: application/json5Content-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
| 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 OK2Content-Type: application/json; charset=utf-83Content-Length: 3245{"status":"ok","deletedCount":1}
cURL
1{2 "status": "ok",3 "deletedCount": 14}
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. |
v2023-01-31T21:25:10