• 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

Room API

APIs for Rooms let you Create, List, Fetch and Delete Rooms.

Creating a Room

This API allows to create a room.

Creating a Room Request

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

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

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
room (required)Room Object

Room Object

FieldDescription
alias (required)A user friendly unique identifier for the room. An empty string is required if you want the Streaming platform to generate an alias for your room.
description (required)A description for the room.
name (required)Unique name of the room.
options (required)An array of options for the room. An empty array is required if there are no options.
type (optional)Type of the room. Defaults to MultiPartyChat. Valid values include: DirectChat, MultiPartyChat, ModeratedChat and TownHall.

Creating a Room 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","room":{"roomId":"us-central#test#channe1","alias":"morningNews","applicationId":"test","name":"Morning News","description":"Morning News Room - Chicago","type":"MultiPartyChat","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 "room" : {
4 "roomId" : "us-central#test#room1",
5 "alias" : "morningNews",
6 "applicationId" : "test",
7 "name" : "Morning News",
8 "description" : "Morning News Room - Chicago",
9 "type" : "MultiPartyChat",
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 Room API Status Codes

HTTPStatusRetryDescription
200 OKokneverRoom 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 room 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 Room API Response fields

FieldDescription
statusSee Status Codes
roomSee Room fields

Room fields

FieldDescription
aliasA user friendly unique identifier for the room.
applicationIdApplication ID.
createdRFC 3339 compliant creation time of the room.
descriptionDescription of the room.
estimatedSizeNumber of members in the Room. The size is eventual consistent with typical lag of a few seconds.
lastUpdateRFC 3339 compliant last update time of the room.
nameUnique name of the room.
optionsOptions for the room.
roomIdUnique identifier for the room.
streamKeyPush your RTMP feed to rtmp://ingest.phenixrts.com:80/ingest/ using this stream key. Stream Key must not be shared.
typeType of the room. Valid values include: DirectChat, MultiPartyChat, ModeratedChat and TownHall

Fetching a Room

This API allows to fetch a room.

Fetching a Room Request

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

HTTP
1GET /pcast/room/<urlEncodedRoomId> 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/room/<urlEncodedRoomId> \
2-H "Accept: application/json" \
3-H "Content-Type: application/json" \
4-u applicationId:secret \
5-X GET
Encoding: Room ID may contain characters that are unsafe for URLs. Be sure to encode the RoomId in the URL path. For example, the URL encoding of `us-central#us-central` is `us-central%23us-central`

Request URI

ComponentDescription
urlEncodedRoomId (required)URL encoded ID of the room

Request Headers

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

Fetching a Room 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","room":{"roomId":"local#test#room1","alias":"room1","applicationId":"test","name":"room 1","description":"a room description","type":"MultiPartyChat","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 "room" : {
4 "roomId" : "local#test#room1",
5 "alias" : "room1",
6 "applicationId" : "test",
7 "name" : "room 1",
8 "description" : "a room description",
9 "type" : "MultiPartyChat",
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 Room API Status Codes

HTTPStatusRetryDescription
200 OKokneverRoom 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 room 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.
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 Room API Response fields

FieldDescription
statusSee Status Codes
roomRoom objects. See Room fields.

Fetching members of a room

This API allows the caller to retrieve all the members of a specified room.

Fetching members of a room Request

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

HTTP
1GET /pcast/room/<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/room/<urlEncodedRoomId>/members \
2-u <applicationId>:<secret> \
3-H "Accept: application/json" \
4-H "Content-Type: application/json" \
5-X GET

Encoding: Room ID may contain characters that are unsafe for URLs. Be sure to encode the RoomId 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 room.

Request Headers

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

Fetching members of a room 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 Room Member API Status Codes

HTTPStatusRetryDescription
200 OKokneverRoom 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 room 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 Room Member API Response fields

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

Room 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 Room Stream object.
stateThe state of the member. Valid values are: Active, Passive, HandRaised, Inactive, Offline
lastUpdateUNIX timestamp of the last member update.

Room 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 Rooms

This API allows to list existing rooms.

Listing Rooms Request

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

HTTP
1GET /pcast/rooms 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/rooms \
2-H "Accept: application/json" \
3-H "Content-Type: application/json" \
4-u applicationId:secret \
5-X GET

Request URI Parameters

ParameterDescription
type (optional)Type of the room. Defaults to MultiPartyChat. Valid values include: DirectChat, MultiPartyChat, ModeratedChat and TownHall.

Request Headers

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

Listing Rooms 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","rooms":[{"roomId":"us-central#test#room1","alias":"morningNews","applicationId":"test","name":"MorningNews","description":"MorningNewsRoom-Chicago","type":"MultiPartyChat","streamKey":"mRq5pZFuQf21lDgLsip1KhNgXC1CVvzJqftZBOW5vX1Kq06YtosMYyeIppPCC41h34bO1NFBbk4f6YLCHXvGYBvX6UoGYwxL","created":"2018-02-04T18:21:28.280000000Z","lastUpdate":"2018-02-04T18:21:28.280000000Z","estimatedSize":null,"options":[]},{"roomId":"us-central#test#room2","alias":"EveningNews","applicationId":"test","name":"EveningNews","description":"EveningNewsRoom-Chicago","type":"MultiPartyChat","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 "rooms": [{
4 "roomId": "us-central#test#room1",
5 "alias": "morningNews",
6 "applicationId": "test",
7 "name": "Morning News",
8 "description": "Morning News Room - Chicago",
9 "type": "MultiPartyChat",
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 "roomId": "us-central#test#room2",
17 "alias": "EveningNews",
18 "applicationId": "test",
19 "name": "Evening News",
20 "description": "Evening News Room - Chicago",
21 "type": "MultiPartyChat",
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}

List Room API Status Codes

HTTPStatusRetryDescription
200 OKokneverRooms were successfully listed.
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.
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.

List Room API Response fields

FieldDescription
statusSee Status Codes.
roomsArray of room objects. See Room fields. Please note that estimatedSize will always be null.

Deleting a Room

This API allows to delete rooms.

Deleting a Room Request

Send a DELETE request to the /pcast/room/<urlEncodedRoomId> endpoint as shown:

HTTP
1DELETE /pcast/room/<urlEncodedRoomId>?type=MultiPartyChat 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/room/<urlEncodedRoomId>?type=MultiPartyChat \
2-H "Accept: application/json" \
3-H "Content-Type: application/json" \
4-u applicationId:secret \
5-X DELETE
Encoding: Room ID may contain characters that are unsafe for URLs. Be sure to encode the RoomId 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
urlEncodedRoomId (required)URL encoded ID of the room

Request Headers

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

Deleting a Room 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 Room API Status Codes

HTTPStatusRetryDescription
200 OKokneverRoom 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.
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.

Delete Room API Response fields

FieldDescription
statusSee Status Codes

Fork a Room

This API allows the caller to copy the active members (that is, the publishers) from one room to another room. Both the source and destination rooms must have previously been created.

A stream will be associated with the destination room which is a fork of the stream being published to the source room with the same content.

Fork a Room Request

Send a PUT request to the /pcast/room/<urlEncodedDestinationRoomId>/fork/<urlEncodedSourceRoomId> endpoint as shown:

HTTP
1PUT /pcast/room/<urlEncodedDestinationRoomId>/fork/<urlEncodedSourceRoomId> 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-room-fork"],
11 "options": []
12}
cURL
1$ curl https://pcast.phenixrts.com/pcast/room/<urlEncodedDestinationRoomId>/fork/<urlEncodedSourceRoomId> \
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-room-fork"],
9 "options": []
10 }'

Encoding: Room ID may contain characters that are unsafe for URLs. Be sure to encode the RoomId 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
urlEncodedSourceRoomId (required)URL encoded Room ID of the source room to fork from.
urlEncodedDestinationRoomId (required)URL encoded Room ID of the destination room 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 room. 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 room. 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 room. "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 Room 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 Room API Status Codes

HTTPStatusRetryDescription
200 OKokneverRoom 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 rooms 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 Room API Response fields

FieldDescription
statusSee Status Codes.
membersArray of session objects that have been forked.

Kill a Room

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

Kill a Room Request

Send a PUT request to the /pcast/room/<urlEncodedRoomId>/kill endpoint as shown:

HTTP
1PUT /pcast/room/<urlEncodedRoomId>/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/room/<urlEncodedRoomId>/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: Room ID may contain characters that are unsafe for URLs. Be sure to encode the RoomId 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
urlEncodedRoomId (required)ID of the room 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 Room 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: 648
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 Room API Status Codes

HTTPStatusRetryDescription
200 OKokneverRoom 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 room 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 Room API Response fields

FieldDescription
statusSee Status Codes.
killedMembersArray of session objects that have been killed.

Checking the State of a Room

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

Checking the State of a Room Request

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

HTTP
1GET /pcast/room/<urlEncodedRoomId>/publishers/count HTTP/1.1
2Host: pcast.phenixrts.com
3Accept: application/json
cURL
1$ curl https://pcast.phenixrts.com/pcast/room/<urlEncodedRoomId>/publishers/count?failIfLess=<numberOfRequiredPublishers> \
2-H "Accept: application/json" \
3-X GET
Encoding: Room ID may contain characters that are unsafe for URLs. Be sure to encode the RoomId 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
urlEncodedRoomId (required)URL encoded ID of the room

Request URI Parameters

ParameterDescription
failIfLess (optional)The number of required publishers that meet all criteria for the room.
withStreams (optional)The number of streams required per publisher to be considered active in the room. 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 Room 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 Room API Status Codes

HTTPStatusRetryDescription
200 OKokneverNumber of publishers was successfully reported.
400 Bad RequestvariesneverIndicates an issue with the request.
404 Not Foundnot-foundneverIndicates the room 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.

Room API Response fields

The response body is a text field with the number of publishers actively publishing a stream to the room.

Universal Live Manifest for a Room

This API allows to retrieve a live manifest of any type for a room. The URL is valid for the lifetime of the room and always points to the most recent stream in the room. In order for this to work, the stream must have enabled streaming capability.

Universal Live Manifest for a Room Request

Send a GET request to the /pcast/room/<urlEncodedRoomId>/<manifest> endpoint as shown:

HTTP
1GET /pcast/room/<urlEncodedRoomId>/live.m3u8 HTTP/1.1
2Host: pcast.phenixrts.com
3Accept: */*
cURL
1$ curl https://pcast.phenixrts.com/pcast/room/<urlEncodedRoomId>/live.m3u8 \
2-H "Accept: */*" \
3-X GET
Encoding: Room ID may contain characters that are unsafe for URLs. Be sure to encode the RoomId 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
urlEncodedRoomId (required)URL encoded ID of the room
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 room ID or alias will grant access to the playlist for the room. Alternatively, if the origin stream ID is known, access can be restricted to just a stream itself.

Universal Live Manifest for a Room 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 Room 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 room or the manifest was not found.
415 Unsupported Media TypevariesneverThe room 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 Room 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/room/<urlEncodedRoomId>/message endpoint as shown:

HTTP
1PUT /pcast/room/<urlEncodedRoomId>/message HTTP/1.1
2Host: pcast.phenixrts.com
3Accept: application/json
4Authorization: Basic YXBwbGljYXRpb25JZDpzZWNyZXQ=
5Content-Type: application/json
6Content-Length: 267
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/room/<urlEncodedRoomId>/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: Room ID may contain characters that are unsafe for URLs. Be sure to encode the RoomId 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 Room 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 room 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 Room Message API Response fields

FieldDescription
statusSee Status Codes
messageSee Message Object

Send Room 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/room/<urlEncodedRoomId>/messages endpoint as shown:

HTTP
1GET /pcast/room/<urlEncodedRoomId>/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/room/<urlEncodedRoomId>/messages?limit=100 \
2-u applicationId:secret \
3-H "Accept: application/json" \
4-H "Content-Type: application/json" \
5-X GET
Encoding: Room ID may contain characters that are unsafe for URLs. Be sure to encode the RoomId 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 Room 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 room 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 Room 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 Room

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

Purging Messages of a Room Request

Send a DELETE request to the /pcast/room/<urlEncodedRoomId>/messages endpoint as shown:

HTTP
1DELETE /pcast/room/<urlEncodedRoomId>/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/room/<urlEncodedRoomId>/messages \
2-H "Accept: application/json" \
3-H "Content-Type: application/json" \
4-u applicationId:secret \
5-X DELETE
Encoding: Room ID may contain characters that are unsafe for URLs. Be sure to encode the RoomId 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
urlEncodedRoomId (required)URL encoded ID of the room

Request Headers

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

Purging Messages of a Room 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 Room Messages API Status Codes

HTTPStatusRetryDescription
200 OKokneverRoom 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 room 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 Room 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