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:

PUT /pcast/room HTTP/1.1
Host: pcast.phenixrts.com
Accept: application/json
Authorization: Basic YXBwbGljYXRpb25JZDpzZWNyZXQ=
Content-Type: application/json
Content-Length: 172
 
{
    "room": {
        "alias": "<roomAlias>",
        "name": "<roomName>",
        "description": "<roomDescription>",
        "type": "MultiPartyChat",
        "options": [<roomOptions>]
    }
}

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

Room Object

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

Room Object Ingest Options

ingestOptions Usage

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

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

Creating a 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/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 427
 
{"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":[]}}

Create Room API Status Codes

HTTP	Status	Retry	Description
200 OK	ok	never	Room 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 room 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 Room API Response fields

Field	Description
status	See Status Codes
room	See Room fields

Room fields

Field	Description
alias	A user friendly unique identifier for the room.
applicationId	Application ID.
created	RFC 3339 compliant creation time of the room.
description	Description of the room.
estimatedSize	Number of members in the Room. The size is eventual consistent with typical lag of a few seconds.
lastUpdate	RFC 3339 compliant last update time of the room.
name	Unique name of the room.
options	Options for the room.
roomId	Unique identifier for the room.
streamKey	Push your RTMP feed to `rtmp://ingest.phenixrts.com:80/ingest/` using this stream key. Stream Key must not be shared.
type	Type of the room. Valid values include: DirectChat, MultiPartyChat, ModeratedChat and TownHall
ingestOptions	Ingest options object (when configured).

Ingest Options

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

Fetching a Room

This API allows to fetch a room.

Fetching a Room Request

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

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

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

Component	Description
urlEncodedRoomId (required)	URL encoded ID of the room

Request Headers

Header	Description
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/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 412
 
{"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":[],"ingestOptions":{"capabilities":["multi-bitrate","aspect-ratio=9x16"],"tags":["realTime"]}}}

Fetching a Room API Status Codes

HTTP	Status	Retry	Description
200 OK	ok	never	Room 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 room 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.
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 Room API Response fields

Field	Description
status	See Status Codes
room	Room 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:

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

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

Component	Description
urlEncodedRoomId (required)	ID of the room.

Request Headers

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

Fetch Room Member API Status Codes

HTTP	Status	Retry	Description
200 OK	ok	never	Room 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 room 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 Room Member API Response fields

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

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

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

This API allows to list existing rooms.

Listing Rooms Request

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

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

Request URI Parameters

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

Request Headers

Header	Description
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/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 830
 
{"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":[]}]}

List Room API Status Codes

HTTP	Status	Retry	Description
200 OK	ok	never	Rooms 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.
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.

List Room API Response fields

Field	Description
status	See Status Codes.
rooms	Array 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:

DELETE /pcast/room/<urlEncodedRoomId>?type=MultiPartyChat HTTP/1.1
Host: pcast.phenixrts.com
Accept: application/json
Content-Type: application/json
Content-Length: 0

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

Component	Description
urlEncodedRoomId (required)	URL encoded ID of the room

Request Headers

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

Delete Room API Status Codes

HTTP	Status	Retry	Description
200 OK	ok	never	Room 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.
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.

Delete Room API Response fields

Field	Description
status	See 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:

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

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

Component	Description
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

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

Fork Room API Status Codes

HTTP	Status	Retry	Description
200 OK	ok	never	Room 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 rooms 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 too long to execute. Please try again later.
5XX	varies	once immediately, then exponential backoff	A transient server error.

Error Responses

Please be aware that some server errors 5XX and request validation errors 400 and 401 may result in an arbitrary response body not encoded in JSON.

Fork Room API Response fields

Field	Description
status	See Status Codes.
members	Array 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:

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

Encoding

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

Component	Description
urlEncodedRoomId (required)	ID of the room 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 Room Response

The API call returns an HTTP response per the following:

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

Kill Room API Status Codes

HTTP	Status	Retry	Description
200 OK	ok	never	Room 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 room 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 Room API Response fields

Field	Description
status	See Status Codes.
killedMembers	Array 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:

GET /pcast/room/<urlEncodedRoomId>/publishers/count HTTP/1.1
Host: pcast.phenixrts.com
Accept: application/json

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

Component	Description
urlEncodedRoomId (required)	URL encoded ID of the room

Request URI Parameters

Parameter	Description
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/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 1
 
1

Health Room 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 room 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.

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:

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

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

Component	Description
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

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

Manifest Room 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 room or the manifest was not found.
415 Unsupported Media Type	varies	never	The room 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 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:

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

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

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

Request Fields

Field	Description
message (required)	Message Object

Message Object

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

User Object

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

Sending a Message Response

The platform will return a successful response that contains a "status" field. The HTTP status code is set according to the "status" field.

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

Send Room 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 room 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 Room Message API Response fields

Field	Description
status	See Status Codes
message	See Message Object

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

GET /pcast/room/<urlEncodedRoomId>/messages?limit=100 HTTP/1.1
Host: pcast.phenixrts.com
Accept: application/json
Authorization: Basic YXBwbGljYXRpb25JZDpzZWNyZXQ=
Content-Type: application/json

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

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

Request URI Parameters

Parameter	Description
limit (optional)	The number of messages to fetch. Defaults to 100.
beforeMessageId (optional)	The upper bound of the fetch range represented by another message ID.
afterMessageId (optional)	The lower bound of the fetch range represented by another message ID.
mimeTypes (optional)	Comma separated list of mime types. When provided only messages with the specified mime types will be returned. Note the search range is still the same so if no messages within the underlying range match then the result might be zero or less than the requested limit.

Fetching Messages Response

The platform will return a successful response that contains a "status" field. The HTTP status code is set according to the "status" field.

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

Fetch Room 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 room 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 Room 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 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:

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

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

Component	Description
urlEncodedRoomId (required)	URL encoded ID of the room

Request Headers

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

Purge Room Messages API Status Codes

HTTP	Status	Retry	Description
200 OK	ok	never	Room 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 room 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 Room Messages API Response fields

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

Page Content

v2025-01-13T17:19:39.000Z

Room API

Creating a Room#Copied URL

Creating a Room Request#Copied URL

Request Headers

Request Fields

Room Object

Room Object Ingest Options

ingestOptions Usage

Creating a Room Response#Copied URL

Create Room API Status Codes

Error Responses

Create Room API Response fields

Room fields

Ingest Options

Fetching a Room#Copied URL

Fetching a Room Request#Copied URL

Encoding

Request URI

Request Headers

Fetching a Room Response#Copied URL

Fetching a Room API Status Codes

Error Responses

Fetching a Room API Response fields

Fetching members of a room#Copied URL

Fetching members of a room Request#Copied URL

Encoding

Request URI

Request Headers

Fetching members of a room Response#Copied URL

Fetch Room Member API Status Codes

Error Responses

Fetch Room Member API Response fields

Room Member Object

Room Stream Object

Listing Rooms#Copied URL

Listing Rooms Request#Copied URL

Request URI Parameters

Request Headers

Listing Rooms Response#Copied URL

List Room API Status Codes

Error Responses

List Room API Response fields

Deleting a Room#Copied URL

Deleting a Room Request#Copied URL

Encoding

Request URI

Request Headers

Deleting a Room Response#Copied URL

Delete Room API Status Codes

Error Responses

Delete Room API Response fields

Fork a Room#Copied URL

Fork a Room Request#Copied URL

Encoding

Request URI

Request Headers

Request Fields

Fork a Room Response#Copied URL

Fork Room API Status Codes

Error Responses

Fork Room API Response fields

Kill a Room#Copied URL

Kill a Room Request#Copied URL

Encoding

Request URI

Request Headers

Request Fields

Kill a Room Response#Copied URL

Kill Room API Status Codes

Error Responses

Kill Room API Response fields

Checking the State of a Room#Copied URL

Checking the State of a Room Request#Copied URL

Encoding

Request URI

Request URI Parameters

Checking the State of a Room Response#Copied URL

Health Room API Status Codes

Error Responses

Room API Response fields

Creating a Room

Creating a Room Request

Creating a Room Response

Fetching a Room

Fetching a Room Request

Fetching a Room Response

Fetching members of a room

Fetching members of a room Request

Fetching members of a room Response

Listing Rooms

Listing Rooms Request

Listing Rooms Response

Deleting a Room

Deleting a Room Request

Deleting a Room Response

Fork a Room

Fork a Room Request

Fork a Room Response

Kill a Room

Kill a Room Request

Kill a Room Response

Checking the State of a Room

Checking the State of a Room Request

Checking the State of a Room Response

Universal Live Manifest for a Room

Universal Live Manifest for a Room Request

Universal Live Manifest for a Room Response

Sending a Message

Sending a Message Request

Sending a Message Response

Fetching Messages

Fetching Messages Request

Fetching Messages Response

Purging Messages of a Room

Purging Messages of a Room Request

Purging Messages of a Room Response