NAV Navbar
Phenix logo
Version 2020.0.22
cURL HTTP

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.
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 168
vld 240p Very low definition Publish 350 60 492
ld 360p Low definition Publish 520 60 696
sd 480p Standard definition - default Publish 830 60 1068
hd 720p High definition Publish 1600 60 1992
fhd 1080p Full high definition Publish 3000 60 3672
xhd 1080p Extended high definition Publish 5500 60 6672
uhd 1080p+ Ultra high definition Publish 5500 60 6672

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

{"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","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","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",
         "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",
         "isProtected" : false,
         "isEncrypted" : false,
         "isVariant" : true
         "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
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
isVariant Whether this is a variant playlist
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.

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>"
        },
        "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.isVariant Whether this is a variant playlist
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>"
        },
        "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.isVariant Whether this is a variant playlist
sessionId The session ID of the client this stream belongs to
timestamp The RFC3339 timestamp of when the request was initiated in Zulu time

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.
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.
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.
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”. The default behavior is not touch the stream(s) already publishing to the destination channel. With the “force” option, the stream(s) will be terminated and replaced.

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.
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.
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 Retry Description
200 OK never Number of publishers was successfully reported.
400 Bad Request never Indicates an issue with the request.
404 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 once The system is temporarily overloaded. 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 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 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 once The system is temporarily overloaded. 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.
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.
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.
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.
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.
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.
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.
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.
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”. The default behavior is not touch the stream(s) already publishing to the destination room. With the “force” option, the stream(s) will be terminated and replaced.

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.
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.
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 Retry Description
200 OK never Number of publishers was successfully reported.
400 Bad Request never Indicates an issue with the request.
404 Not Found never Indicates the room 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 once The system is temporarily overloaded. 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 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 never Indicates the room or the manifest was not found.
415 Unsupported Media Type never The room does not support streaming.
4XX never Indicates an issue with the request.
503 Service Unavailable once The system is temporarily overloaded. 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.
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.
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.
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.

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

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
StreamId Stream ID of the publisher
Region Region of the publisher
AudioQuality Audio quality of the publisher
VideoQuality Video quality of the publisher
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
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
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 “Live” capability
VOD Does the publisher have “VOD” capability
RTMP Does the publisher have “RTMP” capability
LiveLite Does the publisher have “LiveLite” capability
VODLite Does the publisher have “VODLite” capability
MBR Does the publisher have “MBR” capability
MBRContribution Does the publisher have “MBRContribution” capability
AudioOnly Does the publisher have “AudioOnly” capability
Tags Tags on the publishing stream
Capabilities Capabilities on the publishing stream
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 85
Content-Disposition: attachment; filename="20200305T161052Z-START20200101T000000Z-END20200201T000000Z-Publishing-fGGvDe.csv"

ReportTimestamp,PeriodStartTimestamp,PeriodEndTimestamp,ApplicationId,ChannelAlias,ChannelId,StreamId,Region,AudioQuality,VideoQuality,PublishedMinutesDuringPeriod,PublishedMinutesTotal,PeakConcurrentViews,TotalViews,StartTimestamp,EndTimestamp,StartedDuringPeriod,EndedDuringPeriod,EndedReason,RemoteAddress,Ingest,Live,VOD,RTMP,LiveLite,VODLite,MBR,MBRContribution,AudioOnly,Tags,Capabilities
2020-03-05T16:10:53.769Z,2020-01-01T00:00:00.000Z,2020-02-01T00:00:00.000Z,example.com,,,asia-south#asia-south1-c.Bqac2GbH.20191203.Vxg6P1AD,asia-south,,sd,44640,,,,2019-12-03T02:57:15.756Z,,FALSE,FALSE,,,,FALSE,FALSE,FALSE,FALSE,FALSE,TRUE,FALSE,FALSE,x-ingest,publish-uri|resilient|monitor-tracks|no-session-stream-events|transcoding={}|sd|multi-bitrate|prefer-h264|origin-shield
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,,,,2019-12-04T12:36:22.476Z,,FALSE,FALSE,,::ffff:52.4.228.150,,FALSE,FALSE,TRUE,FALSE,FALSE,FALSE,FALSE,FALSE,channelId:us-northeast#example.com#channel123456.S1b486elbH4I|Status:STREAMING,sd|detached|rtmp|publish-uri

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

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
OriginAudioQuality Audio quality of origin
OriginVideoQuality Video quality of the origin
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 × ×
AudioQuality Audio quality of the viewing stream × ×
VideoQuality Video quality of the viewing stream × ×
DeviceId 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: 85
Content-Disposition: attachment; filename="20200204T171148Z-START20200101T000000Z-END20200201T000000Z-RealTime-RWYkT1.csv"

ReportTimestamp,PeriodStartTimestamp,PeriodEndTimestamp,ApplicationId,ChannelAlias,ChannelId,OriginStreamId,OriginRegion,OriginAudioQuality,OriginVideoQuality,OriginTags,TotalBytes,ViewedMinutesDuringPeriod,ViewedMinutesTotal,StartTimestamp,EndTimestamp,StartedDuringPeriod,EndedDuringPeriod,StreamId,Region,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,,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,,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
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 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 analytics.

Request

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

PUT pcast/analytics/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/analytics/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 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
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 analytics.

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
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 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
Global 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,Global
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, may be provided in the URL:

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.