Admin API

The admin APIs are exposed as simple REST services. You can use any REST library indigenous to your backend technology stack.

All requests are made to our secure backend at https://pcast.phenixrts.com. We strongly encourage you to use the https endpoint. Phenix may stop supporting its less secure counterpart at any time.

Creating An Authentication Token

Check out our EdgeAuth libraries for how to generate edge tokens on your backend. This is the recommended way to issue authentication tokens.

For legacy and less common workflows, we support a REST API to generate tokens. Please contact your primary Phenix technical support contact before implementing a workflow based on tokens generated via the REST API.

Request

Authentication tokens are generated using a POST request as shown.

Example request for creating an authentication token

POST /pcast/auth HTTP/1.1
Host: pcast.phenixrts.com
Accept: application/json
Content-Type: application/json
Content-Length: 68

{
    "applicationId": "<applicationId>",
    "secret": "<secret>"
}

$ curl https://pcast.phenixrts.com/pcast/auth \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Content-Length: 68" \
-X POST \
-d '{
        "applicationId": "<applicationId>",
        "secret": "<secret>"
        "capabilities": ["<capability>"]
    }'

Request Headers:

Field	Value
Accept	application/json
Content-Type	application/json
Content-Length	68

Request Payload:

Field	Description
applicationId	Your application ID
secret	Your application secret
capabilities (optional)	An array of capabilities for the token

Supported Authentication Capabilities

Value	Description
wildcard	Creates a wildcard authentication token that can be used by multiple clients.
geo-country-allow=…	Comma separated list of allowed countries in ISO 3166. Example: geo-country-allow=US,UK,DE
geo-country-deny=…	Comma separated list of denied countries in ISO 3166. Example: geo-country-deny=US,IN,??

Response

The platform will return a successful response that contains a “status” and an “authenticationToken” field. The HTTP status code is set according to the “status” field.

HTTP/1.1 200 OK

Response Headers

Field	Value
Content-Type	application/json; charset=utf-8
Content-Length	52

Example response for authentication token requests

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 52

{"status":"ok","authenticationToken":"us-east#VaTd"}

{
    "status":"ok",
    "authenticationToken":"us-east#VaTd"
}

Response Fields

Field	Description
status	The status of the request
authenticationToken	The authentication token to use by your client

Status Codes

HTTP	Status	Retry	Description
200 OK	ok	never	Successful request, “authenticationToken” is valid and ready to use.
400 Bad Request	<not provided>	never	Indicates an issue with the request itself.
401 Unauthorized	unauthorized	never	The streaming platform was not able to authorize the provided credentials.
4XX	<varies>	never	Indicates an issue with the request itself.
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.

Creating A Stream Token

Check out our EdgeAuth libraries for how to generate edge tokens on your backend. This is the recommended way to issue stream tokens.

For legacy and less common workflows, we support a REST API to generate tokens. Please contact your primary Phenix technical support contact before implementing a workflow based on tokens generated via the REST API.

Request

Stream tokens are generated sending a POST request as shown.

If you provide an “originStreamId”, a view token is generated. Otherwise, a publish token is generated.

Example request for creating a stream token

POST /pcast/stream HTTP/1.1
Host: pcast.phenixrts.com
Accept: application/json
Content-Type: application/json
Content-Length: 194

{
    "applicationId": "<applicationId>",
    "secret": "<secret>",
    "sessionId": "<sessionId>",
    "originStreamId": "<originStreamId>",
    "capabilities": [
        "<capability>"
    ]
}

$ curl https://pcast.phenixrts.com/pcast/stream \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Content-Length: 138" \
-X POST \
-d '{
        "applicationId": "<applicationId>",
        "secret": "<secret>",
        "sessionId": "<sessionId>",
        "originStreamId": "<originStreamId>",
        "capabilities": ["<capability>"]
    }'

Request Headers:

Field	Value
Accept	application/json
Content-Type	application/json
Content-Length	138

Request Fields

Field	Description
applicationId (required)	Your application ID
secret (required)	Your application secret
sessionId (required)	The session ID of the client that you are generating this token for or the wildcard * enabling any authorized session to use the token
originStreamId (optional)	The stream ID of the published stream that you want to make available for viewing (omitted when creating a publish token)
capabilities (optional)	An array of capabilities for the new stream

Supported Stream Capabilities

Value	Token Type	Description
multi-bitrate	publish	Provide multi-bitrate ABR for each viewer of the stream. The platform transcodes, in real-time, to multiple quality levels for each stream. The number of quality levels depends on the contribution quality of the stream as selected with the quality capabilities.
aspect-ratio=WxH	publish	Crop the stream to the desired aspect ratio during multi-bitrate transcoding. Example: aspect-ratio=9x16 crops the image to portrait mode in 9 by 16 format. The cropping produces the highest resolution possible limited only by the resolution of the multi-bitrate layer.
streaming	publish	In addition to real-time streaming, create a transcoded live stream using adaptive HLS and MPEG+DASH streaming. The live stream contains multiple quality options from audio-only to highest video quality.
on-demand	publish	Persist the transcoded live stream for on-demand playback. The stream features the same capabilities as the adaptive multi-bit rate live stream and can be accessed time delayed.
streaming-lite	publish	Only create one rendition for the live stream that corresponds to the highest quality level.
on-demand-lite	publish	Only create one rendition for the on-demand stream that corresponds to the highest quality level.
token-auth	publish	Protects the live stream with edge auth tokens. When enabled it requires a ?streamToken=<edgeAuthToken> to be provided when accessing the manifests on all HTTP requests.
low-latency	publish	Experimental Use low latency settings for the adaptive bitrate live stream. This will trade bandwidth efficiency for lower latency.
high-fidelity	publish	Use high fidelity audio bitrate configuration for high-quality reproduction of sound.
rtmp	publish	In addition to real-time streaming, expose a RTMP streaming option.
channel	publish	The stream will be made available in the channel identified by one of the tags channelId: or channelAlias:. The channel must be owned by the same application as the stream.
audio-only	publish+subscribe	The stream will only have an audio track.
video-only	publish+subscribe	The stream will only have a video track.
real-time	subscribe	Use real-time streaming with typically less than 300 milliseconds delivery latency. This is the default.
broadcast	subscribe	Use broadcast real-time streaming with about 1 second delivery latency. This can be used for users with bad WiFi networks with high jitter and/or interference.
streaming	subscribe	Use adaptive live streaming using HLS or MPEG+DASH with about 8-12 seconds delivery latency. This can be used for broadcasts to clients with network connections with limited bandwidth or highly fluctuating bandwidth. It requires the publisher stream to have the “streaming” capability.
on-demand	subscribe	Use adaptive on-demand streaming using HLS or MPEG+DASH. This can be used to access the stream after it was recorded. It requires the publisher stream to have the “on-demand” capability.
rtmp	subscribe	Use RTMP for playback with about 1-2 seconds delivery latency. It requires the publisher stream to have the “rtmp” capability.

Supported Quality Capabilities

Value	Video Size	Description	Token Type	Video Bitrate, kbps	Audio Bitrate, kbps*	Recommended Bandwidth, kbps**
uld	144p	Ultra low definition	Publish	80	60	400
vld	240p	Very low definition	Publish	350	60	600
ld	360p	Low definition	Publish	520	60	1000
sd	480p	Standard definition - default	Publish	830	60	1500
hd	720p	High definition	Publish	1600	60	3000
fhd	1080p	Full high definition	Publish	3000	60	5000
xhd	1080p	Extended high definition	Publish	5500	60	10000
uhd	1080p+	Ultra high definition	Publish	8500	60	15000

Live/On-Demand Renditions

ID	Quality	Video Size	Video Framerate, fps	Video Codec	Video Bitrate, kbps	Audio Codec	Audio Bitrate, kbps
qcif	uld+	144p	15	h264 baseline 3.0 (avc1.42c01e)	80	AAC LC (mp4a.40.2)	64
sif	vld+	240p	15	h264 baseline 3.1 (avc1.42c01f)	350	AAC LC (mp4a.40.2)	64
ld	ld+	360p	15	h264 baseline 3.1 (avc1.42c01f)	520	AAC LC (mp4a.40.2)	64
sd	sd+	480p	30	h264 main 3.1 (avc1.42c01f)	830	AAC LC (mp4a.40.2)	128
hd	hd+	720p	30	h264 main 3.1 (avc1.42c01f)	1600	AAC LC (mp4a.40.2)	128
fhd	fhd+	1080p	30	h264 high 4.1 (avc1.640029)	3000	AAC LC (mp4a.40.2)	128
xhd	xhd+	1080p	30	h264 high 4.1 (avc1.640029)	5500	AAC LC (mp4a.40.2)	128

When enabling streaming or on-demand, each of the above rendition is made available if the stream quality is equal or better than the rendition itself.

The playlist for HLS and DASH leverage an adaptive bitrate configuration based on the available video and audio renditions. Example: A stream with hd quality will have two audio and five video renditions.

When using the streaming-lite capability, only the top layer is generated. Example: A stream with hd quality and streaming-lite rendition has one audio and one video rendition corresponding the the hd rendition.

Response

The platform will return a successful response that contains a “status” and a “streamToken” field. The HTTP status code is set according to the “status” field.

Response Headers

Field	Value
Content-Type	application/json; charset=utf-8
Content-Length	44

Example response for stream token requests

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 44

{"status":"ok","streamToken":"us-east#C1Nl"}

{
    "status":"ok",
    "streamToken":"us-east#C1Nl"
}

Response Fields

Field	Description
status	The status of the request
streamToken	The stream token to use by your client

Status Codes

HTTP	Status	Retry	Description
200 OK	ok	never	Successful request, “streamToken” is valid and ready to use.
400 Bad Request	<varies>	never	Indicates an issue with the request itself.
401 Unauthorized	unauthorized	never	The streaming platform was not able to authorize the provided credentials.
404 Not Found	not-found or origin-not-found	never	The stream specified in the “originStreamId” is not known to the platform.
410 Gone	origin-ended	never	The stream specified in the “originStreamId” has ended.
4XX	<varies>	never	Indicates an issue with the request itself.
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.

Terminating A Stream

Request

You can terminate any of your streams using a DELETE request. Typically, a stream will be terminated through the client API and this REST API may be used to censor streams.

DELETE /pcast/stream HTTP/1.1
Host: pcast.phenixrts.com
Accept: application/json
Content-Type: application/json
Content-Length: 124

{
    "applicationId": "<applicationId>",
    "secret": "<secret>",
    "streamId": "<streamId>",
    "reason": "<reason>"
}

$ curl https://pcast.phenixrts.com/pcast/stream \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-X DELETE \
-d '{
        "applicationId": "<applicationId>",
        "secret": "<secret>",
        "streamId": "<streamId>",
        "reason": "<reason>",
    }'

Request Fields

Field	Description
applicationId (required)	Your application ID
secret (required)	Your application secret
streamId (required)	The stream ID of the stream that you want to terminate
reason (required)	The reason of the termination

Reasons String

Value	Description
<empty>	The stream ended normally
ended	The stream ended normally
censored	The stream was censored
<custom>	A custom reason will be passed to your client

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"}

{
    "status":"ok"
}

Status Codes for terminating a stream

HTTP	Status	Retry	Description
200 OK	ok	never	Stream was successfully terminated.
400 Bad Request	<varies>	never	Indicates an issue with the request itself.
401 Unauthorized	unauthorized	never	The streaming platform was not able to authorize the provided credentials.
404 Not Found	not-found	never	The specified stream is not known to the platform.
410 Gone	already-ended	never	The specified stream has already ended.
410 Gone	resource-unavailable	never	The resources that hosted the specified stream are unavailable.
4XX	<varies>	never	Indicates an issue with the request itself.
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.

Deleting A On-Demand Stream

This API lets you delete an on-demand stream.

Request

You can delete an on-demand stream by using a DELETE request.

DELETE /pcast/stream/archive HTTP/1.1
Host: pcast.phenixrts.com
Accept: application/json
Content-Type: application/json
Content-Length: 124

{
    "applicationId": "<applicationId>",
    "secret": "<secret>",
    "streamId": "<streamId>",
    "reason": "<reason>"
}

$ curl https://pcast.phenixrts.com/pcast/stream/archive \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-X DELETE \
-d '{
        "applicationId": "<applicationId>",
        "secret": "<secret>",
        "streamId": "<streamId>",
        "reason": "<reason>"
    }'

Request Fields

Field	Description
applicationId (required)	Your application ID
secret (required)	Your application secret
streamId (required)	The stream ID of the on-demand stream that you want to delete
reason (required)	A reason for why the stream is deleted for your records.

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"}

{
    "status":"ok"
}

Status Codes

HTTP	Status	Retry	Description
200 OK	ok	never	Stream was successfully terminated.
400 Bad Request	<varies>	never	Indicates an issue with the request itself.
401 Unauthorized	unauthorized	never	The streaming platform was not able to authorize the provided credentials.
404 Not Found	not-found	never	The specified stream is not known to the platform.
408 Request Timeout	request-timeout	once immediately, then exponential backoff	Request timed out likely due to temporary resource or network conditions. Please try again.
409 Conflict	not-ended	after terminating the stream	Stream has not ended. On-demand streams can not be deleted until the stream has terminated. To forcefully terminate a stream, see Terminating A Stream.
410 Gone	already-deleted	never	The specified stream has already been deleted.
410 Gone	resource-unavailable	never	The resources that hosted the specified stream are unavailable.
4XX	<varies>	never	Indicates an issue with the request itself.
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.

Get Playlist Information

This API allows to get information for all the playlists of a live or on-demand stream.

Request

You can send a PUT request to the /pcast/stream/playlist endpoint as shown:

PUT /pcast/stream/playlist HTTP/1.1
Host: pcast.phenixrts.com
Accept: application/json
Content-Type: application/json
Content-Length: 98

{
    "applicationId": "<applicationId>",
    "secret": "<secret>",
    "streamId": "<streamId>"
}

$ curl https://pcast.phenixrts.com/pcast/stream/playlist \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-X PUT \
-d '{
        "applicationId": "<applicationId>",
        "secret": "<secret>",
        "streamId": "<streamId>"
    }'

Request Fields

Field	Description
applicationId (required)	Your application ID
secret (required)	Your application secret
streamId (required)	The stream ID of the stream whose playlist URIs are requested

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: 698

{"status":"ok","playlists":[{"name":"live-720.mpd","type":"Dash","uri":"https://pcast.phenixrts.com/video/application-id/us-central#us-central1-c.YfMSNkZM.20171121.9VuaQSac/live-720.mpd","isPrimary":false,"isVariant":false,"isProtected":false,"isEncrypted":false,info":{"bitrate":null,"height":720,"framesPerSecond":null}},{"name":"live.mpd","type":"Dash","uri":"https://pcast.phenixrts.com/video/application-id/us-central#us-central1-c.YfMSNkZM.20171121.9VuaQSac/live.mpd","isPrimary":true,"isVariant":true,"isProtected":false,"info":{"bitrate":null,"height":null,"framesPerSecond":null}},...],"streamInfo":{"startTime":"2017-11-21T20:53:43.529000000Z","endTime":"2017-11-21T20:53:40.955000000Z"}}

{
   "status": "ok",
   "playlists": [
      {
         "name": "live-720.mpd",
         "type": "Dash",
         "uri": "https://pcast.phenixrts.com/video/application-id/us-central#us-central1-c.YfMSNkZM.20171121.9VuaQSac/live-720.mpd",
         "isPrimary": false,
         "isVariant": false,
         "isProtected": false,
         "isEncrypted": false,
         "info": {
            "bitrate": null,
            "height": 720,
            "framesPerSecond": null
         }
      },
      {
         "name": "live.mpd",
         "type": "Dash",
         "uri": "https://pcast.phenixrts.com/video/application-id/us-central#us-central1-c.YfMSNkZM.20171121.9VuaQSac/live.mpd",
         "isPrimary": true,
         "isVariant": true
         "isProtected": false,
         "isEncrypted": false,
         "info": {
            "bitrate": null
            "height": null,
            "framesPerSecond": null
         }
      },
      ...
   ],
   "streamInfo": {
      "startTime": "2017-11-21T20:53:43.529000000Z",
      "endTime": "2017-11-21T20:53:40.955000000Z"
   }
}

Playlist API Status Codes

HTTP	Status	Retry	Description
200 OK	ok	never	Playlists were successfully retrieved.
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.
408 Request Timeout	request-timeout	once immediately, then exponential backoff	Request timed out likely due to temporary resource or network conditions. Please try again.
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.

Playlist API Response fields

Field	Description
status	See Status Codes
playlists	Array of playlists. See Playlist fields.
streamInfo	Metadata about the stream. See Stream Metadata fields.

Playlist fields

Field	Description
name	Name of the playlist
type	type of playlist - HLS or DASH
uri	URI of the playlist
isPrimary	Whether this is a primary playlist containing variant playlists
isVariant	Whether this is a variant playlist (Note: This flag is currently wrong. Use isPrimary until it is fixed.)
isProtected	Whether this playlist is protected with an edge auth token. See token-auth.
isEncrypted	Whether this playlist is encrypted with DRM
info	Metadata about the playlist. See Playlist metadata.

Playlist metadata

Field	Description
bitrate	bit rate of track(s) in the playlist. This is null when the bitrate is unknown or when there are tracks with different bitrates.
height	height of the track(s) in the playlist. This is null when the height is unknown or when there are tracks with different height.
framesPerSecond	frames per second (fps) of the track(s) in the playlist. This is null when the framesPerSecond value is unknown or when there are tracks with different frames per second.

Stream Metadata fields

Field	Description
startTime	RFC 3339 compliant start time of the stream
endTime	RFC 3339 compliant end time of the stream. This is null if the stream has not ended.

Accessing playlists

Request

Send a GET request to the /video/<applicationId>/<urlEncodedStreamId>/<manifest> endpoint as shown:

GET /video/<applicationId>/<urlEncodedStreamId>/<manifest> HTTP/1.1
Host: pcast.phenixrts.com
Accept: */*

$ curl https://pcast.phenixrts.com/video/<applicationId>/<urlEncodedStreamId>/<manifest> \
-H "Accept: */*" \
-X GET

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.

Response

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

Playlist API Status Codes

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

Notifications

The PCast™ streaming platform can notify your backend when streams start and stop.

Request

You can set the callback endpoint for your application using a PUT request.

PUT /pcast/application/<applicationId>/callback HTTP/1.1
Host: pcast.phenixrts.com
Accept: application/json
Content-Type: application/json
Content-Length: 194
Authorization: Basic YXBwbGljYXRpb25JZDpzZWNyZXQ=

{
    "callback": {
        "protocol": "<protocol>",
        "host": "<host>",
        "port": <port>,
        "method": "<method>",
        "path": "<path>",
        "query": "<query>"
    }
}

$ curl https://pcast.phenixrts.com/pcast/application/<applicationId>/callback \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-u applicationId:secret \
-X PUT \
-d '{
        "callback": {
            "protocol": "<protocol>",
            "host": "<host>",
            "port": <port>,
            "method": "<method>",
            "path": "<path>",
            "query": "<query>"
        }
    }'

Request Fields

Field	Description
credentials (optional)	The preferred way of passing the credentials is with HTTP authentication header. Alternatively they can be passed in the request body.
callback (required)	The object defining the callback endpoint. See object structure below.

Callback Object

Field	Default Value	Description
protocol (optional)	“http”	The protocol to use for notifications: “http” or “https”
host (required)		The host to use for notifications (E.g. “mywebsite.com”)
port (optional)	80 (HTTP) or 443 (HTTPS)	A numerical (not a string) value defining the port to use for notifications
method (optional)	“POST”	The HTTP method to use for notifications: “GET”, “POST” or “PUT”
path (optional)	“/”	The path to use for notifications (E.g. “/phenix/callback”)
query (optional)	empty	The query parameters (E.g. “param1=true&param2=false&param3”)

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: 107

{"status":"ok","endpoint":"POST https://webhook.site:443/1234abcd-1234-6789-0123-abcdef123456?param1=true"}

{
    "status": "ok",
    "endpoint": "POST https://webhook.site:443/1234abcd-1234-6789-0123-abcdef123456?param1=true"
}

Status Codes

HTTP	Status	Retry	Description
200 OK	ok	never	Stream was successfully terminated.
400 Bad Request	<varies>	never	Indicates an issue with the request itself.
401 Unauthorized	unauthorized	never	The streaming platform was not able to authorize the provided credentials.
4XX	<varies>	never	Indicates an issue with the request itself.
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.

Response Fields

Field	Description
status	The status code
endpoint	The resolved end point to confirm your settings were applied as intended.

Notification Types

The streaming platform notifies the callback endpoint when certain platform events occur.

Event Name	Description
Stream Started	Triggers when a new stream is published
Stream Ended	Triggers when a published stream ends
Live Available	Triggers when a live playlist of a published stream is ready
On-Demand Available	Triggers when a on-demand playlist of a published stream is ready

We will be using the callback.method of POST in the examples for each notification type below. However “GET”, “POST” or “PUT” are fully supported.

Stream Started Notification

POST <callback.path> HTTP/1.1
Host: <callback.host>:<callback.port>
Content-Type: application/json
Content-Length: 250

{
    "apiVersion": 0,
    "entity", "stream",
    "what", "started",
    "data": {
        "streamId": "<streamId>",
        "tags": [
            "<tag>"
        ]
    },
    "sessionId": "<sessionId>",
    "timestamp": "2019-01-23T21:12:55.384Z"
}

$ curl <callback.url> \
-H "Content-Type: application/json" \
-X POST \
-d '{
        "apiVersion": 0,
        "entity", "stream",
        "what", "started",
        "data": {
            "streamId": "<streamId>",
            "tags": [
                "<tag>"
            ]
        },
        "sessionId": "<sessionId>",
        "timestamp": "2019-01-23T21:12:55.384Z"
    }'

Request Fields

Field	Description
apiVersion	The API version the message conforms to
entity	Belongs to the “stream” entity
what	The type is “started” indicating that the stream started
data	The notification payload
data.streamId	The ID of the stream that started
data.tags	Array of string tags provided when publishing the stream. The order of tags may be different than the order of tags provided during publishing.
sessionId	The session ID of the client this stream belongs to
timestamp	The RFC3339 timestamp of when the request was initiated in Zulu time

Stream Ended Notification

POST <callback.path> HTTP/1.1
Host: <callback.host>:<callback.port>
Content-Type: application/json
Content-Length: 304

{
    "apiVersion": 0,
    "entity", "stream",
    "what", "ended",
    "data": {
        "streamId": "<streamId>",
        "tags": [
            "<tag>"
        ]
        "duration": 11457,
        "reason": "<reason>"
    },
    "sessionId": "<sessionId>",
    "timestamp": "2019-01-23T21:12:55.384Z"
}

$ curl <callback.url> \
-H "Content-Type: application/json" \
-X POST \
-d '{
        "apiVersion": 0,
        "entity", "stream",
        "what", "ended",
        "data": {
            "streamId": "<streamId>",
            "tags": [
                "<tag>"
            ]
            "duration": 11457,
            "reason": "<reason>"
        },
        "sessionId": "<sessionId>",
        "timestamp": "2019-01-23T21:12:55.384Z"
    }'

Request Fields

Field	Description
apiVersion	The API version the message conforms to
entity	Belongs to the “stream” entity
what	The type is “ended” indicating that the stream ended
data	The notification payload
data.streamId	The ID of the stream that started
data.tags	Array of string tags provided when publishing the stream
data.duration	Duration of the stream in milliseconds
data.reason	The reason the stream ended which may be an empty string or a custom reason
sessionId	The session ID of the client this stream belongs to
timestamp	The RFC3339 timestamp of when the request was initiated in Zulu time

Live Available Notification

Reach devices with adaptive multi-bitrate live streaming capabilities. Currently HLS and MPEG-DASH playlists in adaptive multi-bitrate and various quality levels are supported.

This also makes the stream available inside all our SDKs using the streaming capability when subscribing.

POST <callback.path> HTTP/1.1
Host: <callback.host>:<callback.port>
Content-Type: application/json
Content-Length: 222

{
    "apiVersion": 0,
    "entity", "stream",
    "what", "live",
    "data": {
        "streamId": "<streamId>",
        "uri": "<uri>"
    },
    "sessionId": "<sessionId>",
    "timestamp": "2019-01-23T21:12:55.384Z"
}

$ curl <callback.url> \
-H "Content-Type: application/json" \
-X POST \
-d '{
        "apiVersion": 0,
        "entity", "stream",
        "what", "live",
        "data": {
            "streamId": "<streamId>",
            "uri": "<uri>",
            "isPrimary": true,
            "isVariant": false
        },
        "sessionId": "<sessionId>",
        "timestamp": "2019-01-23T21:12:55.384Z"
    }'

Request Fields

Field	Description
apiVersion	The API version the message conforms to
entity	Belongs to the “stream” entity
what	Type “live” indicates a live playlist is available
data	The notification payload
data.streamId	The ID of the stream that started
data.uri	The URI of the playlist. File extensions: HLS -> .m3u8, MPEG-DASH -> .mpd
data.isPrimary	Whether this is a primary playlist containing variant playlists
data.isVariant	Whether this is a variant playlist (Note: This flag is currently wrong. Use isPrimary until it is fixed.)
sessionId	The session ID of the client this stream belongs to
timestamp	The RFC3339 timestamp of when the request was initiated in Zulu time

On-demand Available Notification

Provide adaptive multi-bitrate on-demand streaming capabilities. Currently HLS and MPEG-DASH playlists as adaptive multi-bitrate and specific quality levels are supported.

This also makes the stream available inside all our SDKs using the “on-demand” capability when subscribing.

POST <callback.path> HTTP/1.1
Host: <callback.host>:<callback.port>
Content-Type: application/json
Content-Length: 227

{
    "apiVersion": 0,
    "entity", "stream",
    "what", "on-demand",
    "data": {
        "streamId": "<streamId>",
        "uri": "<uri>"
    },
    "sessionId": "<sessionId>",
    "timestamp": "2019-01-23T21:12:55.384Z"
}

$ curl <callback.url> \
-H "Content-Type: application/json" \
-X POST \
-d '{
        "apiVersion": 0,
        "entity", "stream",
        "what", "on-demand",
        "data": {
            "streamId": "<streamId>",
            "uri": "<uri>",
            "isPrimary": true,
            "isVariant": false
        },
        "sessionId": "<sessionId>",
        "timestamp": "2019-01-23T21:12:55.384Z"
    }'

Request Fields

Field	Description
apiVersion	The API version the message conforms to
entity	Belongs to the “stream” entity
what	Type “on-demand” indicates a on-demand playlist is available
data	The notification payload
data.streamId	The ID of the stream that started
data.uri	The URI of the playlist. File extensions: HLS -> .m3u8, MPEG-DASH -> .mpd
data.isPrimary	Whether this is a primary playlist containing variant playlists
data.isVariant	Whether this is a variant playlist (Note: This flag is currently wrong. Use isPrimary until it is fixed.)
sessionId	The session ID of the client this stream belongs to
timestamp	The RFC3339 timestamp of when the request was initiated in Zulu time

HMAC Authentication

You can authenticate notifications by using the HMAC-SHA256 authentication scheme. HMAC refers to hash-based message authentication code.

To authenticate a notification, you must assert that it contains valid X-PCast-Content-Sha256 and Authorization headers.

Notification Headers

Header	Description
Authorization	Authentication information required by the HMAC-SHA256 scheme.
Content-Type	Indicates the original media type before any content encoding was applied for sending.
X-PCast-Content-Sha256	Base64 encoded SHA256 hash of the request body.
X-PCast-Timestamp	The RFC3339 timestamp of when the request was initiated in UNIX time

Validate X-PCast-Content-Sha256

To validate X-PCast-Content-Sha256 header you need to stringify the request body, and generate a SHA-265 hash from it. Then you need to compare generated hash with the hash in X-PCast-Content-Sha256.

    //Validate X-PCast-Content-Sha256
    function isContentSha256Valid(requestStringBody, contentSha256Header) {
        var generatedContentHash = crypto
            .createHash('sha256')
            .update(requestStringBody)
            .digest('base64');

        return contentSha256Header === generatedContentHash;
    }

Validate Authorization Header

The Authorization header consists of the HMAC hash of the request prefixed with HMAC-SHA256.

Authorization = ‘HMAC-SHA256 ’ + hash (HMAC created using the SHA-256 hash algorithm with the application secret as key)

To validate the HMAC hash of the Authorization header you must compare it with the one regenerated from the canonical representation of the request using your application secret as a key.

String-To-Sign = HTTP_METHOD + path_and_query + content_sha256_header + content_type_header + pcast_timestamp_header

    // Generate string to sign
    function getStringToSign(method, path, contentSha256, contentType, unixTimestamp) {
        return method + path + contentSha256 + contentType + unixTimestamp;
    }

    // Validate Authorization header
    function isAuthorizationHeaderValid(secret, stringToSign, authorizationHeader) {
        var generatedHmacSha256Hash = 'HMAC-SHA256 ' + crypto
            .createHmac('sha256', secret)
            .update(stringToSign)
            .digest('base64');

        return generatedHmacSha256Hash === authorizationHeader;
    }

Channel API

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

Creating a Channel

This API allows to create a channel.

Request

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

PUT /pcast/channel HTTP/1.1
Host: pcast.phenixrts.com
Accept: application/json
Authorization: Basic YXBwbGljYXRpb25JZDpzZWNyZXQ=
Content-Type: application/json
Content-Length: 172

{
    "channel": {
        "alias": "<channelAlias>",
        "name": "<channelName>",
        "description": "<channelDescription>",
        "options": [<channelOptions>]
    }
}

$ curl https://pcast.phenixrts.com/pcast/channel \
-u applicationId:secret \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-X PUT \
-d '{
        "channel": {
            "alias": "<channelAlias>",
            "name": "<channelName>",
            "description": "<channelDescription>",
            "options": [<channelOptions>]
        }
    }'

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.

Response

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

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 427

{"status":"ok","channel":{"channelId":"us-central#test#channe1","alias":"morningNews","applicationId":"test","name":"Morning News","description":"Morning News Channel - Chicago","type":"Channel","streamKey":"mRq5pZFuQf21lDgLsip1KhNgXC1CVvzJqftZBOW5vX1Kq06YtosMYyeIppPCC41h34bO1NFBbk4f6YLCHXvGYBvX6UoGYwxL","created":"2018-02-05T18:21:28.280000000Z","lastUpdate":"2018-02-05T18:21:28.280000000Z","estimatedSize":0,"options":[]}}

{
   "status" : "ok",
   "channel" : {
      "channelId" : "us-central#test#channel1",
      "alias" : "morningNews",
      "applicationId" : "test",
      "name" : "Morning News",
      "description" : "Morning News Channel - Chicago",
      "type" : "Channel",
      "streamKey" : "mRq5pZFuQf21lDgLsip1KhNgXC1CVvzJqftZBOW5vX1Kq06YtosMYyeIppPCC41h34bO1NFBbk4f6YLCHXvGYBvX6UoGYwxL",
      "created" : "2018-02-05T18:21:28.280000000Z",
      "lastUpdate" : "2018-02-05T18:21:28.280000000Z",
      "estimatedSize": 0,
      "options" : []
   }
}

Create Channel API Status Codes

HTTP	Status	Retry	Description
200 OK	ok	never	Channel has been successfully created.
400 Bad Request	<varies>	never	Indicates an issue with the request.
401 Unauthorized	unauthorized	never	The streaming platform was not able to authorize the provided credentials.
409 Conflict	already-exists	never	The channel already exists.
4XX	<varies>	never	Indicates an issue with the request.
503 Service Unavailable	capacity	once	The system is temporarily overloaded. Please try again later.
504 Gateway Timeout	rate-limited	once immediately, then exponential backoff	The system is temporarily overloaded. Please try again later.
5XX	<varies>	once immediately, then exponential backoff	A transient server error.

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.

Request

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

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

$ curl https://pcast.phenixrts.com/pcast/channel/<urlEncodedChannelId> \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-u applicationId:secret \
-X PUT

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

Response

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

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 412

{"status":"ok","channel":{"channelId":"local#test#channel1","alias":"channel1","applicationId":"test","name":"channel 1","description":"a channel description","type":"Channel","streamKey":"F4CIbURu34oYH1OikqZsqaEkK1wgCJ2Lmn4xaJlXGA24ptLip4wKSWnfFeAjj9HDSEJ4b7EafGrEp1d9G3L1A9h0avUC7HPc","created":"2018-02-05T22:20:25.304000000Z","lastUpdate":"2018-02-05T22:20:25.304000000Z","estimatedSize":13741,"options":[]}}

{
   "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" : []
   }
}

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.

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.

Request

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

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

$ curl https://pcast.phenixrts.com/pcast/channel/<urlEncodedRoomId>/members \
-u <applicationId>:<secret> \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-X GET

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

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
        }
    ]
}

{
    "status": "ok",
    "members": [
        {
            "sessionId": "us-southwest#DpMPWP3YQu8dmJCN9Vfn2v",
            "screenName": "Primary-mrvwman-438728",
            "role": "Presenter",
            "streams": [
                {
                    "type": "Presentation",
                    "uri": "pcast://phenixrts.com/us-southwest#us-west2-c.XfFVcxNg.20200205.PYIyIFS4?capabilities=multi-bitrate%2Cfhd",
                    "audioState": "TrackEnabled",
                    "videoState": "TrackEnabled"
                }
            ],
            "state": "Passive",
            "lastUpdate": 1580913727128
        }
    ]
}

Fetch Channel Member API Status Codes

HTTP	Status	Retry	Description
200 OK	ok	never	Channel members were successfully listed.
400 Bad Request	<varies>	never	Indicates an issue with the request.
401 Unauthorized	unauthorized	never	The streaming platform was not able to authorize the provided credentials.
404 Not Found	not found	never	The channel was not found.
4XX	<varies>	never	Indicates an issue with the request.
503 Service Unavailable	capacity	once	The system is temporarily overloaded. Please try again later.
504 Gateway Timeout	rate-limited	once immediately, then exponential backoff	The system is temporarily overloaded. Please try again later.
504 Gateway Timeout	time-exceeded	once immediately, then exponential backoff	The request took to long to execute. Please try again later.
5XX	<varies>	once immediately, then exponential backoff	A transient server error.

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.

Request

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

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

$ curl https://pcast.phenixrts.com/pcast/channels \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-u applicationId:secret \
-X GET

Request Headers

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

Response

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

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 830

{"status":"ok","channels":[{"channelId":"us-central#test#channel1","alias":"morningNews","applicationId":"test","name":"MorningNews","description":"MorningNewsChannel-Chicago","type":"Channel","streamKey":"mRq5pZFuQf21lDgLsip1KhNgXC1CVvzJqftZBOW5vX1Kq06YtosMYyeIppPCC41h34bO1NFBbk4f6YLCHXvGYBvX6UoGYwxL","created":"2018-02-04T18:21:28.280000000Z","lastUpdate":"2018-02-04T18:21:28.280000000Z","estimatedSize":null,"options":[]},{"channelId":"us-central#test#channel2","alias":"EveningNews","applicationId":"test","name":"EveningNews","description":"EveningNewsChannel-Chicago","type":"Channel","streamKey":"8oJgHdxCWht13CdBlmWev6BUm4D1hfiamsX0gpLNFaTCbJBN0Ty8jQiAa0mzmDuCA89AYYXjG8bp0pCFq3ehHFy1DJTbvGfr","created":"2018-02-05T18:21:28.280000000Z","lastUpdate":"2018-02-05T18:21:28.280000000Z","estimatedSize":null,"options":[]}]}

{
    "status": "ok",
    "channels": [{
        "channelId": "us-central#test#channel1",
        "alias": "morningNews",
        "applicationId": "test",
        "name": "Morning News",
        "description": "Morning News Channel - 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": "Evening News",
        "description": "Evening News Channel - Chicago",
        "type": "Channel",
        "streamKey": "8oJgHdxCWht13CdBlmWev6BUm4D1hfiamsX0gpLNFaTCbJBN0Ty8jQiAa0mzmDuCA89AYYXjG8bp0pCFq3ehHFy1DJTbvGfr",
        "created": "2018-02-05T18:21:28.280000000Z",
        "lastUpdate": "2018-02-05T18:21:28.280000000Z",
        "estimatedSize": null,
        "options": []
    }]
}

Deleting a Channel

This API allows to delete channels.

Request

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

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

$ curl https://pcast.phenixrts.com/pcast/channel/<urlEncodedChannelId> \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-u applicationId:secret \
-X DELETE

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

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"}

{
    "status": "ok"
}

Delete Channel API Status Codes

HTTP	Status	Retry	Description
200 OK	ok	never	Channel was successfully deleted.
400 Bad Request	<varies>	never	Indicates an issue with the request.
401 Unauthorized	unauthorized	never	The streaming platform was not able to authorize the provided credentials.
4XX	<varies>	never	Indicates an issue with the request.
503 Service Unavailable	capacity	once	The system is temporarily overloaded. Please try again later.
5XX	<varies>	once immediately, then exponential backoff	A transient server error.

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.

Request

Send a PUT request to the /pcast/channel/<urlEncodedDestinationChannelId>/fork/<urlEncodedSourceChannelId> endpoint as shown:

PUT /pcast/channel/<urlEncodedDestinationChannelId>/fork/<urlEncodedSourceChannelId> HTTP/1.1
Host: pcast.phenixrts.com
Accept: application/json
Content-Type: application/json
Content-Length: 86
Authorization: Basic YmlsbHk6c2VjcmV0cGFzc3dvcmQ=

{
    "streamCapabilities": [],
    "streamTags": ["my-channel-fork"],
    "options": []
}

$ curl https://pcast.phenixrts.com/pcast/channel/<urlEncodedDestinationChannelId>/fork/<urlEncodedSourceChannelId> \
-u <applicationId>:<secret> \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-X PUT \
-d '{
        "streamCapabilities": [],
        "streamTags": ["my-channel-fork"],
        "options": []
    }'

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.

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
        }
    ]
}

{
    "status": "ok",
    "members": [
        {
            "sessionId": "us-southwest#DpMPWP3YQu8dmJCN9Vfn2v",
            "screenName": "Primary-mrvwman-438728",
            "role": "Presenter",
            "streams": [
                {
                    "type": "Presentation",
                    "uri": "pcast://phenixrts.com/us-southwest#us-west2-c.XfFVcxNg.20200205.PYIyIFS4?capabilities=multi-bitrate%2Cfhd",
                    "audioState": "TrackEnabled",
                    "videoState": "TrackEnabled"
                }
            ],
            "state": "Passive",
            "lastUpdate": 1580913727128
        }
    ]
}

Fork Channel API Status Codes

HTTP	Status	Retry	Description
200 OK	ok	never	Channel was successfully forked.
400 Bad Request	<varies>	never	Indicates an issue with the request. Eg: Options must be an array of strings.
401 Unauthorized	unauthorized	never	The streaming platform was not able to authorize the provided credentials.
404 Not Found	not found	never	One or both of the source and destination channels are not found.
4XX	<varies>	never	Indicates an issue with the request.
503 Service Unavailable	capacity	once	The system is temporarily overloaded. Please try again later.
504 Gateway Timeout	rate-limited	once immediately, then exponential backoff	The system is temporarily overloaded. Please try again later.
504 Gateway Timeout	time-exceeded	once immediately, then exponential backoff	The request took to long to execute. Please try again later.
5XX	<varies>	once immediately, then exponential backoff	A transient server error.

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.

Request

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

PUT /pcast/channel/<urlEncodedChannelId>/kill HTTP/1.1
Host: pcast.phenixrts.com
Accept: application/json
Content-Type: application/json
Content-Length: 47
Authorization: Basic YmlsbHk6c2VjcmV0cGFzc3dvcmQ=

{
    "reason": "kill-reason",
    "options": []
}

$ curl https://pcast.phenixrts.com/pcast/channel/<urlEncodedChannelId>/kill \
-u <applicationId>:<secret> \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-X PUT \
-d '{
        "reason": "kill-reason",
        "options": []
    }'

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.

Response

The API call returns an HTTP response per the following:

HTTP/2 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 629

{
    "status": "ok",
    "killedMembers": [
        {
            "sessionId": "us-southwest#DpMPWP3YQu8dmJCN9Vfn2v",
            "screenName": "Primary-mrvwman-438728",
            "role": "Presenter",
            "streams": [
                {
                    "type": "Presentation",
                    "uri": "pcast://phenixrts.com/us-southwest#us-west2-c.XfFVcxNg.20200205.PYIyIFS4?capabilities=multi-bitrate%2Cfhd",
                    "audioState": "TrackEnabled",
                    "videoState": "TrackEnabled"
                }
            ],
            "state": "Passive",
            "lastUpdate": 1580913727128
        }
    ]
}

{
    "status": "ok",
    "killedMembers": [
        {
            "sessionId": "us-southwest#DpMPWP3YQu8dmJCN9Vfn2v",
            "screenName": "Primary-mrvwman-438728",
            "role": "Presenter",
            "streams": [
                {
                    "type": "Presentation",
                    "uri": "pcast://phenixrts.com/us-southwest#us-west2-c.XfFVcxNg.20200205.PYIyIFS4?capabilities=multi-bitrate%2Cfhd",
                    "audioState": "TrackEnabled",
                    "videoState": "TrackEnabled"
                }
            ],
            "state": "Passive",
            "lastUpdate": 1580913727128
        }
    ]
}

Kill Channel API Status Codes

HTTP	Status	Retry	Description
200 OK	ok	never	Channel was successfully killed.
400 Bad Request	<varies>	never	Indicates an issue with the request. Eg: Options must be an array of strings.
401 Unauthorized	unauthorized	never	The streaming platform was not able to authorize the provided credentials or Field “reason” must be a string.
404 Not Found	not found	never	The channel was not found.
4XX	<varies>	never	Indicates an issue with the request.
503 Service Unavailable	capacity	once	The system is temporarily overloaded. Please try again later.
504 Gateway Timeout	rate-limited	once immediately, then exponential backoff	The system is temporarily overloaded. Please try again later.
504 Gateway Timeout	time-exceeded	once immediately, then exponential backoff	The request took to long to execute. Please try again later.
5XX	<varies>	once immediately, then exponential backoff	A transient server error while processing the request.

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.

Request

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

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

$ curl https://pcast.phenixrts.com/pcast/channel/<urlEncodedChannelId>/publishers/count?failIfLess=<numberOfRequiredPublishers> \
-H "Accept: application/json" \
-X GET

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.

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

1

Health Channel API Status Codes

HTTP	Status	Retry	Description
200 OK	ok	never	Number of publishers was successfully reported.
400 Bad Request		never	Indicates an issue with the request.
404 Not Found	not-found	never	Indicates the channel was not found.
4XX		never	Indicates an issue with the request.
412 Precondition Failed		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		once immediately, then exponential backoff	A transient server error.

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.

Request

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

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

$ curl https://pcast.phenixrts.com/pcast/channel/<urlEncodedChannelId>/live.m3u8 \
-H "Accept: */*" \
-X GET

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.

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

Found. Redirecting to /video/<applicationId>/<streamId>/live.m3u8

Manifest Channel API Status Codes

HTTP	Status	Retry	Description
302 Found		never	The manifest was successfully located and a redirect URL is provided.
400 Bad Request		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		never	The channel does not support streaming.
4XX		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		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.

Request

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

PUT /pcast/channel/<urlEncodedChannelId>/message HTTP/1.1
Host: pcast.phenixrts.com
Accept: application/json
Authorization: Basic YXBwbGljYXRpb25JZDpzZWNyZXQ=
Content-Type: application/json
Content-Length: 303

{
    "message": {
        "from": {
            "screenName": "Screen Name",
            "role": "Moderator",
            "lastUpdate": 0
        },
        "mimeType": "text/plain",
        "message": "My message",
        "tags": ["my-tag", "my-other-tag"]
    }
}

$ curl https://pcast.phenixrts.com/pcast/channel/<urlEncodedChannelId>/message \
-u applicationId:secret \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-X PUT \
-d '{
         "message": {
            "from": {
                "screenName": "Screen Name",
                "role": "Moderator",
                "lastUpdate": 0
            },
            "mimeType": "text/plain",
            "message": "My message",
            "tags": ["my-tag", "my-other-tag"]
        }
    }'

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.

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"]}}

{
    "status": "ok",
    "message": {
        "messageId": "us-central#room|test#testing.xV1OVWEkOxZm|0000000009",
        "timestamp": 1596088080439,
        "deletedTimestamp": 0,
        "from": {
            "sessionId": "api",
            "screenName": "Screen Name",
            "role": "Moderator",
            "lastUpdate": 0
        },
        "mimeType": "text/plain",
        "message": "My message",
        "tags": [
            "my-tag",
            "my-other-tag"
        ]
    }
}

Send Channel Message API Status Codes

HTTP	Status	Retry	Description
200 OK	ok	never	Message has been successfully sent.
400 Bad Request	<varies>	never	Indicates an issue with the request.
401 Unauthorized	unauthorized	never	The streaming platform was not able to authorize the provided credentials.
404 Not Found	not-found	never	The channel does not exist.
413 Payload Too Large	<varies>	never	One of the fields exceeds the limits. The size limit for messages is 1024 bytes. The total limit for all tags is 512 bytes. The screen name and mime type each must not exceed 128 bytes.
4XX	<varies>	never	Indicates an issue with the request.
503 Service Unavailable	capacity	once	The system is temporarily overloaded. Please try again later.
504 Gateway Timeout	rate-limited	once immediately, then exponential backoff	The system is temporarily overloaded. Please try again later.
5XX	<varies>	once immediately, then exponential backoff	A transient server error.

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.

Request

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

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

$ curl https://pcast.phenixrts.com/pcast/channel/<urlEncodedChannelId>/messages?limit=100 \
-u applicationId:secret \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-X GET

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.

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}

{
    "status": "ok",
    "messages": [
        {
            "messageId": "us-central#room|test#testing.xV1OVWEkOxZm|0000000243",
            "timestamp": 1596089241062,
            "deletedTimestamp": 0,
            "from": {
                "sessionId": "local#IrGTKf0ztwN3H5xORrtD9e",
                "screenName": "ScreenName58611",
                "role": "Participant",
                "lastUpdate": 1596089235915
            },
            "mimeType": "text/plain",
            "message": "Test message 240:1596089241045",
            "tags": []
        }
    ],
    "hasMoreBefore": false,
    "hasMoreAfter": false
}

Fetch Channel Messages API Status Codes

HTTP	Status	Retry	Description
200 OK	ok	never	Messages have been successfully fetched.
400 Bad Request	<varies>	never	Indicates an issue with the request.
401 Unauthorized	unauthorized	never	The streaming platform was not able to authorize the provided credentials.
404 Not Found	not-found	never	The channel does not exist.
413 Payload Too Large	limit-too-large	never	Too many messages are requested. The maximal limit is 128 messages per request.
4XX	<varies>	never	Indicates an issue with the request.
503 Service Unavailable	capacity	once	The system is temporarily overloaded. Please try again later.
504 Gateway Timeout	rate-limited	once immediately, then exponential backoff	The system is temporarily overloaded. Please try again later.
5XX	<varies>	once immediately, then exponential backoff	A transient server error.

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.

Request

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

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

$ curl https://pcast.phenixrts.com/pcast/channel/<urlEncodedChannelId>/messages \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-u applicationId:secret \
-X DELETE

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

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}

{
    "status": "ok",
    "deletedCount": 1
}

Purge Channel Messages API Status Codes

HTTP	Status	Retry	Description
200 OK	ok	never	Channel was successfully deleted.
400 Bad Request	<varies>	never	Indicates an issue with the request.
401 Unauthorized	unauthorized	never	The streaming platform was not able to authorize the provided credentials.
404 Not Found	not-found	never	The channel does not exist.
4XX	<varies>	never	Indicates an issue with the request.
503 Service Unavailable	capacity	once	The system is temporarily overloaded. Please try again later.
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.

Purge Channel Messages API Response fields

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

Room API

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

Creating a Room

This API allows to create 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>]
    }
}

$ curl https://pcast.phenixrts.com/pcast/room \
-u applicationId:secret \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-X PUT \
-d '{
        "room": {
            "alias": "<roomAlias>",
            "name": "<roomName>",
            "description": "<roomDescription>",
            "type": "MultiPartyChat",
            "options": [<roomOptions>]
        }
    }'

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.
name (required)	Unique name of the room.
description (required)	A description for the room.
type (required)	Type of the room. Defaults to MultiPartyChat. Valid values include: DirectChat, MultiPartyChat, ModeratedChat and TownHall.
options (required)	An array of options for the room. An empty array is required if there are no options.

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":[]}}

{
   "status" : "ok",
   "room" : {
      "roomId" : "us-central#test#room1",
      "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.

Create Room API Response fields

Field	Description
status	See Status Codes
room	See Room fields

Room fields

Field	Description
roomId	Unique identifier for the room.
alias	A user friendly unique identifier for the room.
applicationId	Application ID.
name	Unique name of the room.
description	Description of the room.
type	Type of the room. Valid values include: DirectChat, MultiPartyChat, ModeratedChat and TownHall
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 room.
lastUpdate	RFC 3339 compliant last update time of the room.
estimatedSize	Number of members in the Room. The size is eventual consistent with typical lag of a few seconds.
options	Options for the room.

Fetching a Room

This API allows to fetch 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

$ curl https://pcast.phenixrts.com/pcast/room/<urlEncodedRoomId> \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-u applicationId:secret \
-X GET

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

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":[]}}

{
   "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" : []
   }
}

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.

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.

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=

$ curl https://pcast.phenixrts.com/pcast/room/<urlEncodedRoomId>/members \
-u <applicationId>:<secret> \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-X GET

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

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
        }
    ]
}

{
    "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.

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.

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

$ curl https://pcast.phenixrts.com/pcast/rooms \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-u applicationId:secret \
-X GET

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

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":[]}]}

{
    "status": "ok",
    "rooms": [{
        "roomId": "us-central#test#room1",
        "alias": "morningNews",
        "applicationId": "test",
        "name": "Morning News",
        "description": "Morning News Room - 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": "Evening News",
        "description": "Evening News Room - 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.

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.

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

$ curl https://pcast.phenixrts.com/pcast/room/<urlEncodedRoomId>?type=MultiPartyChat \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-u applicationId:secret \
-X DELETE

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

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"}

{
    "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.

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.

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": []
}

$ curl https://pcast.phenixrts.com/pcast/room/<urlEncodedDestinationRoomId>/fork/<urlEncodedSourceRoomId> \
-u <applicationId>:<secret> \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-X PUT \
-d '{
        "streamCapabilities": [],
        "streamTags": ["my-room-fork"],
        "options": []
    }'

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

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
        }
    ]
}

{
    "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 to long to execute. Please try again later.
5XX	<varies>	once immediately, then exponential backoff	A transient server error.

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.

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": []
}

$ curl https://pcast.phenixrts.com/pcast/room/<urlEncodedRoomId>/kill \
-u <applicationId>:<secret> \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-X PUT \
-d '{
        "reason": "kill-reason",
        "options": []
    }'

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.

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
        }
    ]
}

{
    "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.

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.

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

$ curl https://pcast.phenixrts.com/pcast/room/<urlEncodedRoomId>/publishers/count?failIfLess=<numberOfRequiredPublishers> \
-H "Accept: application/json" \
-X GET

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.

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

1

Health Room API Status Codes

HTTP	Status	Retry	Description
200 OK	ok	never	Number of publishers was successfully reported.
400 Bad Request		never	Indicates an issue with the request.
404 Not Found	not-found	never	Indicates the channel was not found.
4XX		never	Indicates an issue with the request.
412 Precondition Failed		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		once immediately, then exponential backoff	A transient server error.

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.

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: */*

$ curl https://pcast.phenixrts.com/pcast/room/<urlEncodedRoomId>/live.m3u8 \
-H "Accept: */*" \
-X GET

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.

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

Found. Redirecting to /video/<applicationId>/<streamId>/live.m3u8

Manifest Room API Status Codes

HTTP	Status	Retry	Description
302 Found		never	The manifest was successfully located and a redirect URL is provided.
400 Bad Request		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		never	The channel does not support streaming.
4XX		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		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.

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"]
    }
}

$ curl https://pcast.phenixrts.com/pcast/room/<urlEncodedRoomId>/message \
-u applicationId:secret \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-X PUT \
-d '{
         "message": {
            "from": {
                "screenName": "Screen Name",
                "role": "Moderator",
                "lastUpdate": 0
            },
            "mimeType": "text/plain",
            "message": "My message",
            "tags": ["my-tag", "my-other-tag"]
        }
    }'

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.

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"]}}

{
    "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.

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.

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

$ curl https://pcast.phenixrts.com/pcast/room/<urlEncodedRoomId>/messages?limit=100 \
-u applicationId:secret \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-X GET

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.

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}

{
    "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.

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.

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

$ curl https://pcast.phenixrts.com/pcast/room/<urlEncodedRoomId>/messages \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-u applicationId:secret \
-X DELETE

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

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}

{
    "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.
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.

Purge Room Messages API Response fields

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

Stream API

APIs for streams let you publish, subscribe, destroy and manage streams. In addition, the APIs let you create and fetch replays.

Publishing a URI

This API allows to publish a stream from a URI.

Request

Send a PUT request to the pcast/:tenancy/stream/publish/uri/:type endpoint as shown:

PUT pcast/<applicationId>/stream/publish/uri/<type> HTTP/1.1
Authorization: Bearer <edgeAuthToken>
Host: pcast.phenixrts.com
Accept: application/json
Content-Type: application/json

{
    "uri": "<uri>",
    "options": [<options>]
}

$ curl https://pcast.phenixrts.com/pcast/<applicationId>/stream/publish/uri/<type> \
-H "Authorization: Bearer <edgeAuthToken>" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-X PUT \
-d '{
        "uri": "<uri>",
        "options": [<options>]
    }'

Request Headers

Header	Description
Authorization (required)	Use Bearer authentication with a EdgeAuthToken

Request URI

Component	Description
applicationId (required)	The application ID that the request belongs to
type (required)	The remote URI type such as mp4, m3u8, udp, srt,…

Request Fields

Field	Description
uri (required)	The URI to publish such as srt://103.19.109.140:4201
options (optional)	For future use

Request (multipart/form-data)

Send a POST request to the pcast/:tenancy/stream/publish/uri/:type endpoint as shown:

POST pcast/<applicationId>/stream/publish/uri/<type> HTTP/1.1
Host: pcast.phenixrts.com
Accept: application/json
Content-Type: multipart/form-data

{
    "edgeAuthToken": "<edgeAuthToken>",
    "uri": "<uri>",
    "options": [<options>]
}

$ curl https://pcast.phenixrts.com/pcast/<applicationId>/stream/publish/uri/<type> \
-H "Accept: application/json" \
-H "Content-Type: multipart/form-data" \
-X POST \
-F jsonBody='{
        "edgeAuthToken": "<edgeAuthToken>",
        "uri": "<uri>",
        "options": [<options>]
    }'

Request URI

Component	Description
applicationId (required)	The application ID that the request belongs to
type (required)	The remote URI type such as mp4, m3u8, udp, srt,…

Request Fields

Field	Description
edgeAuthToken (required)	EdgeAuthToken used to connect and authenticate to the platform and publish the stream
uri (required)	The URI to publish such as srt://73.103.226.97:4201
options (optional)	For future use

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: 518

{"status":"ok","streamId":"us-central#us-central1-c.K3hpFbOX.20210913.I9LYKcSz","sharedSecret":"DIGEST:eyJhcHBsaWNhdGlvbklkIjoiZGVtbyIsImRpZ2VzdCI6ImlkdG5oVjc2WEFseUsxSWdNTFJMbkdET01CLzhzdE84N0JEUkNKNkdzNjZzNmFPeEJ5a3RlQzVuU09LSlVUWWxqVGpVdHRJVnphcHJHdlg4THgxUkRBPT0iLCJ0b2tlbiI6IntcInN0cmVhbUlkXCI6XCJldXJvcGUtd2VzdCNldXJvcGUtd2VzdDEtYi40NU9EMDdaQS4yMDIxMDkxNS5JRVp3YTdmeFwiLFwiaW5zdGFuY2VSb3V0ZUtleVwiOlwidW5pY2FzdC5ldXJvcGUtd2VzdC5ldXJvcGUtd2VzdDEtYi40NU9EMDdaQVwiLFwiZXhwaXJlc1wiOjE2MzIzMDM1NDAzNDl9In0=","options":[]}```

{
  "status": "ok",
  "streamId": "us-central#us-central1-c.K3hpFbOX.20210913.I9LYKcSz",
  "sharedSecret": "DIGEST:eyJhcHBsaWNhdGlvbklkIjoiZGVtbyIsImRpZ2VzdCI6ImlkdG5oVjc2WEFseUsxSWdNTFJMbkdET01CLzhzdE84N0JEUkNKNkdzNjZzNmFPeEJ5a3RlQzVuU09LSlVUWWxqVGpVdHRJVnphcHJHdlg4THgxUkRBPT0iLCJ0b2tlbiI6IntcInN0cmVhbUlkXCI6XCJldXJvcGUtd2VzdCNldXJvcGUtd2VzdDEtYi40NU9EMDdaQS4yMDIxMDkxNS5JRVp3YTdmeFwiLFwiaW5zdGFuY2VSb3V0ZUtleVwiOlwidW5pY2FzdC5ldXJvcGUtd2VzdC5ldXJvcGUtd2VzdDEtYi40NU9EMDdaQVwiLFwiZXhwaXJlc1wiOjE2MzIzMDM1NDAzNDl9In0=",
  "options": []
}

Publish URI API Status Codes

HTTP	Status	Retry	Description
200 OK	ok	never	Stream has been successfully published.
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.
402 Unauthorized	geo-restricted	never	The access to the content is geo-restricted.
403 Unauthorized	geo-blocked	never	The access to the content is geo-blocked.
409 Conflict	conflicting-capability	never	Ingest capabilities are conflicting. Only one must be specified at a time.
415 Unsupported Media Type	invalid-source-uri	never	The URI to publish is not a valid URI.
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.

Publish URI API Response fields

Field	Description
status	See Status Codes
streamId	The stream ID of the ingest stream
sharedSecret	The shared secret used in follow on operations on the stream
options	For future use

Fetching a Replay Manifest

This API allows to create and fetch replay manifests.

Request

Send a Get request to the /pcast/:tenancy/stream/replay/:type.m3u8 endpoint as shown:

GET /pcast/:tenancy/stream/replay/:type.m3u8?edgeAuthToken=<edgeAuthToken>&startTime=<startTime>&endTime=<endTime> HTTP/1.1
Host: pcast.phenixrts.com
Accept: application/json

$ curl https://pcast.phenixrts.com/pcast/<applicationId>/stream/replay/primary.m3u8?edgeAuthToken=<edgeAuthToken>&startTime=<startTime>&endTime=<endTime> \
-x GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \

Request URI

Component	Description
applicationId (required)	The application ID that the request belongs to.
type (required)	The manifest type such as primary.m3u8 for for primary manifest or xhd.m3u8 for quality manifest.

Request Parameters

Field	Description
edgeAuthToken (required)	EdgeAuthToken used to connect and authenticate to the platform and subscribe to a stream
startTime (required)	The date, formatted as ‘yyyy-MM-dd’T'HH:mm:ss.SSS'Z’‘, from which replay should start
endTime (required)	The date, formatted as 'yyyy-MM-dd’T'HH:mm:ss.SSS'Z’‘, until which replay should last
apiVersion (optional)	The API version the message conforms to. Default to '0’
httpRoundTripTime (optional)	The round trip time

Response

The platform will return a successful response that contains a playlist manifest. Or it will return error object with status on failure.

Success response example for primary manifest

HTTP/1.1 200 OK
Content-Type: application/vnd.apple.mpegurl; charset=utf-8
Content-Length: 427
#EXTM3U

#EXT-X-STREAM-INF:PROGRAM-ID=1,RESOLUTION=1920x1080,CODECS="avc1.640029,mp4a.40.2",BANDWIDTH=5628000,AVERAGE-BANDWIDTH=5628000,FRAME-RATE=30
xhd.m3u8?tenancy=test&edgeAuthToken=DIGEST%3AeyJhcHBsaWNhdGlvbklkIjoidGVzdCIsImRpZ2VzdCI6IjFuUU90ZnpKTmwwRUVLaHVBWGE4YWd0RGNNaGdGbEhTbksyRElsNTlTS0RTZ2xlUjc3c3NpTmRQcGdhMnZYVEhuSEJCdWIwQmdYRTQ2a3ZvbmNBcmFBPT0iLCJ0b2tlbiI6IntcImV4cGlyZXNcIjoxOTQ0MjE2MDAwMDAwLFwiY2FwYWJpbGl0aWVzXCI6W1wicmVwbGF5XCJdLFwib3JpZ2luU3RyZWFtSWRcIjpcImxvY2FsI3N0YW5kYWxvbmUuVFpkcnkwdjcuMjAyMTA5MTQuUFN5V1E2dk1cIixcInJlcXVpcmVkVGFnXCI6XCJyb29tSWQ6bG9jYWwjdGVzdCN0ZXN0Q2hhbm5lbC40UjBsVHU5Y1o3NjNcIn0ifQ%3D%3D&startTime=Tue+Sep+14+2021+08%3A05%3A52+GMT%2B0000&endTime=Tue+Sep+14+2021+08%3A06%3A02+GMT%2B0000&options=
...

#EXTM3U

#EXT-X-STREAM-INF:PROGRAM-ID=1,RESOLUTION=1920x1080,CODECS="avc1.640029,mp4a.40.2",BANDWIDTH=5628000,AVERAGE-BANDWIDTH=5628000,FRAME-RATE=30
xhd.m3u8?tenancy=test&edgeAuthToken=DIGEST%3AeyJhcHBsaWNhdGlvbklkIjoidGVzdCIsImRpZ2VzdCI6IjFuUU90ZnpKTmwwRUVLaHVBWGE4YWd0RGNNaGdGbEhTbksyRElsNTlTS0RTZ2xlUjc3c3NpTmRQcGdhMnZYVEhuSEJCdWIwQmdYRTQ2a3ZvbmNBcmFBPT0iLCJ0b2tlbiI6IntcImV4cGlyZXNcIjoxOTQ0MjE2MDAwMDAwLFwiY2FwYWJpbGl0aWVzXCI6W1wicmVwbGF5XCJdLFwib3JpZ2luU3RyZWFtSWRcIjpcImxvY2FsI3N0YW5kYWxvbmUuVFpkcnkwdjcuMjAyMTA5MTQuUFN5V1E2dk1cIixcInJlcXVpcmVkVGFnXCI6XCJyb29tSWQ6bG9jYWwjdGVzdCN0ZXN0Q2hhbm5lbC40UjBsVHU5Y1o3NjNcIn0ifQ%3D%3D&startTime=Tue+Sep+14+2021+08%3A05%3A52+GMT%2B0000&endTime=Tue+Sep+14+2021+08%3A06%3A02+GMT%2B0000&options=

Replay Manifest 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.
402 Unauthorized	geo-restricted	never	The access to the content is geo-restricted.
403 Unauthorized	geo-blocked	never	The access to the content is geo-blocked.
408 Request Timeout	request-timeout	once immediately, then exponential backoff	Request timed out likely due to temporary resource or network conditions. Please try again.
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.

Transformation API

APIs for the composition and transcoding of streams

Creating a Composition

This API allows for composition of a single stream from multiple streams

Request

Send a POST request to /pcast/composition endpoint as shown:

POST /pcast/composition HTTP/1.1
Host: pcast.phenixrts.com
Accept: application/json
Content-Type: application/json
Content-Length: 524
Authorization: Basic YXBwbGljYXRpb25JZDpzZWNyZXQ=

{
    "composition": {
        "type": "<compositionType>",
        "streams": [
            {
                "streamId": "<streamId1>",
                "offset": {
                    "anchor": "TopLeft",
                    "x": 0,
                    "y": 0
                },
                "width": 640,
                "height": 480
            },
            {
                "streamId": "<streamId2>"
            }
        ],
        "capabilities": ["multi-bitrate"],
        "tags": ["<tag1>", "<tag2>"]
    }
}

$ curl https://pcast.phenixrts.com/pcast/composition \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-u applicationId:secret \
-X POST \
-d '{
        "composition": {
            "type": "<compositionType>",
            "streams": [
                {
                    "streamId": "<streamId1>",
                    "offset": {
                        "anchor": "TopLeft",
                        "x": 0,
                        "y": 0
                    },
                    "width": 640,
                    "height": 480
                },
                {
                    "streamId": "<streamId2>"
                }
            ],
            "capabilities": ["multi-bitrate"],
            "tags": ["<tag1>", "<tag2>"]
        }
    }'

Request Fields

Field	Description
composition (required)	See Composition object below
tags (optional)	Tags for the Composition stream
credentials (optional)	The preferred way of passing the credentials is with HTTP authentication header. Alternatively they can be passed in the request body.

Composition Object

Field	Description
type (required)	Type of composition that need to be applied. See Composition types below.
streams (required)	Array of streams that need to be composed. See Stream Object below.
capabilities	See Composition Capabilities below

Composition Types

Field	Description
PictureInPicture	Main stream is displayed on the full screen and other streams are displayed in inset windows. The main stream is the first stream of all streams.

Stream Object

Field	Description
streamId (required)	The stream ID of the the input.
offset (optional)	The offset of the input video relative to the composition canvas. See Offset Object below.
width (optional)	The width of the input on the composition canvas.
height (optional)	The height of the input on the composition canvas.

Offset Object

Field	Description
anchor (optional)	The anchor for the offset. See Anchor Object below.
x (optional)	The horizontal offset relative to the anchor.
y (optional)	The vertical offset relative to the anchor.

Anchor Object

Value	Description
TopLeft	Anchor relative to top left corner.
TopRight	Anchor relative to top right corner.
BottomLeft	Anchor relative to bottom left corner.
BottomRight	Anchor relative to bottom right corner.
Center	Anchor relative to the center.

Composition Capabilities

Value	Description
prefer-h264	Output H.264 stream if possible
prefer-vp8	Output VP8 stream if possible
multi-bitrate	Multi bitrate stream
multi-bitrate-codec=vp8	Multi bitrate VP8 stream
multi-bitrate-codec=h264	Multi bitrate H.264 stream
uld	Output Ultra low definition - 80kbps stream
vld	Output Very low definition - 350kbps stream
ld	Output Low definition - 520kbps stream
sd	Output Standard definition - 830kbps - default stream
hd	Output High definition - 1600kbps stream
fhd	Output Full high definition - 3000kbps stream
xhd	Output Extended high definition - 5500kbps stream
uhd	Output Ultra high definition - 8500kbps stream

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: 85

{"status":"ok","compositionId":"us-central#us-central1-c.8q9rSY86.20180412.CCiaENCV"}

{
   "status":"ok",
   "compositionId":"us-central#us-central1-c.8q9rSY86.20180412.CCiaENCV"
}

Create Composition API Response fields

Field	Description
status	See status codes below
compositionId	ID of the composed stream

Create Composition API Status Codes

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

Updating a Composition

This API allows for modifying a composition created above.

Request

Send a PUT request to /pcast/composition endpoint as shown:

PUT /pcast/composition/<compositionId> HTTP/1.1
Host: pcast.phenixrts.com
Accept: application/json
Content-Type: application/json
Content-Length: 319
Authorization: Basic YXBwbGljYXRpb25JZDpzZWNyZXQ=

{
    "streams": [
        {
            "streamId": "<streamId1>",
            "offset": {
                "anchor": "TopLeft",
                "x": 0,
                "y": 0
            },
            "width": 640,
            "height": 480
        },
        {
            "streamId": "<streamId2>"
        }
    ]
}

$ curl https://pcast.phenixrts.com/pcast/composition/<compositionId> \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-u applicationId:secret \
-X PUT \
-d '{
        "streams": [
            {
                "streamId": "<streamId1>",
                "offset": {
                    "anchor": "TopLeft",
                    "x": 0,
                    "y": 0
                },
                "width": 640,
                "height": 480
            },
            {
                "streamId": "<streamId2>"
            }
        ]
    }'

Request Fields

Field	Description
compositionId (required)	The ID of the composition.
streams (required)	Array of streams that need to be composed. See Stream Object below.
credentials (optional)	The preferred way of passing the credentials is with HTTP authentication header. Alternatively they can be passed in the request body.

Stream Object

Field	Description
streamId (required)	The stream ID of the the input.
offset (optional)	The offset of the input video relative to the composition canvas. See Offset Object below.
width (optional)	The width of the input on the composition canvas.
height (optional)	The height of the input on the composition canvas.

Offset Object

Field	Description
anchor (optional)	The anchor for the offset. See Anchor Object below.
x (optional)	The horizontal offset relative to the anchor.
y (optional)	The vertical offset relative to the anchor.

Anchor Object

Value	Description
TopLeft	Anchor relative to top left corner.
TopRight	Anchor relative to top right corner.
BottomLeft	Anchor relative to bottom left corner.
BottomRight	Anchor relative to bottom right corner.
Center	Anchor relative to the center.

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"}

{
   "status":"ok"
}

Update Composition API Response fields

Field	Description
status	See status codes below

Update Composition API Status Codes

HTTP	Status	Retry	Description
200 OK	ok	never	Composition was successfully updated.
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 composition stream 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.

Deleting a Composition

This API allows for deletion of a composition stream

Request

Send a DELETE request to /pcast/composition/<urlEncodedCompositionlId> endpoint as shown:

DELETE /pcast/composition/<urlEncodedCompositionId> HTTP/1.1
Host: pcast.phenixrts.com
Accept: application/json
Content-Type: application/json
Content-Length: 28
Authorization: Basic YXBwbGljYXRpb25JZDpzZWNyZXQ=

{
    "reason": "<reason>"
}

$ curl https://pcast.phenixrts.com/pcast/composition/<urlEncodedCompositionId> \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Content-Length: 28" \
-u applicationId:secret \
-X DELETE \
-d '{
        "reason": "<reason>"
    }'

Request Fields

Field	Description
reason (optional)	Reason for deleting the composition
credentials (optional)	The preferred way of passing the credentials is with HTTP authentication header. Alternatively they can be passed in the request body.

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"}

{
    "status": "ok"
}

Delete Composition API Response fields

Field	Description
status	See status codes below

Delete Composition API Status Codes

HTTP	Status	Retry	Description
200 OK	ok	never	Composition 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 composition stream does not exist.
409 Conflict	already-deleted	never	The Composition is already deleted.
410 Gone	already-deleted	never	The stream has already ended.
410 Gone	already-ended	never	The stream has already ended.
410 Gone	resource-unavailable	never	The stream has already ended.
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.

Start Transcoding

This API allows for transcoding an ongoing stream.

Request

Send a POST request to /pcast/transcoding endpoint as shown:

POST /pcast/transcoding HTTP/1.1
Host: pcast.phenixrts.com
Accept: application/json
Content-Type: application/json
Content-Length: 210
Authorization: Basic YXBwbGljYXRpb25JZDpzZWNyZXQ=

{
    "transcoding": {
        "type": "DASH",
        "originStreamId": "<streamId>",
        "onDemand": true,
        "audioOnly": false,
        "quality": "hd",
        "tags": ["<tag1>", "<tag2>"]
    }
}

$ curl https://pcast.phenixrts.com/pcast/transcoding \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Content-Length: 210" \
-u applicationId:secret \
-X PUT \
-d '{
        "transcoding": {
            "type": "DASH",
            "originStreamId": "<streamId>",
            "onDemand": true,
            "audioOnly": false,
            "quality": "hd",
            "tags": ["<tag1>", "<tag2>"]
        }
    }'

Request Fields

Field	Description
transcoding (required)	See Transcoding object below
credentials (optional)	The preferred way of passing the credentials is with HTTP authentication header. Alternatively they can be passed in the request body.

Transcoding Object

Field	Description
type (required)	Format the stream will be transcoded to. See Transcoding types below.
originStreamId (required)	ID of the Stream that will be transcoded
onDemand (optional)	Persist the transcoded live stream for on-demand playback. The stream features the same capabilities as the adaptive multi-bit rate live stream and can be accessed time delayed.
audioOnly (optional)	Transcode audio only stream. This is mutually exclusive with videoOnly.
videoOnly (optional)	Transcode video only stream. This is mutually exclusive with audioOnly.
quality (optional)	See Transcoding qualities below
tags (optional)	Tags for the Transcoded stream

Transcoding Types

Field	Description
DASH	Dynamic Adaptive Streaming over HTTP
HLS	HTTP Live Streaming

Transcoding Qualities

Field	Description
uld	Output Ultra low definition - 80kbps stream
vld	Output Very low definition - 350kbps stream
ld	Output Low definition - 520kbps stream
sd	Output Standard definition - 830kbps - default stream
hd	Output High definition - 1600kbps stream
fhd	Output Full high definition - 3000kbps stream
xhd	Output Extended high definition - 5500kbps stream
uhd	Output Ultra high definition - 8500kbps stream

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: 85

{"status":"ok","transcodingId":"us-central#us-central1-c.8q9rSY86.20180412.PNGRcHO8"}

{
    "status": "ok",
    "transcodingId": "us-central#us-central1-c.8q9rSY86.20180412.PNGRcHO8"
}

Start Transcoding API Response fields

Field	Description
status	See status codes below
transcodingId	ID of the transcoded stream

Start Transcoding API Status Codes

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

Stop Transcoding

This API allows for stopping the transcoding of a stream.

Request

Send a DELETE request to /pcast/transcoding/<urlEncodedTranscodingId> endpoint as shown:

DELETE /pcast/transcoding/<urlEncodedTranscodingId> HTTP/1.1
Host: pcast.phenixrts.com
Accept: application/json
Content-Type: application/json
Content-Length: 28
Authorization: Basic YXBwbGljYXRpb25JZDpzZWNyZXQ=

{
    "reason": "<reason>"
}

$ curl https://pcast.phenixrts.com/pcast/transcoding/<urlEncodedTranscodingId> \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Content-Length: 28" \
-u applicationId:secret \
-X DELETE \
-d '{
        "reason": "<reason>"
    }'

Request Fields

Field	Description
reason (optional)	Reason for deleting the transcoded stream
credentials (optional)	The preferred way of passing the credentials is with HTTP authentication header. Alternatively they can be passed in the request body.

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"}

{
    "status": "ok"
}

Stop Transcoding API Response fields

Field	Description
status	See status codes below

Delete Transcoding API Status Codes

HTTP	Status	Retry	Description
200 OK	ok	never	Transcoding 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.
409 Conflict	already-deleted	never	The Transcoding is already deleted.
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.

Reporting API

APIs for generating reports

Generate a Publishing Report

This API generates a publishing report for all streams during an interval.

In order to be able to generate reports, your account needs to be provisioned accordingly. Please contact your primary Phenix technical support contact if you wish to use reporting.

Request

Send a PUT request to /pcast/reporting/publishing endpoint as shown:

PUT /pcast/reporting/publishing HTTP/1.1
Host: pcast.phenixrts.com
Accept: application/json
Content-Type: application/json
Content-Length: 157
Authorization: Basic YXBwbGljYXRpb25JZDpzZWNyZXQ=

{
    "publishingReport": {
        "applicationIds": ["example.com"],
        "start": "2020-01-01T00:00:00Z",
        "end": "2020-02-01T00:00:00Z"
    }
}

$ curl https://pcast.phenixrts.com/pcast/reporting/publishing \
-u <applicationId>:<secret> \
-H "Accept: text/csv" \
-H "Content-Type: application/json" \
-X PUT \
-d '{
        "publishingReport": {
            "applicationIds": ["example.com"],
            "start": "2020-01-01T00:00:00Z",
            "end": "2020-02-01T00:00:00Z"
        }
    }'
--remote-name
--remote-header-name

Request Headers

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

Request Query Parameters

Name	Description
version (optional)	Must be in the format of ‘YYYY-MM-dd’. If absent, a default value will be used as described in Publishing Report Versions

Publishing Report Versions

Version	Description
2021-09-07	The default if request is made before 2022-04-19 14:00:00 UTC.
2021-10-20	The default if request is made on or after 2022-04-19 14:00:00 UTC.

Request Fields

Field	Description
publishingReport (required)	See PublishingReport object below

PublishingReport Object

Field	Description
applicationIds (optional)	Array of applications IDs to report for. By default, it will report publishing for the application ID from credentials.
streamIds (optional)	Array of stream IDs to report for. Limits the report to just these streams.
channelIds (optional)	Array of channel IDs to report for. Limits the report to just these channels.
channelAliases (optional)	Array of channel aliases to report for. Limits the report to just these channels.
roomIds (optional)	Array of room IDs to report for. Limits the report to just these rooms.
roomAliases (optional)	Array of room aliases to report for. Limits the report to just these rooms.
tags (optional)	Array of tags to report for. Limits the report to just these tags.
start (required)	The report start time. Either an RFC3339 timestamp string or an integer of UNIX epoch time in milliseconds.
end (required)	The report end time. Either an RFC3339 timestamp string or an integer of UNIX epoch time in milliseconds.

Note: All filter conditions are cumulative.

Response

The response is in CSV format.

Report Response Fields (Version 2021-09-07)

Column	Description
ReportTimestamp	Time of report generation
PeriodStartTimestamp	Start time of the reporting period
PeriodEndTimestamp	End time of the reporting period
ApplicationId	Application ID of the stream
ChannelAlias	Channel alias of the stream
ChannelId	Channel ID of the stream
RoomAlias	Room alias of the stream
RoomId	Room ID of the stream
StreamId	Stream ID of the publisher
Region	Region of the publisher
AudioQuality	Audio quality of the publisher, or “video-only” if the publisher was video-only
VideoQuality	Video quality of the publisher, or “audio-only” if the publisher was audio-only
PublishedMinutesDuringPeriod	The duration published during the report period
PublishedMinutesTotal	Total duration of the publishing stream, empty if stream did not end within the report period
PeakConcurrentViews	Peak number of concurrent viewing streams
TotalViews	Total number of viewing streams
FramesPerSecond	Frames per second of the publishing stream
StartTimestamp	Timestamp at which the publishing stream started
EndTimestamp	Timestamp at which the publishing stream ended
StartedDuringPeriod	Whether the publishing stream started during the period
EndedDuringPeriod	Whether the publishing stream ended during the period
EndedReason	Why the publishing stream ended, empty if stream did not end within the report period
DeviceId	Unique device ID of the publisher
RemoteAddress	IP address of the publisher
IngestStreamId	Stream ID of the ingest stream, empty if stream did not have a corresponding ingest stream
IngestStreamEndedReason	Why the ingest stream ended, empty if stream did not have a corresponding ingest stream
Live	Does the publisher have “streaming” capability
VOD	Does the publisher have “on-demand” or “on-demand-archive=PT…” capability
RTMP	Does the publisher have “rtmp” capability
LiveLite	Does the publisher have “streaming-lite” capability
VODLite	Does the publisher have “on-demand-lite” capability
MBR	Does the publisher have “multi-bitrate” capability
MBRContribution	Does the publisher have “multi-bitrate-contribution” capability
AudioOnly	Does the publisher have “audio-only” capability
Tags	Tags on the publishing stream
Capabilities	Capabilities on the publishing stream
EncodingProfile	Encoding profile of the publishing stream

Report Response Fields (Version 2021-10-20)

Column	Description
ReportTimestamp	Time of report generation
PeriodStartTimestamp	Start time of the reporting period
PeriodEndTimestamp	End time of the reporting period
ApplicationId	Application ID of the stream
ChannelAlias	Channel alias of the stream
ChannelId	Channel ID of the stream
RoomAlias	Room alias of the stream
RoomId	Room ID of the stream
StreamId	Stream ID of the publisher
Region	Region of the publisher
AudioQuality	Audio quality of the publisher, or “video-only” if the publisher was video-only
VideoQuality	Video quality of the publisher, or “audio-only” if the publisher was audio-only
PublishedMinutesDuringPeriod	The duration published during the report period
PublishedMinutesTotal	Total duration of the publishing stream, empty if stream did not end within the report period
FramesPerSecond	Frames per second of the publishing stream
PeakConcurrentViews	Peak number of concurrent viewing streams
TotalViews	Total number of viewing streams
StartTimestamp	Timestamp at which the publishing stream started
EndTimestamp	Timestamp at which the publishing stream ended
StartedDuringPeriod	Whether the publishing stream started during the period
EndedDuringPeriod	Whether the publishing stream ended during the period
EndedReason	Why the publishing stream ended, empty if stream did not end within the report period
DeviceId	Unique device ID of the publisher
RemoteAddress	IP address of the publisher
ContributionMethod	The method of publishing, either “URI”, “RTMP”, or “ITP-WebRTC”
IngestStreamId	Stream ID of the ingest stream, empty if stream did not have a corresponding ingest stream
IngestStreamEndedReason	Why the ingest stream ended, empty if stream did not have a corresponding ingest stream
IngestSource	Source of the published stream, one of “iOS SDK”, “Android SDK”, “Web SDK”, “Phenix Encoder”, “RTMP Encoder”, or “Admin API”
MultiBitrateTranscoding	Whether MultiBitrate transcoding is done for the stream. “TRUE” if either 1) “streaming” capability is set and “streaming-lite” capability is missing, or 2) “on-demand” capability is set and “on-demand-lite” capability is missing, or 3) “multi-bitrate” capability is set.
Repackaging	Whether repackaging work is done for the stream. “TRUE” if any of the capabilities “streaming”, “on-demand”, or “rtmp” is presernt, or if ContributionMethod is “URI” or “RTMP”
Composition	Whether composition work is done for the stream. “TRUE” if the capability “composition” is set.
Tags	Tags on the publishing stream
Capabilities	Capabilities on the publishing stream
audio_only	Does the publisher have “audio-only” capability
video_only	Does the publisher have “video-only” capability
encoding_profile	Encoding profile of the publishing stream
multi_bitrate	Does the publisher have “multi-bitrate” capability
multi_bitrate_contribution	Does the publisher have “multi-bitrate-contribution” capability
streaming	Does the publisher have “streaming” capability
on_demand	Does the publisher have “on-demand” or “on-demand-archive=PT…” capability
rtmp	Does the publisher have “rtmp” capability
streaming_lite	Does the publisher have “streaming-lite” capability
on_demand_lite	Does the publisher have “on-demand-lite” capability

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 1,522
Content-Disposition: attachment; filename="20200305T161052Z-START20200101T000000Z-END20200201T000000Z-Publishing-fGGvDe.csv"

ReportTimestamp,PeriodStartTimestamp,PeriodEndTimestamp,ApplicationId,ChannelAlias,ChannelId,RoomAlias,RoomId,StreamId,Region,AudioQuality,VideoQuality,PublishedMinutesDuringPeriod,PublishedMinutesTotal,PeakConcurrentViews,TotalViews,FramesPerSecond,StartTimestamp,EndTimestamp,StartedDuringPeriod,EndedDuringPeriod,EndedReason,DeviceId,RemoteAddress,Ingest,Live,VOD,RTMP,LiveLite,VODLite,MBR,MBRContribution,AudioOnly,Tags,Capabilities,EncodingProfile
2020-03-05T16:10:53.769Z,2020-01-01T00:00:00.000Z,2020-02-01T00:00:00.000Z,example.com,,us-northeast#example.com#channel123456.S1b486elbH4I,,,us-northeast#US-ASHBURN-AD-1.abc1dmrQ.20191204.LggGuzQ8,us-northeast,,sd,44640,,,,60.12,2019-12-04T12:36:22.476Z,,FALSE,FALSE,,a18af5b7cf914765bd066b13ba842a90953d0bb92bf58c7cfd7b6839b861e5ed,::ffff:52.4.228.111,FALSE,FALSE,TRUE,FALSE,FALSE,FALSE,FALSE,FALSE,FALSE,channelId:us-northeast#example.com#channel123456.S1b486elbH4I|Status:STREAMING,sd|detached|rtmp|publish-uri,phenix-2020
2020-03-05T16:10:53.769Z,2020-01-01T00:00:00.000Z,2020-02-01T00:00:00.000Z,example.com,,,exampleRoomAlias,asia-south#example#roomName.abcdee,asia-south#asia-south1-c.Bqac2GbH.20191203.Vxg6P1AD,asia-south,,sd,44640,,,,59.89,2019-12-03T02:57:15.756Z,,FALSE,FALSE,,3d14957e6209e1c77db3086557d6a42655f8a54ded2a2cea33c9f43506c56297,::ffff:53.5.212.150,FALSE,FALSE,FALSE,FALSE,FALSE,TRUE,FALSE,FALSE,FALSE,x-ingest,publish-uri|resilient|monitor-tracks|no-session-stream-events|transcoding={}|sd|multi-bitrate|prefer-h264|origin-shield,phenix-2020

curl: Saved to filename '20200204T171148Z-START20200101T000000Z-END20200201T000000Z-RealTime-RWYkT1.csv'

If the request fails, the platform will return a failed response that contains a “status” field. The HTTP status code is set according to the “status” field.

HTTP/1.1 400 Bad request
Content-Type: application/json; charset=utf-8
Content-Length: 37

{"status":"excessive-report-interval"}

$ cat publishing
{
   "status":"excessive-report-interval"
}

Publishing report API Response fields

Field	Description
status	See status codes below

Publishing report API Status Codes

HTTP	Status	Retry	Description
200 OK	ok	never	Report was successfully created.
400 Bad Request	<varies>	never	Indicates an issue with the request.
400 Bad Request	excessive-report-interval	never	The interval for the report exceed 1 year.
400 Bad Request	period-start-outside-supported-window	never	The year of the start of period is more than 1 year before the current year.
400 Bad Request	period-end-must-be-in-past	never	The end of period is in future.
400 Bad Request	period-end-must-be-after-start	never	The end of period is less than or equal to the start of the period.
400 Bad Request	malformed-version-in-request-query-parameter	never	The supplied version in HTTP query parameter does not conform to the format “YYYY-MM-dd”.
400 Bad Request	version-does-not-exist	never	The supplied version in HTTP query parameter does not exist, see Publishing Report Versions for supported versions.
400 Bad Request	unsupported	never	The parameter combination is not supported.
401 Unauthorized	unauthorized	never	The streaming platform was not able to authorize the provided credentials.
408 Request Timeout	request-timeout	once immediately, then exponential backoff	Request timed out likely due to temporary resource or network conditions. Please try again.
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.

Generate a Viewing Report

This API generates a viewing report for all streams during an interval.

In order to be able to generate reports, your account needs to be provisioned accordingly. Please contact your primary Phenix technical support contact if you wish to use reporting.

Request

Send a PUT request to /pcast/reporting/viewing endpoint as shown:

PUT /pcast/reporting/viewing HTTP/1.1
Host: pcast.phenixrts.com
Accept: application/json
Content-Type: application/json
Content-Length: 174
Authorization: Basic YXBwbGljYXRpb25JZDpzZWNyZXQ=

{
    "viewingReport": {
        "kind": "RealTime",
        "applicationIds": ["example.com"],
        "start": "2020-01-01T00:00:00Z",
        "end": "2020-02-01T00:00:00Z"
    }
}

$ curl https://pcast.phenixrts.com/pcast/reporting/viewing \
-u <applicationId>:<secret> \
-H "Accept: text/csv" \
-H "Content-Type: application/json" \
-X PUT \
-d '{
        "viewingReport": {
            "kind": "RealTime",
            "applicationIds": ["example.com"],
            "start": "2020-01-01T00:00:00Z",
            "end": "2020-02-01T00:00:00Z"
        }
    }'
--remote-name
--remote-header-name

Request Headers

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

Request Fields

Field	Description
viewingReport (required)	See ViewingReport object below

ViewingReport Object

Field	Description
kind (required)	Kind of viewing report to generate.
applicationIds (optional)	Array of applications IDs to report for. By default, it will report viewing for the application ID from credentials.
streamIds (optional)	Array of stream IDs to report for. Limits the report to just these streams.
sessionIds (optional)	Array of session IDs to report for. Limits the report to just these sessions.
originStreamIds (optional)	Array of origin stream IDs to report for. Limits the report to just these origin streams.
channelIds (optional)	Array of channel IDs to report for. Limits the report to just these channels.
channelAliases (optional)	Array of channel aliases to report for. Limits the report to just these channel aliases.
tags (optional)	Array of tags to report for. Limits the report to just these tags.
originTags (optional)	Array of origin tags to report for. Limits the report to just these origin tags.
start (required)	The report start time. Either an RFC3339 timestamp string or an integer of UNIX epoch time in milliseconds.
end (required)	The report end time. Either an RFC3339 timestamp string or an integer of UNIX epoch time in milliseconds.

Note: All filter conditions are cumulative.

ViewingReport Kinds

Field	Description
RealTime	Report for real time viewing.
RTMP	Report for RTMP viewing.
HLS	Report for HLS viewing.
DASH	Report for DASH viewing.

Response

The response is in CSV format.

Report Response Fields

Column	Description	Real Time	RTMP	HLS	DASH
ReportTimestamp	Time of report generation	✔	✔	✔	✔
PeriodStartTimestamp	Start time of the reporting period	✔	✔	✔	✔
PeriodEndTimestamp	End time of the reporting period	✔	✔	✔	✔
ApplicationId	Application ID of the stream	✔	✔	✔	✔
ChannelAlias	Channel alias of the stream	✔	✔	✔	✔
ChannelId	Channel ID of the stream	✔	✔	✔	✔
OriginStreamId	Stream ID of the origin	✔	✔	✔	✔
OriginRegion	Region of the origin	✔	✔	✔	✔
OriginFramesPerSecond	Frames per second of the origin	✔	✔	✔	✔
OriginAudioQuality	Audio quality of the origin, or “video-only” if the origin was video-only	✔	✔	✔	✔
OriginVideoQuality	Video quality of the origin, or “audio-only” if the origin was audio-only	✔	✔	✔	✔
OriginTags	Tags on the origin stream	✔	✔	✔	✔
ViewedMinutesDuringPeriod	The duration viewed during the report period	✔	✔	✔	✔
ViewedMinutesTotal	Total duration of the viewing stream, empty if stream did not end within the report period	✔	✔	×	×
TotalBytes	The total bytes bidirectionally transferred for the stream	✔	✔	✔	✔
StartTimestamp	Timestamp at which the viewing stream started	✔	✔	✔	✔
EndTimestamp	Timestamp at which the viewing stream ended	✔	✔	✔	✔
StartedDuringPeriod	Whether the viewing stream started during the period	✔	✔	✔	✔
EndedDuringPeriod	Whether the viewing stream ended during the period	✔	✔	✔	✔
StreamId	Stream ID of the viewer	✔	✔	×	×
Region	Region of the viewer	✔	✔	×	×
FramesPerSecond	Frames per second of the viewer	✔	✔	×	×
AudioQuality	Audio quality of the viewing stream, or “video-only” if the viewer or corresponding origin was video-only	✔	✔	×	×
VideoQuality	Video quality of the viewing stream, or “audio-only” if the viewer or corresponding origin was audio-only	✔	✔	×	×
DeviceId	Unique device ID of the viewer	✔	✔	✔	✔
RemoteAddress	IP address of the viewer	✔	✔	✔	✔
Continent	Continent of the viewer	✔	✔	✔	✔
Country	Country of the viewer	✔	✔	✔	✔
State	State of the viewer	✔	✔	✔	✔
City	City of the viewer	✔	✔	✔	✔
PostalCode	Postal code of the viewer	✔	✔	✔	✔
UserAgent	User agent of the viewer	✔	✔	✔	✔
Tags	Tags on the viewing stream	✔	✔	✔	✔
NumberOfRequests	Total number of HTTP requests made by the viewer within the report period	×	×	✔	✔

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 905
Content-Disposition: attachment; filename="20200204T171148Z-START20200101T000000Z-END20200201T000000Z-RealTime-RWYkT1.csv"

ReportTimestamp,PeriodStartTimestamp,PeriodEndTimestamp,ApplicationId,ChannelAlias,ChannelId,OriginStreamId,OriginRegion,OriginFramesPerSecond,OriginAudioQuality,OriginVideoQuality,OriginTags,TotalBytes,ViewedMinutesDuringPeriod,ViewedMinutesTotal,StartTimestamp,EndTimestamp,StartedDuringPeriod,EndedDuringPeriod,StreamId,Region,FramesPerSecond,AudioQuality,VideoQuality,DeviceId,RemoteAddress,UserAgent,Tags
2020-02-04T17:11:49.734Z,2020-01-01T00:00:00.000Z,2020-02-01T00:00:00.000Z,applicationId,test,europe-west#applicationId#test.123456,europe-west#europe-west1-b.98iO2zP0.20190102.PUFMxKEZ,europe-west,30.01,,hd,“”,52130,4,4,2020-01-02T13:38:58.114Z,2020-01-02T13:42:49.042Z,TRUE,TRUE,europe-west#europe-west1-b.98iO2zP0.20190102.PoohNQEi,europe-west,30.00,,hd,64dabda4d6fae4ac0926290c6851ff8586e0cd9f58067c0ee0013c6a73060dd1,1.2.3.4,Mozilla/5.0 (Windows NT 6.1; Trident/7.0; rv:11.0) like Gecko,“”

curl: Saved to filename '20200204T171148Z-START20200101T000000Z-END20200201T000000Z-RealTime-RWYkT1.csv'

If the request fails, the platform will return a failed response that contains a “status” field. The HTTP status code is set according to the “status” field.

HTTP/1.1 400 Bad request
Content-Type: application/json; charset=utf-8
Content-Length: 37

{"status":"excessive-report-interval"}

$ cat viewing
{
   "status":"excessive-report-interval"
}

Viewing report API Response fields

Field	Description
status	See status codes below

Viewing report API Status Codes

HTTP	Status	Retry	Description
200 OK	ok	never	Report was successfully created.
400 Bad Request	<varies>	never	Indicates an issue with the request.
400 Bad Request	excessive-report-interval	never	The interval for the report exceed 1 year.
400 Bad Request	period-start-outside-supported-window	never	The year of the start of period is more than 1 year before the current year.
400 Bad Request	period-end-must-be-in-past	never	The end of period is in future.
400 Bad Request	period-end-must-be-after-start	never	The end of period is less than or equal to the start of the period.
400 Bad Request	unsupported	never	The parameter combination is not supported.
401 Unauthorized	unauthorized	never	The streaming platform was not able to authorize the provided credentials.
408 Request Timeout	request-timeout	once immediately, then exponential backoff	Request timed out likely due to temporary resource or network conditions. Please try again.
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.

Generate a Fork History Report

This API retrieves history of fork-channel API calls.

In order to be able to generate reports, your account needs to be provisioned accordingly. Please contact your primary Phenix technical support contact if you wish to use reporting.

Request

Send a PUT request to pcast/reporting/fork/history endpoint as shown:

PUT pcast/reporting/fork/history HTTP/1.1
Host: pcast.phenixrts.com
Accept: application/json
Content-Type: application/json
Content-Length: 158
Authorization: Basic YXBwbGljYXRpb25JZDpzZWNyZXQ=

{
    "forkHistoryReport": {
        "applicationIds": ["example.com"],
        "start": "2020-01-01T00:00:00Z",
        "end": "2020-01-02T00:00:00Z"
    }
}

$ curl https://pcast.phenixrts.com/pcast/reporting/fork/history \
-u <applicationId>:<secret> \
-H "Accept: text/csv" \
-H "Content-Type: application/json" \
-X PUT \
-d '{
        "forkHistoryReport": {
            "applicationIds": ["example.com"],
            "start": "2020-01-01T00:00:00Z",
            "end": "2020-01-02T00:00:00Z"
        }
    }'
--remote-name
--remote-header-name

Request Headers

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

Request Fields

Field	Description
forkHistoryReport (required)	See ForkHistoryReport object below

ForkHistoryReport Object

Field	Description
start (required)	The report start time. Either an RFC3339 timestamp string or an integer of UNIX epoch time in milliseconds.
end (required)	The report end time. Either an RFC3339 timestamp string or an integer of UNIX epoch time in milliseconds.
applicationIds (optional)	Array of applications IDs to report for. By default, it will report fork requests for the application ID from credentials. A record is selected as long as at least one of the target or destination channel belongs to the supplied application ID.
sourceChannelIds (optional)	Array of source channel IDs to report for.
destinationChannelIds (optional)	Array of destination channel IDs to report for.

Note: All filter conditions are cumulative.

Response

The response is in CSV format.

Report Response Fields

Column	Description
Timestamp	The time at which an fork API call is made.
ApplicationId	The application ID that the request belongs to.
SourceId	The ID of the room that was forked from.
DestinationId	The ID of the room that was forked to.
RequestMethod	The HTTP request method of the API call.
RequestURL	The URL of the request.
RequestSize	The size of the request.
Status	The status code of the request.
ResponseSize	The size of the response.
UserAgent	The useragent from which the request was sent.
RemoteAddress	The remote address from which the request was sent.

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 85
Content-Disposition: attachment; filename="20200204T171148Z-START20200101T000000Z-END20200102T000000Z-ForkHistory-RWYkT1.csv"

Timestamp,ApplicationId,SourceId,DestinationId,RequestMethod,RequestURL,RequestSize,Status,ResponseSize,UserAgent,RemoteAddress
2020-01-01 03:10:00,example.com,us-east#example.com#2,uk-southeast#example.com#1,PUT,https://pcast.phenixrts.com/pcast/channel/uk-southeast#example.com#1/fork/us-east#example.com#2,465,200,978,okhttp/3.12.1,111.22.333.444
2020-01-02 03:12:00,example.com,us-east#example.com#4,uk-southeast#example.com#3,PUT,https://pcast.phenixrts.com/pcast/channel/uk-southeast#example.com#3/fork/us-east#example.com#4,482,200,938,okhttp/3.12.1,555.66.777.888

curl: Saved to filename '20200204T171148Z-START20200101T000000Z-END20200102T000000Z-ForkHistory-RWYkT1.csv'

If the request fails, the platform will return a failed response that contains a “status” field. The HTTP status code is set according to the “status” field.

HTTP/1.1 400 Bad request
Content-Type: application/json; charset=utf-8
Content-Length: 37

{"status":"excessive-report-interval"}

$ cat history
{
   "status":"excessive-report-interval"
}

Fork History Report API Response Fields

Field	Description
status	See status codes below

Fork History Report API Status Codes

HTTP	Status	Retry	Description
200 OK	ok	never	Report was successfully created.
400 Bad Request	<varies>	never	Indicates an issue with the request.
400 Bad Request	excessive-report-interval	never	The interval for the report exceed 1 day.
400 Bad Request	period-start-outside-supported-window	never	The year of the start of period is more than 1 year before the current year.
400 Bad Request	period-end-must-be-in-past	never	The end of period is in future.
400 Bad Request	period-end-must-be-after-start	never	The end of period is less than or equal to the start of the period.
400 Bad Request	unsupported	never	The parameter combination is not supported.
401 Unauthorized	unauthorized	never	The streaming platform was not able to authorize the provided credentials.
408 Request Timeout	request-timeout	once immediately, then exponential backoff	Request timed out likely due to temporary resource or network conditions. Please try again.
413 Payload Too Large	maximal-result-size-exceeded	never	The size of the result exceeds the maximum allowed (10GB).
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.

Generate an Ingest Report

This API generates an ingest report for the given interval.

In order to be able to generate reports, your account needs to be provisioned accordingly. Please contact your primary Phenix technical support contact if you wish to use reporting.

Request

Send a PUT request to pcast/ingest/buffer endpoint as shown:

PUT pcast/ingest/buffer HTTP/1.1
Host: pcast.phenixrts.com
Accept: application/json
Content-Type: application/json
Content-Length: 174
Authorization: Basic YXBwbGljYXRpb25JZDpzZWNyZXQ=

{
    "ingestReport": {
        "kind": "BufferUnderrun",
        "applicationIds": ["example.com"],
        "start": "2020-01-01T00:00:00Z",
        "end": "2020-01-02T00:00:00Z"
    }
}

$ curl https://pcast.phenixrts.com/pcast/ingest/buffer \
-u <applicationId>:<secret> \
-H "Accept: text/csv" \
-H "Content-Type: application/json" \
-X PUT \
-d '{
        "ingestReport": {
            "kind": "BufferUnderrun",
            "applicationIds": ["example.com"],
            "start": "2020-01-01T00:00:00Z",
            "end": "2020-01-02T00:00:00Z"
        }
    }'
--remote-name
--remote-header-name

Request Headers

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

Request Fields

Field	Description
ingestReport (required)	See IngestReport object below

IngestReport Object

Field	Description
kind (required)	Kind of ingest report to generate.
applicationIds (optional)	Array of applications IDs to report for. By default, it will report ingest for the application ID from credentials.
streamIds (optional)	Array of stream IDs to report for. Limits the report to just these streams.
channelIds (optional)	Array of channel IDs to report for. Limits the report to just these channels IDs.
channelAliases (optional)	Array of channel aliases to report for. Limits the report to just these channel aliases.
ingestIds (optional)	Array of ingest IDs to report for. Limits the report to just these ingest IDs.
start (required)	The report start time. Either an RFC3339 timestamp string or an integer of UNIX epoch time in milliseconds.
end (required)	The report end time. Either an RFC3339 timestamp string or an integer of UNIX epoch time in milliseconds.

Note: All filter conditions are cumulative.

IngestReport Kinds

Field	Description
BufferUnderrun	Report for ingest buffer underrrun.

Response

The response is in CSV format.

Report Response Fields

Column	Description	BufferUnderrun
ApplicationId	Application ID of the stream	✔
ChannelAlias	Channel alias of the stream	✔
ChannelId	Channel ID of the stream	✔
StreamId	Stream ID of the publisher	✔
IngestId	Ingest ID of the publisher	✔
MediaType	Media type of the publisher	✔
Ssrc	Ssrc of the publisher	✔
StartOfUnderrun	Timestamp at which the ingest buffer underrun started	✔
EndOfUnderrun	Timestamp at which the ingest buffer underrun ended	✔
DurationMillisecond	The duration of the ingest event in milliseconds	✔

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 85
Content-Disposition: attachment; filename="20200204T171148Z-START20200101T000000Z-END20200102T000000Z-BufferUnderrun-RWYkT1.csv"

ApplicationId,ChannelAlias,ChannelId,StreamId,IngestId,MediaType,Ssrc,StartOfUnderrun,EndOfUnderrun,DurationMillisecond
example.com,MT_2audio,us-northeast#demo#mt2Audio.8sV13fIRnn4D,asia-east#asia-east1-b.4O506ci8.20200601.PSfVsDhh,asia-east#asia-east1-b.4O506ci8.20200601.ItnIMcjA,audio,4155586604,2020-01-01T20:16:38.294Z,2020-01-01T20:16:38.378Z,84
example.com,MT_2audio,us-northeast#demo#mt2Audio.8sV13fIRnn4D,asia-east#asia-east1-b.4O506ci8.20200601.PSfVsDhh,asia-east#asia-east1-b.4O506ci8.20200601.ItnIMcjA,audio,4155586604,2020-01-01T20:16:38.922Z,2020-01-01T20:16:39.007Z,85

curl: Saved to filename '20200204T171148Z-START20200101T000000Z-END20200102T000000Z-BufferUnderrun-RWYkT1.csv'

If the request fails, the platform will return a failed response that contains a “status” field. The HTTP status code is set according to the “status” field.

HTTP/1.1 400 Bad request
Content-Type: application/json; charset=utf-8
Content-Length: 37

{"status":"excessive-report-interval"}

$ cat ingest
{
   "status":"excessive-report-interval"
}

Ingest Report API Response Fields

Field	Description
status	See status codes below

Ingest Report API Status Codes

HTTP	Status	Retry	Description
200 OK	ok	never	Report was successfully created.
400 Bad Request	<varies>	never	Indicates an issue with the request.
400 Bad Request	excessive-report-interval	never	The interval for the report exceed 1 day.
400 Bad Request	period-start-outside-supported-window	never	The year of the start of period is more than 1 year before the current year.
400 Bad Request	period-end-must-be-in-past	never	The end of period is in future.
400 Bad Request	period-end-must-be-after-start	never	The end of period is less than or equal to the start of the period.
400 Bad Request	unsupported	never	The parameter combination is not supported.
401 Unauthorized	unauthorized	never	The streaming platform was not able to authorize the provided credentials.
408 Request Timeout	request-timeout	once immediately, then exponential backoff	Request timed out likely due to temporary resource or network conditions. Please try again.
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.

Generate a Network Throughput Report

This API generates a network throughput report for the given interval.

In order to be able to generate reports, your account needs to be provisioned accordingly. Please contact your primary Phenix technical support contact if you wish to use reporting.

Request

Send a PUT request to pcast/network/throughput endpoint as shown:

PUT pcast/network/throughput HTTP/1.1
Host: pcast.phenixrts.com
Accept: application/json
Content-Type: application/json
Content-Length: 185
Authorization: Basic YXBwbGljYXRpb25JZDpzZWNyZXQ=

{
    "networkReport": {
        "applicationIds": ["example.com"],
        "start": "2021-01-01T00:00:00Z",
        "end": "2021-01-02T00:00:00Z"
    }
}

$ curl https://pcast.phenixrts.com/pcast/network/throughput \
-u <applicationId>:<secret> \
-H "Accept: text/csv" \
-H "Content-Type: application/json" \
-X PUT \
-d '{
        "networkReport": {
            "applicationIds": ["example.com"],
            "start": "2021-01-01T00:00:00Z",
            "end": "2021-01-02T00:00:00Z"
        }
    }'
--remote-name
--remote-header-name

Request Headers

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

Request Fields

Field	Description
networkReport (required)	See NetworkReport object below

NetworkReport Object

Field	Description
applicationIds (optional)	Array of applications IDs to report for. By default, it will report network for the application ID from credentials.
streamIds (optional)	Array of stream IDs to report for. Limits the report to just these streams.
channelIds (optional)	Array of channel IDs to report for. Limits the report to just these channels IDs.
channelAliases (optional)	Array of channel aliases to report for. Limits the report to just these channel aliases.
roomIds (optional)	Array of room IDs to report for. Limits the report to just these rooms.
roomAliases (optional)	Array of room aliases to report for. Limits the report to just these rooms.
start (required)	The report start time. Either an RFC3339 timestamp string or an integer of UNIX epoch time in milliseconds.
end (required)	The report end time. Either an RFC3339 timestamp string or an integer of UNIX epoch time in milliseconds.

Note: All filter conditions are cumulative.

Response

The response is in CSV format.

Report Response Fields

Column	Description	Throughput
TimeBucket	Aggregated time bucket (in invervals of SECONDS)	✔
MinimalTimestamp	Minimal timestamp window of normalized throughput	✔
MaximalTimestamp	Maximal timestamp window of normalized throughput	✔
Kind	Kind/Media type of the stream	✔
NumberOfSsrc	Total number of Synchronization Source(s) in TimeBucket	✔
NumberOfStreams	Total number of Stream(s) in TimeBucket	✔
MediaBitsPerSecondThroughput	Number of payload bits sent as part of Media packets in TimeBucket	✔
FecBitsPerSecondThroughput	Number of payload bits sent as part of FEC packets in TimeBucket	✔
RtpBitsPerSecondThroughput	Number of payload bits sent as part of RTP packets in TimeBucket	✔

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 1604
Content-Disposition: attachment; filename="20210915T230840Z-START20210903T173000Z-END20210903T180000Z-Throughput-eTe4HH.csv"

TimeBucket,MinimalTimestamp,MaximalTimestamp,Kind,NumberOfSsrc,NumberOfStreams,MediaBitsPerSecondThroughput,FecBitsPerSecondThroughput,RtpBitsPerSecondThroughput
2021-09-03 17:45:35 UTC,2021-09-03 17:45:41.775 UTC,2021-09-03 17:45:41.775 UTC,audio,1,1,29116,,43260
2021-09-03 17:45:36 UTC,2021-09-03 17:45:41.775 UTC,2021-09-03 17:45:41.775 UTC,audio,1,1,29116,,43260
2021-09-03 17:45:37 UTC,2021-09-03 17:45:41.775 UTC,2021-09-03 17:45:41.775 UTC,audio,1,1,29116,,43260
2021-09-03 17:45:38 UTC,2021-09-03 17:45:41.775 UTC,2021-09-03 17:45:41.775 UTC,audio,1,1,29116,,43260
2021-09-03 17:45:39 UTC,2021-09-03 17:45:41.775 UTC,2021-09-03 17:45:41.775 UTC,audio,1,1,29116,,43260
2021-09-03 17:45:40 UTC,2021-09-03 17:45:41.775 UTC,2021-09-03 17:45:41.775 UTC,audio,1,1,29116,,43260
2021-09-03 17:45:41 UTC,2021-09-03 17:45:41.775 UTC,2021-09-03 17:45:41.775 UTC,audio,1,1,29116,,43260
2021-09-03 17:45:35 UTC,2021-09-03 17:45:41.773 UTC,2021-09-03 17:45:41.773 UTC,video,1,1,51600,,59784
2021-09-03 17:45:36 UTC,2021-09-03 17:45:41.773 UTC,2021-09-03 17:45:41.773 UTC,video,1,1,51600,,59784
2021-09-03 17:45:37 UTC,2021-09-03 17:45:41.773 UTC,2021-09-03 17:45:41.773 UTC,video,1,1,51600,,59784
2021-09-03 17:45:38 UTC,2021-09-03 17:45:41.773 UTC,2021-09-03 17:45:41.773 UTC,video,1,1,51600,,59784
2021-09-03 17:45:39 UTC,2021-09-03 17:45:41.773 UTC,2021-09-03 17:45:41.773 UTC,video,1,1,51600,,59784
2021-09-03 17:45:40 UTC,2021-09-03 17:45:41.773 UTC,2021-09-03 17:45:41.773 UTC,video,1,1,51600,,59784
2021-09-03 17:45:41 UTC,2021-09-03 17:45:41.773 UTC,2021-09-03 17:45:41.773 UTC,video,1,1,51600,,59784

curl: Saved to filename '20210915T230840Z-START20210903T173000Z-END20210903T180000Z-Throughput-eTe4HH.csv'

If the request fails, the platform will return a failed response that contains a “status” field. The HTTP status code is set according to the “status” field.

HTTP/1.1 400 Bad request
Content-Type: application/json; charset=utf-8
Content-Length: 39

{"status":"excessive-report-interval"}

$ cat network
{
   "status":"excessive-report-interval"
}

Network Throughput Report API Response Fields

Field	Description
status	See status codes below

Network Throughput Report API Status Codes

HTTP	Status	Retry	Description
200 OK	ok	never	Report was successfully created.
400 Bad Request	<varies>	never	Indicates an issue with the request.
400 Bad Request	excessive-report-interval	never	The interval for the report exceed 1 day.
400 Bad Request	period-start-outside-supported-window	never	The year of the start of period is more than 1 year before the current year.
400 Bad Request	period-end-must-be-in-past	never	The end of period is in future.
400 Bad Request	period-end-must-be-after-start	never	The end of period is less than or equal to the start of the period.
400 Bad Request	unsupported	never	The parameter combination is not supported.
401 Unauthorized	unauthorized	never	The streaming platform was not able to authorize the provided credentials.
408 Request Timeout	request-timeout	once immediately, then exponential backoff	Request timed out likely due to temporary resource or network conditions. Please try again.
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.

Generate a Network Packet Loss Rate Report

This API generates a network packet loss rate report for the given interval.

In order to be able to generate reports, your account needs to be provisioned accordingly. Please contact your primary Phenix technical support contact if you wish to use reporting.

Request

Send a PUT request to pcast/network/packet-loss-rate endpoint as shown:

PUT pcast/network/packet-loss-rate HTTP/1.1
Host: pcast.phenixrts.com
Accept: application/json
Content-Type: application/json
Content-Length: 185
Authorization: Basic YXBwbGljYXRpb25JZDpzZWNyZXQ=

{
    "networkReport": {
        "applicationIds": ["example.com"],
        "start": "2021-01-01T00:00:00Z",
        "end": "2021-01-02T00:00:00Z"
    }
}

$ curl https://pcast.phenixrts.com/pcast/network/packet-loss-rate \
-u <applicationId>:<secret> \
-H "Accept: text/csv" \
-H "Content-Type: application/json" \
-X PUT \
-d '{
        "networkReport": {
            "applicationIds": ["test"],
            "start": "2022-04-05T10:00:00Z",
            "end": "2022-04-05T18:10:00Z",
            "streamIds": ["local#standalone.WHFHRnl6.20220405.PS3S3QsW"] 
        }
    }'
--remote-name
--remote-header-name

Request Headers

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

Request Fields

Field	Description
networkReport (required)	See NetworkReport object below

NetworkReport Object

Field	Description
applicationIds (optional)	Array of applications IDs to report for. By default, it will report network for the application ID from credentials.
streamIds (optional)	Array of stream IDs to report for. Limits the report to just these streams.
channelIds (optional)	Array of channel IDs to report for. Limits the report to just these channels IDs.
channelAliases (optional)	Array of channel aliases to report for. Limits the report to just these channel aliases.
roomIds (optional)	Array of room IDs to report for. Limits the report to just these rooms.
roomAliases (optional)	Array of room aliases to report for. Limits the report to just these rooms.
start (required)	The report start time. Either an RFC3339 timestamp string or an integer of UNIX epoch time in milliseconds.
end (required)	The report end time. Either an RFC3339 timestamp string or an integer of UNIX epoch time in milliseconds.

Note: All filter conditions are cumulative.

Response

The response is in CSV format.

Report Response Fields

Column	Description
TimeBucket	Aggregated time bucket (in invervals of SECONDS)	✔
MinimalTimestamp	Minimal timestamp window of normalized PacketLossRate	✔
MaximalTimestamp	Maximal timestamp window of PacketLossRate	✔
Kind	Kind/Media type of the stream	✔
NumberOfSsrc	Total number of Synchronization Source(s) in TimeBucket	✔
NumberOfStreams	Total number of Stream(s) in TimeBucket	✔
PacketLossRate	Average Packet loss rate over set of filtered SSRC streams in TimeBucket	✔

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 1604
Content-Disposition: attachment; filename="20220422T110526Z-START20220405T100000Z-END20220405T181000Z-PacketLossRate-JdxuIr.csv"

TimeBucket,MinimalTimestamp,MaximalTimestamp,Kind,NumberOfSsrc,NumberOfStreams,PacketLossRate
2022-04-05 13:40:36 UTC,2022-04-05 13:40:36.498 UTC,2022-04-05 13:40:36.498 UTC,audio,1,1,0.5
2022-04-05 13:40:37 UTC,2022-04-05 13:40:37.501 UTC,2022-04-05 13:40:37.501 UTC,audio,1,1,0.2578125
2022-04-05 13:40:38 UTC,2022-04-05 13:40:38.502 UTC,2022-04-05 13:40:38.899 UTC,audio,1,1,0.275390625
2022-04-05 13:40:39 UTC,,,audio,1,1,
2022-04-05 13:40:40 UTC,2022-04-05 13:40:40.418 UTC,2022-04-05 13:40:40.902 UTC,audio,1,1,0.376953125
2022-04-05 13:40:41 UTC,2022-04-05 13:40:41.903 UTC,2022-04-05 13:40:41.903 UTC,audio,1,1,0.42578125
2022-04-05 13:40:42 UTC,,,audio,1,1,
2022-04-05 13:40:43 UTC,2022-04-05 13:40:43.42 UTC,2022-04-05 13:40:43.42 UTC,audio,1,1,0.31640625
2022-04-05 13:40:44 UTC,2022-04-05 13:40:44.42 UTC,2022-04-05 13:40:44.42 UTC,audio,1,1,0.40625
2022-04-05 13:40:45 UTC,2022-04-05 13:40:45.421 UTC,2022-04-05 13:40:45.421 UTC,audio,1,1,0.2578125
2022-04-05 13:40:46 UTC,2022-04-05 13:40:46.899 UTC,2022-04-05 13:40:46.899 UTC,audio,1,1,0.30859375
2022-04-05 13:40:47 UTC,,,audio,1,1,
2022-04-05 13:40:48 UTC,2022-04-05 13:40:48.418 UTC,2022-04-05 13:40:48.418 UTC,audio,1,1,0.27734375
2022-04-05 13:40:49 UTC,2022-04-05 13:40:49.419 UTC,2022-04-05 13:40:49.419 UTC,audio,1,1,0.27734375
2022-04-05 13:40:50 UTC,,,audio,1,1,
2022-04-05 13:40:51 UTC,2022-04-05 13:40:51.423 UTC,2022-04-05 13:40:51.423 UTC,audio,1,1,0.5
2022-04-05 13:40:52 UTC,2022-04-05 13:40:52.419 UTC,2022-04-05 13:40:52.419 UTC,audio,1,1,0.1171875
2022-04-05 13:40:53 UTC,2022-04-05 13:40:53.422 UTC,2022-04-05 13:40:53.422 UTC,audio,1,1,0.1171875
2022-04-05 13:40:54 UTC,2022-04-05 13:40:54.421 UTC,2022-04-05 13:40:54.421 UTC,audio,1,1,0.4140625
2022-04-05 13:40:55 UTC,2022-04-05 13:40:55.419 UTC,2022-04-05 13:40:55.419 UTC,audio,1,1,0.20703125
2022-04-05 13:40:56 UTC,2022-04-05 13:40:56.422 UTC,2022-04-05 13:40:56.422 UTC,audio,1,1,0.23828125
2022-04-05 13:40:57 UTC,,,audio,1,1,
2022-04-05 13:40:58 UTC,2022-04-05 13:40:58.418 UTC,2022-04-05 13:40:58.418 UTC,audio,1,1,0.25
2022-04-05 13:40:59 UTC,2022-04-05 13:40:59.422 UTC,2022-04-05 13:40:59.9 UTC,audio,1,1,0.2578125
2022-04-05 13:41:00 UTC,,,audio,1,1,
2022-04-05 13:41:01 UTC,2022-04-05 13:41:01.42 UTC,2022-04-05 13:41:01.42 UTC,audio,1,1,0.3984375
2022-04-05 13:41:02 UTC,2022-04-05 13:41:02.421 UTC,2022-04-05 13:41:02.421 UTC,audio,1,1,0.31640625
2022-04-05 13:41:03 UTC,2022-04-05 13:41:03.422 UTC,2022-04-05 13:41:03.422 UTC,audio,1,1,0.28515625
2022-04-05 13:41:04 UTC,2022-04-05 13:41:04.421 UTC,2022-04-05 13:41:04.421 UTC,audio,1,1,0.3515625
2022-04-05 13:41:05 UTC,2022-04-05 13:41:05.42 UTC,2022-04-05 13:41:05.42 UTC,audio,1,1,0.30078125
2022-04-05 13:41:06 UTC,2022-04-05 13:41:06.423 UTC,2022-04-05 13:41:06.423 UTC,audio,1,1,0.359375
2022-04-05 13:41:07 UTC,2022-04-05 13:41:07.423 UTC,2022-04-05 13:41:07.423 UTC,audio,1,1,0.33203125
2022-04-05 13:41:08 UTC,2022-04-05 13:41:08.903 UTC,2022-04-05 13:41:08.903 UTC,audio,1,1,0.2734375
2022-04-05 13:41:09 UTC,,,audio,1,1,
2022-04-05 13:41:10 UTC,2022-04-05 13:41:10.423 UTC,2022-04-05 13:41:10.423 UTC,audio,1,1,0.28125
2022-04-05 13:41:11 UTC,2022-04-05 13:41:11.422 UTC,2022-04-05 13:41:11.422 UTC,audio,1,1,0.2578125
2022-04-05 13:41:12 UTC,2022-04-05 13:41:12.422 UTC,2022-04-05 13:41:12.422 UTC,audio,1,1,0.18359375
2022-04-05 13:41:13 UTC,,,audio,1,1,
2022-04-05 13:41:14 UTC,2022-04-05 13:41:14.421 UTC,2022-04-05 13:41:14.421 UTC,audio,1,1,0.27734375
2022-04-05 13:41:15 UTC,2022-04-05 13:41:15.422 UTC,2022-04-05 13:41:15.422 UTC,audio,1,1,0.375
2022-04-05 13:41:16 UTC,2022-04-05 13:41:16.422 UTC,2022-04-05 13:41:16.903 UTC,audio,1,1,0.265625
2022-04-05 13:41:17 UTC,,,audio,1,1,
2022-04-05 13:41:18 UTC,2022-04-05 13:41:18.423 UTC,2022-04-05 13:41:18.903 UTC,audio,1,1,0.330078125
2022-04-05 13:41:19 UTC,2022-04-05 13:41:19.903 UTC,2022-04-05 13:41:19.903 UTC,audio,1,1,0.15625
2022-04-05 13:41:20 UTC,,,audio,1,1,
2022-04-05 13:41:21 UTC,2022-04-05 13:41:21.422 UTC,2022-04-05 13:41:21.422 UTC,audio,1,1,0.1640625
2022-04-05 13:41:22 UTC,2022-04-05 13:41:22.423 UTC,2022-04-05 13:41:22.904 UTC,audio,1,1,0.240234375
2022-04-05 13:41:23 UTC,2022-04-05 13:41:23.903 UTC,2022-04-05 13:41:23.903 UTC,audio,1,1,0.2578125
2022-04-05 13:41:24 UTC,2022-04-05 13:41:24.903 UTC,2022-04-05 13:41:24.903 UTC,audio,1,1,0.296875
2022-04-05 13:41:25 UTC,,,audio,1,1,
2022-04-05 13:41:26 UTC,2022-04-05 13:41:26.422 UTC,2022-04-05 13:41:26.422 UTC,audio,1,1,0.21484375
2022-04-05 13:41:27 UTC,,,audio,1,1,
2022-04-05 13:41:28 UTC,,,audio,1,1,
2022-04-05 13:41:29 UTC,,,audio,1,1,
2022-04-05 13:41:30 UTC,2022-04-05 13:41:30.419 UTC,2022-04-05 13:41:30.419 UTC,audio,1,1,0.27734375
2022-04-05 13:41:31 UTC,2022-04-05 13:41:31.418 UTC,2022-04-05 13:41:31.903 UTC,audio,1,1,0.234375
2022-04-05 13:41:32 UTC,,,audio,1,1,
2022-04-05 13:41:33 UTC,2022-04-05 13:41:33.422 UTC,2022-04-05 13:41:33.903 UTC,audio,1,1,0.279296875
2022-04-05 13:41:34 UTC,,,audio,1,1,
2022-04-05 13:41:35 UTC,2022-04-05 13:41:35.422 UTC,2022-04-05 13:41:35.899 UTC,audio,1,1,0.2578125
2022-04-05 13:40:37 UTC,2022-04-05 13:40:37.399 UTC,2022-04-05 13:40:37.399 UTC,video,1,1,0.10546875
2022-04-05 13:40:38 UTC,2022-04-05 13:40:38.65 UTC,2022-04-05 13:40:38.65 UTC,video,1,1,0.12890625
2022-04-05 13:40:39 UTC,2022-04-05 13:40:39.497 UTC,2022-04-05 13:40:39.497 UTC,video,1,1,0
2022-04-05 13:40:40 UTC,2022-04-05 13:40:40.538 UTC,2022-04-05 13:40:40.538 UTC,video,1,1,0.046875
2022-04-05 13:40:41 UTC,2022-04-05 13:40:41.523 UTC,2022-04-05 13:40:41.523 UTC,video,1,1,0.12109375
2022-04-05 13:40:42 UTC,2022-04-05 13:40:42.491 UTC,2022-04-05 13:40:42.491 UTC,video,1,1,0.0859375
2022-04-05 13:40:43 UTC,2022-04-05 13:40:43.534 UTC,2022-04-05 13:40:43.534 UTC,video,1,1,0.078125
2022-04-05 13:40:44 UTC,2022-04-05 13:40:44.65 UTC,2022-04-05 13:40:44.65 UTC,video,1,1,0.07421875
2022-04-05 13:40:45 UTC,2022-04-05 13:40:45.618 UTC,2022-04-05 13:40:45.618 UTC,video,1,1,0.05078125
2022-04-05 13:40:46 UTC,2022-04-05 13:40:46.623 UTC,2022-04-05 13:40:46.623 UTC,video,1,1,0.10546875
2022-04-05 13:40:47 UTC,2022-04-05 13:40:47.609 UTC,2022-04-05 13:40:47.609 UTC,video,1,1,0.08203125
2022-04-05 13:40:48 UTC,2022-04-05 13:40:48.682 UTC,2022-04-05 13:40:48.682 UTC,video,1,1,0.0546875
2022-04-05 13:40:49 UTC,2022-04-05 13:40:49.137 UTC,2022-04-05 13:40:49.137 UTC,video,1,1,0.0859375
2022-04-05 13:40:50 UTC,2022-04-05 13:40:50.185 UTC,2022-04-05 13:40:50.185 UTC,video,1,1,0.0859375
2022-04-05 13:40:51 UTC,2022-04-05 13:40:51.656 UTC,2022-04-05 13:40:51.656 UTC,video,1,1,0.0546875
2022-04-05 13:40:52 UTC,2022-04-05 13:40:52.655 UTC,2022-04-05 13:40:52.655 UTC,video,1,1,0.0859375
2022-04-05 13:40:53 UTC,2022-04-05 13:40:53.695 UTC,2022-04-05 13:40:53.695 UTC,video,1,1,0.06640625
2022-04-05 13:40:54 UTC,2022-04-05 13:40:54.215 UTC,2022-04-05 13:40:54.215 UTC,video,1,1,0.0625
2022-04-05 13:40:55 UTC,2022-04-05 13:40:55.246 UTC,2022-04-05 13:40:55.246 UTC,video,1,1,0.0625
2022-04-05 13:40:56 UTC,2022-04-05 13:40:56.275 UTC,2022-04-05 13:40:56.275 UTC,video,1,1,0.1015625
2022-04-05 13:40:57 UTC,2022-04-05 13:40:57.309 UTC,2022-04-05 13:40:57.309 UTC,video,1,1,0.06640625
2022-04-05 13:40:58 UTC,2022-04-05 13:40:58.39 UTC,2022-04-05 13:40:58.92 UTC,video,1,1,0.0546875
2022-04-05 13:40:59 UTC,2022-04-05 13:40:59.89 UTC,2022-04-05 13:40:59.89 UTC,video,1,1,0.04296875
2022-04-05 13:41:00 UTC,,,video,1,1,
2022-04-05 13:41:01 UTC,2022-04-05 13:41:01.46 UTC,2022-04-05 13:41:01.46 UTC,video,1,1,0.0625
2022-04-05 13:41:02 UTC,2022-04-05 13:41:02.46 UTC,2022-04-05 13:41:02.46 UTC,video,1,1,0.05078125
2022-04-05 13:41:03 UTC,2022-04-05 13:41:03.532 UTC,2022-04-05 13:41:03.532 UTC,video,1,1,0.08203125
2022-04-05 13:41:04 UTC,2022-04-05 13:41:04.56 UTC,2022-04-05 13:41:04.56 UTC,video,1,1,0.05859375
2022-04-05 13:41:05 UTC,2022-04-05 13:41:05.524 UTC,2022-04-05 13:41:05.524 UTC,video,1,1,0.10546875
2022-04-05 13:41:06 UTC,2022-04-05 13:41:06.56 UTC,2022-04-05 13:41:06.56 UTC,video,1,1,0.04296875
2022-04-05 13:41:07 UTC,2022-04-05 13:41:07.524 UTC,2022-04-05 13:41:07.524 UTC,video,1,1,0.08203125
2022-04-05 13:41:08 UTC,2022-04-05 13:41:08.045 UTC,2022-04-05 13:41:08.987 UTC,video,1,1,0.052734375
2022-04-05 13:41:09 UTC,,,video,1,1,
2022-04-05 13:41:10 UTC,2022-04-05 13:41:10.503 UTC,2022-04-05 13:41:10.503 UTC,video,1,1,0.1171875
2022-04-05 13:41:11 UTC,2022-04-05 13:41:11.085 UTC,2022-04-05 13:41:11.085 UTC,video,1,1,0.0625
2022-04-05 13:41:12 UTC,2022-04-05 13:41:12.649 UTC,2022-04-05 13:41:12.649 UTC,video,1,1,0.0546875
2022-04-05 13:41:13 UTC,2022-04-05 13:41:13.631 UTC,2022-04-05 13:41:13.631 UTC,video,1,1,0.0703125
2022-04-05 13:41:14 UTC,2022-04-05 13:41:14.196 UTC,2022-04-05 13:41:14.196 UTC,video,1,1,0.08203125
2022-04-05 13:41:15 UTC,2022-04-05 13:41:15.739 UTC,2022-04-05 13:41:15.739 UTC,video,1,1,0.02734375
2022-04-05 13:41:16 UTC,2022-04-05 13:41:16.286 UTC,2022-04-05 13:41:16.286 UTC,video,1,1,0.14453125
2022-04-05 13:41:17 UTC,2022-04-05 13:41:17.325 UTC,2022-04-05 13:41:17.777 UTC,video,1,1,0.05078125
2022-04-05 13:41:18 UTC,,,video,1,1,
2022-04-05 13:41:19 UTC,2022-04-05 13:41:19.348 UTC,2022-04-05 13:41:19.841 UTC,video,1,1,0.06640625
2022-04-05 13:41:20 UTC,,,video,1,1,
2022-04-05 13:41:21 UTC,2022-04-05 13:41:21.337 UTC,2022-04-05 13:41:21.337 UTC,video,1,1,0.05859375
2022-04-05 13:41:22 UTC,,,video,1,1,
2022-04-05 13:41:23 UTC,2022-04-05 13:41:23.464 UTC,2022-04-05 13:41:23.464 UTC,video,1,1,0.0546875
2022-04-05 13:41:24 UTC,2022-04-05 13:41:24.053 UTC,2022-04-05 13:41:24.053 UTC,video,1,1,0.0546875
2022-04-05 13:41:25 UTC,2022-04-05 13:41:25.58 UTC,2022-04-05 13:41:25.58 UTC,video,1,1,0.109375
2022-04-05 13:41:26 UTC,2022-04-05 13:41:26.653 UTC,2022-04-05 13:41:26.653 UTC,video,1,1,0.11328125
2022-04-05 13:41:27 UTC,2022-04-05 13:41:27.754 UTC,2022-04-05 13:41:27.754 UTC,video,1,1,0.09765625
2022-04-05 13:41:28 UTC,2022-04-05 13:41:28.684 UTC,2022-04-05 13:41:28.684 UTC,video,1,1,0.07421875
2022-04-05 13:41:29 UTC,2022-04-05 13:41:29.156 UTC,2022-04-05 13:41:29.156 UTC,video,1,1,0.05078125
2022-04-05 13:41:30 UTC,2022-04-05 13:41:30.756 UTC,2022-04-05 13:41:30.756 UTC,video,1,1,0.03515625
2022-04-05 13:41:31 UTC,2022-04-05 13:41:31.684 UTC,2022-04-05 13:41:31.684 UTC,video,1,1,0.0703125
2022-04-05 13:41:32 UTC,2022-04-05 13:41:32.776 UTC,2022-04-05 13:41:32.776 UTC,video,1,1,0.04296875
2022-04-05 13:41:33 UTC,2022-04-05 13:41:33.29 UTC,2022-04-05 13:41:33.29 UTC,video,1,1,0.07421875
2022-04-05 13:41:34 UTC,2022-04-05 13:41:34.782 UTC,2022-04-05 13:41:34.782 UTC,video,1,1,0.08203125
2022-04-05 13:41:35 UTC,2022-04-05 13:41:35.36 UTC,2022-04-05 13:41:35.36 UTC,video,1,1,0.11328125
2022-04-05 13:41:36 UTC,2022-04-05 13:41:36.297 UTC,2022-04-05 13:41:36.297 UTC,video,1,1,0.02734375

curl: Saved to filename '20220407T125518Z-START20220405T100000Z-END20220405T181000Z-PacketLossRate-3VreKW.csv'

If the request fails, the platform will return a failed response that contains a “status” field. The HTTP status code is set according to the “status” field.

HTTP/1.1 400 Bad request
Content-Type: application/json; charset=utf-8
Content-Length: 39

{"status":"excessive-report-interval"}

$ cat network
{
   "status":"excessive-report-interval"
}

Network Packet Loss Rate Report API Response Fields

Field	Description
status	See status codes below

Network Packet Loss Rate Report API Status Codes

HTTP	Status	Retry	Description
200 OK	ok	never	Report was successfully created.
400 Bad Request	<varies>	never	Indicates an issue with the request.
400 Bad Request	excessive-report-interval	never	The interval for the report exceed 1 day.
400 Bad Request	period-start-outside-supported-window	never	The year of the start of period is more than 1 year before the current year.
400 Bad Request	period-end-must-be-in-past	never	The end of period is in future.
400 Bad Request	period-end-must-be-after-start	never	The end of period is less than or equal to the start of the period.
400 Bad Request	unsupported	never	The parameter combination is not supported.
401 Unauthorized	unauthorized	never	The streaming platform was not able to authorize the provided credentials.
408 Request Timeout	request-timeout	once immediately, then exponential backoff	Request timed out likely due to temporary resource or network conditions. Please try again.
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.

Analytics API

APIs for generating analytics reports

Generate a Concurrent Viewing Streams Report

This API generates a concurrent viewing streams report for the given interval.

In order to be able to generate reports, your account needs to be provisioned accordingly. Please contact your primary Phenix technical support contact if you wish to use analytics.

Request

Send a PUT request to pcast/streams/concurrent endpoint as shown:

PUT pcast/streams/concurrent HTTP/1.1
Host: pcast.phenixrts.com
Accept: application/json
Content-Type: application/json
Content-Length: 174
Authorization: Basic YXBwbGljYXRpb25JZDpzZWNyZXQ=

{
    "concurrentViewingStreamsReport": {
        "applicationIds": ["example.com"],
        "start": "2020-01-01T00:00:00Z",
        "end": "2020-01-02T00:00:00Z"
    }
}

$ curl https://pcast.phenixrts.com/pcast/streams/concurrent \
-u <applicationId>:<secret> \
-H "Accept: text/csv" \
-H "Content-Type: application/json" \
-X PUT \
-d '{
        "concurrentViewingStreamsReport": {
            "applicationIds": ["example.com"],
            "start": "2020-01-01T00:00:00Z",
            "end": "2020-01-02T00:00:00Z"
        }
    }'
--remote-name
--remote-header-name

Request Headers

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

Request Fields

Field	Description
concurrentViewingStreamsReport (required)	See ConcurrentViewingStreamsReport object below

ConcurrentViewingStreamsReport Object

Field	Description
applicationIds (optional)	Array of applications IDs to report for. By default, it will report viewing streams for the application ID from credentials.
streamIds (optional)	Array of origin stream IDs to report for. Limits the report to viewing streams of just these origin streams.
channelIds (optional)	Array of channel IDs to report for. Limits the report to just these channel IDs.
channelAliases (optional)	Array of channel aliases to report for. Limits the report to just these channel aliases.
originTags (optional)	Array of origin Tags to report for. Limits the report to viewing streams of only origin streams with these tags.
viewerTags (optional)	Array of viewer Tags to report for. Limist the report to only viewing streams with these tags.
start (required)	The report start time. Either an RFC3339 timestamp string or an integer of UNIX epoch time in milliseconds.
end (required)	The report end time. Either an RFC3339 timestamp string or an integer of UNIX epoch time in milliseconds.

Note: All filter conditions are cumulative.

Response

The response is in CSV format.

Report Response Fields

Column	Description
ApplicationId	Application ID for which number of concurrent viewing streams is counted
Timestamp	The time at which number of concurrent viewing streams is counted
Concurrent	Number of concurrent viewing streams

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 85
Content-Disposition: attachment; filename="20200204T171148Z-START20200101T000000Z-END20200102T000000Z-ConcurrentViewingStreams-RWYkT1.csv"

ApplicationId,Timestamp,Concurrent
example.com,2020-01-01 20:16:38,200
example.com,2020-01-01 20:16:39,15
example.com,2020-01-01 20:16:40,2

curl: Saved to filename '20200204T171148Z-START20200101T000000Z-END20200102T000000Z-ConcurrentViewingStreams-RWYkT1.csv'

If the request fails, the platform will return a failed response that contains a “status” field. The HTTP status code is set according to the “status” field.

HTTP/1.1 400 Bad request
Content-Type: application/json; charset=utf-8
Content-Length: 37

{"status":"excessive-report-interval"}

$ cat concurrent
{
   "status":"excessive-report-interval"
}

Concurrent Viewing Streams Report API Response Fields

Field	Description
status	See status codes below

Concurrent Viewing Streams Report API Status Codes

HTTP	Status	Retry	Description
200 OK	ok	never	Report was successfully created.
400 Bad Request	<varies>	never	Indicates an issue with the request.
400 Bad Request	excessive-report-interval	never	The interval for the report exceed 1 day.
400 Bad Request	period-start-outside-supported-window	never	The year of the start of period is more than 1 year before the current year.
400 Bad Request	period-end-must-be-in-past	never	The end of period is in future.
400 Bad Request	period-end-must-be-after-start	never	The end of period is less than or equal to the start of the period.
400 Bad Request	unsupported	never	The parameter combination is not supported.
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.

Authentication

Authentication is required for working with our HTTP APIs. Currently there are 2 ways of sending credentials in the request.

HTTP Authentication Header

Pass credentials for authentication using the HTTP Authorization request header as shown:

Authorization: <type> <credentials>

Authorization Type

Field	Description
Basic	Use “Basic” authentication scheme

Authorization Credentials

1. Combine the applicationId and the secret with a colon applicationId:secret
2. base64 encoded the resulting string YXBwbGljYXRpb25JZDpzZWNyZXQ=

For example:

POST /pcast/composition HTTP/1.1
Host: pcast.phenixrts.com
Accept: application/json
Content-Type: application/json
Content-Length: 249
Authorization: Basic YXBwbGljYXRpb25JZDpzZWNyZXQ=

$ curl https://pcast.phenixrts.com/pcast/composition \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Content-Length: 249" \
-u applicationId:secret \

HTTP Request Body Authentication (deprecated)

You can pass credentials in the request body as shown:

{
    "credentials": {
        "applicationId": "<applicationId>",
        "secret": "<secret>"
    }
}

Credentials Object

Field	Description
applicationId (required)	Application ID
secret (required)	Appplication secret

Passing the Credentials in request body is deprecated and supported only for backward compatibility. The preferred way of passing the Credentials is through HTTP Authentication Header

RTMP Ingest

Phenix supports ingest via RTMP push directly into a channel.

Push your RTMP feed to rtmp://ingest.phenixrts.com:80/ingest/ using this stream key from the channel API.

The basic RTMP URL looks as follows:

rtmp://ingest.phenixrts.com:80/ingest/{STREAMKEY}

Additional options, such as capabilities and tags, may be provided in the URL separated by semicolons, for example:

rtmp://ingest.phenixrts.com:80/ingest/{STREAMKEY};capabilities=hd,multi-bitrate,prefer-h264;tags=my-awesome-stream-id,my-customer-id

If your system does not allow the inclusion of semicolons in the URL, the | (pipe) can be used instead, for example:

rtmp://ingest.phenixrts.com:80/ingest/{STREAMKEY}|capabilities=hd,multi-bitrate,prefer-h264|tags=my-awesome-stream-id,my-customer-id

RTMP URL Options

Option	Default	Description
capabilities	hd,multi-bitrate	A comma separated list of capabilities for the published stream.
tags		A comma separated list of custom tags.
maxFps	30	[Advanced] Controls the maximal frame rate sampled from the source signal. Support of signals with more than 30 FPS is experimental.
buffer	500	[Advanced] The amount of buffer to use on the ingest side to compensate for network jitter.
prerollSkipDuration	500	[Experimental] Milliseconds to skip at the beginning of the stream.
jitterBuffer	${buffer}	[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.
screenName		[Experimental] The screen name of the channel member representing this ingest. The screen name is automatically chosen to properly enable functionality like HA publishing.

Please note that changing options marked as experimental may alter expected behavior and may have unintended side effects and therefore should only be modified after consultation with the Phenix support staff.

High Availability

The Phenix platform is built with high availability (HA) in mind for all system components from encoding and ingest through to client connections to the platform. The autonomous operation architecture ensures that faults are detected and corrected without any administrative or end-user impacts.

HA Ingest is the ability to send data into multiple redundant data centers over redundant networking connections effectively addresses risks of origin and first mile failures. Thus providing a deployment with complete end-to-end redundancy.

Please contact your primary Phenix technical support contact if you wish to use HA Ingest and for instructions on how to set it up.