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>"]
}'
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,??
Unmapped IPs Even the best geo IP databases will not be able to map all IPs to a country. The special code `??` serves as the country code for any IP that is not mapped and can be used to identify unmapped IPs.
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
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.
Lifetime : Authentication tokens can be used for up to 1 hour. For wildcard tokens, it is recommended that they are generated frequently, e.g. every five minutes. This will provide the highest level of availability in the presence of internet outages.
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>"]
}'
Field
Value
Accept
application/json
Content-Type
application/json
Content-Length
138
Request Fields
Field
Description
applicationId (required)
Your application ID
secret (required)
Your application secret
sessionId (required)
The session ID of the client that you are generating this token for or the wildcard *
enabling any authorized session to use the token
originStreamId (optional)
The stream ID of the published stream that you want to make available for viewing (omitted when creating a publish token)
capabilities (optional)
An array of capabilities for the new stream
Supported Stream Capabilities
Value
Token Type
Description
multi-bitrate
publish
Provide multi-bitrate ABR for each viewer of the stream. The platform transcodes, in real-time, to multiple quality levels for each stream. The number of quality levels depends on the contribution quality of the stream as selected with the quality capabilities .
aspect-ratio=WxH
publish
Crop the stream to the desired aspect ratio during multi-bitrate transcoding. Example: aspect-ratio=9x16
crops the image to portrait mode in 9 by 16 format. The cropping produces the highest resolution possible limited only by the resolution of the multi-bitrate layer.
streaming
publish
In addition to real-time streaming, create a transcoded live stream using adaptive HLS and MPEG+DASH streaming. The live stream contains multiple quality options from audio-only to highest video quality.
on-demand
publish
Persist the transcoded live stream for on-demand playback. The stream features the same capabilities as the adaptive multi-bit rate live stream and can be accessed time delayed.
streaming-lite
publish
Only create one rendition for the live stream that corresponds to the highest quality level.
on-demand-lite
publish
Only create one rendition for the on-demand stream that corresponds to the highest quality level.
token-auth
publish
Protects the live stream with edge auth tokens. When enabled it requires a ?streamToken=<edgeAuthToken>
to be provided when accessing the manifests on all HTTP requests.
low-latency
publish
Experimental Use low latency settings for the adaptive bitrate live stream. This will trade bandwidth efficiency for lower latency.
high-fidelity
publish
Use high fidelity audio bitrate configuration for high-quality reproduction of sound.
rtmp
publish
In addition to real-time streaming, expose a RTMP streaming option.
channel
publish
The stream will be made available in the channel identified by one of the tags channelId: or channelAlias:. The channel must be owned by the same application as the stream.
audio-only
publish+subscribe
The stream will only have an audio track.
video-only
publish+subscribe
The stream will only have a video track.
real-time
subscribe
Use real-time streaming with typically less than 300 milliseconds delivery latency. This is the default.
broadcast
subscribe
Use broadcast real-time streaming with about 1 second delivery latency. This can be used for users with bad WiFi networks with high jitter and/or interference.
streaming
subscribe
Use adaptive live streaming using HLS or MPEG+DASH with about 8-12 seconds delivery latency. This can be used for broadcasts to clients with network connections with limited bandwidth or highly fluctuating bandwidth. It requires the publisher stream to have the “streaming” capability.
on-demand
subscribe
Use adaptive on-demand streaming using HLS or MPEG+DASH. This can be used to access the stream after it was recorded. It requires the publisher stream to have the “on-demand” capability.
rtmp
subscribe
Use RTMP for playback with about 1-2 seconds delivery latency. It requires the publisher stream to have the “rtmp” capability.
Wildcard Tokens : Wildcard stream tokens can be reused between multiple authorized sessions for accessing the stream. These tokens are generated using a wildcard “*” as the session ID. These tokens are valid for typically up to 24 hours upon which they expire automatically. Any use after that will result in unauthorized responses. Thus it is recommended to refresh tokens before the expiration time. For global broadcasting uses cases, it is recommended that wildcard tokens are refreshed frequently, e.g. every five minutes.
Supported Quality Capabilities
Value
Video Size
Description
Token Type
Video Bitrate, kbps
Audio Bitrate, kbps*
Recommended Bandwidth, kbps**
uld
144p
Ultra low definition
Publish
80
60
400
vld
240p
Very low definition
Publish
350
60
600
ld
360p
Low definition
Publish
520
60
1000
sd
480p
Standard definition - default
Publish
830
60
1500
hd
720p
High definition
Publish
1600
60
3000
fhd
1080p
Full high definition
Publish
3000
60
5000
xhd
1080p
Extended high definition
Publish
5500
60
10000
uhd
1080p+
Ultra high definition
Publish
8500
60
15000
* - In case of high fidelity audio capability, audio bitrate is 160kbps.
** - A stable low latency internet connection is recommended for best experience. Note that some Wifi and DSL lines may experience high latency periodically or under load which makes their effective throughput significantly less than their nominal bandwidth.
NB: For publishing, please make sure to select local user media option matching the quality of the stream. For example, it causes overhead if you select a user media with larger size than the recommended size for the quality level.
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.
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>",
}'
The Content-Length header is automatically populated by curl. If using another method to access the API, you must calculate and populate the Content-Length header.
Request 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.
Error Responses : Please be aware that some server errors 5XX and request validation errors 400 and 401 may result in an arbitrary response body not encoded in JSON.
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>"
}'
The Content-Length header is automatically populated by curl. If using another method to access the API, you must calculate and populate the Content-Length header.
Request Fields
Field
Description
applicationId (required)
Your application ID
secret (required)
Your application secret
streamId (required)
The stream ID of the on-demand stream that you want to delete
reason (required)
A reason for why the stream is deleted for your records.
Response
The platform will return a successful response that contains a “status” field. The HTTP status code is set according to the “status” field.
HTTP / 1.1 200 OK
Content-Type : application/json; charset=utf-8
Content-Length : 15
{ "status" : "ok" }
{
"status" :"ok"
}
Status Codes
HTTP
Status
Retry
Description
200 OK
ok
never
Stream was successfully terminated.
400 Bad Request
<varies>
never
Indicates an issue with the request itself.
401 Unauthorized
unauthorized
never
The streaming platform was not able to authorize the provided credentials.
404 Not Found
not-found
never
The specified stream is not known to the platform.
408 Request Timeout
request-timeout
once immediately, then exponential backoff
Request timed out likely due to temporary resource or network conditions. Please try again.
409 Conflict
not-ended
after terminating the stream
Stream has not ended. On-demand streams can not be deleted until the stream has terminated. To forcefully terminate a stream, see Terminating A Stream .
410 Gone
already-deleted
never
The specified stream has already been deleted.
410 Gone
resource-unavailable
never
The resources that hosted the specified stream are unavailable.
4XX
<varies>
never
Indicates an issue with the request itself.
503 Service Unavailable
capacity
once
The system is temporarily overloaded. Please try again later.
5XX
<varies>
once immediately, then exponential backoff
A transient server error.
Error Responses : Please be aware that some server errors 5XX and request validation errors 400 and 401 may result in an arbitrary response body not encoded in JSON.
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>"
}'
The Content-Length header is automatically populated by curl. If using another method to access the API, you must calculate and populate the Content-Length header.
Request Fields
Field
Description
applicationId (required)
Your application ID
secret (required)
Your application secret
streamId (required)
The stream ID of the stream whose playlist URIs are requested
Response
The platform will return a successful response that contains a “status” field. The HTTP status code is set according to the “status” field.
HTTP / 1.1 200 OK
Content-Type : application/json; charset=utf-8
Content-Length : 698
{ "status" : "ok" , "playlists" :[{ "name" : "live-720.mpd" , "type" : "Dash" , "uri" : "https://pcast.phenixrts.com/video/application-id/us-central#us-central1-c.YfMSNkZM.20171121.9VuaQSac/live-720.mpd" , "isPrimary" : false , "isVariant" : false , "isProtected" : false , "isEncrypted" : false , info ":{" bitrate ":null," height ":720," framesPerSecond ":null}},{" name ":" live.mpd "," type ":" Dash "," uri ":" https : //pcast.phenixrts.com/video/application-id/us-central#us-central 1 -c.YfMSNkZM. 20171121.9 VuaQSac/live.mpd "," isPrimary ":true," isVariant ":true," isProtected ":false," info ":{" bitrate ":null," height ":null," framesPerSecond ":null}},...]," streamInfo ":{" startTime ":" 2017-11-21 T 20 : 53 : 43.529000000 Z "," endTime ":" 2017-11-21 T 20 : 53 : 40.955000000 Z "}}
{
"status" : "ok" ,
"playlists" : [
{
"name" : "live-720.mpd" ,
"type" : "Dash" ,
"uri" : "https://pcast.phenixrts.com/video/application-id/us-central#us-central1-c.YfMSNkZM.20171121.9VuaQSac/live-720.mpd" ,
"isPrimary" : false ,
"isVariant" : false ,
"isProtected" : false ,
"isEncrypted" : false ,
"info" : {
"bitrate" : null,
"height" : 720,
"framesPerSecond" : null
}
} ,
{
"name" : "live.mpd" ,
"type" : "Dash" ,
"uri" : "https://pcast.phenixrts.com/video/application-id/us-central#us-central1-c.YfMSNkZM.20171121.9VuaQSac/live.mpd" ,
"isPrimary" : true ,
"isVariant" : true
"isProtected" : false ,
"isEncrypted" : false ,
"info" : {
"bitrate" : null
"height" : null,
"framesPerSecond" : null
}
} ,
...
] ,
"streamInfo" : {
"startTime" : "2017-11-21T20:53:43.529000000Z" ,
"endTime" : "2017-11-21T20:53:40.955000000Z"
}
}
Playlist API Status Codes
HTTP
Status
Retry
Description
200 OK
ok
never
Playlists were successfully retrieved.
400 Bad Request
<varies>
never
Indicates an issue with the request.
401 Unauthorized
unauthorized
never
The streaming platform was not able to authorize the provided credentials.
408 Request Timeout
request-timeout
once immediately, then exponential backoff
Request timed out likely due to temporary resource or network conditions. Please try again.
4XX
<varies>
never
Indicates an issue with the request.
503 Service Unavailable
capacity
once
The system is temporarily overloaded. Please try again later.
5XX
<varies>
once immediately, then exponential backoff
A transient server error.
Playlist API Response fields
Playlist fields
Field
Description
name
Name of the playlist
type
type of playlist - HLS or DASH
uri
URI of the playlist
isPrimary
Whether this is a primary playlist containing variant playlists
isVariant
Whether this is a variant playlist (Note: This flag is currently wrong. Use isPrimary
until it is fixed.)
isProtected
Whether this playlist is protected with an edge auth token. See token-auth
.
isEncrypted
Whether this playlist is encrypted with DRM
info
Metadata about the playlist. See Playlist metadata .
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.
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
Encoding : Stream ID may contain characters that are unsafe for URLs. Be sure to encode the StreamId in the URL path. For example, the URL encoding of `us-central#us-central` is `us-central%23us-central`
Request URI Parameters
Parameter
Description
streamToken (optional)
Streams protected with token-auth
require a valid edge auth token to be provided. An edge auth token issued for the channel ID or alias will grant access to the playlist for the channel. Alternatively, if the origin stream ID is known, access can be restricted to just a stream itself.
Response
The platform will return a successful response that contains a “status” field. The HTTP status code is set according to the “status” field.
Playlist API Status Codes
HTTP
Status
Retry
Description
200 OK
ok
never
Playlist was successfully retrieved.
400 Bad Request
<varies>
never
Indicates an issue with the request.
401 Unauthorized
unauthorized
never
The streaming platform was not able to authorize the provided credentials.
4XX
<varies>
never
Indicates an issue with the request.
503 Service Unavailable
capacity
once
The system is temporarily overloaded. Please try again later.
5XX
<varies>
once immediately, then exponential backoff
A transient server error.
Notifications
The PCast™ streaming platform can notify your backend when streams start and stop.
Request
You can set the callback endpoint for your application using a PUT
request.
PUT /pcast/application/<applicationId>/callback HTTP / 1.1
Host : pcast.phenixrts.com
Accept : application/json
Content-Type : application/json
Content-Length : 194
Authorization : Basic YXBwbGljYXRpb25JZDpzZWNyZXQ=
{
"callback" : {
"protocol" : "<protocol>" ,
"host" : "<host>" ,
"port" : <port> ,
"method" : "<method>" ,
"path" : "<path>" ,
"query" : "<query>"
}
}
$ curl https://pcast.phenixrts.com/pcast/application/<applicationId>/callback \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-u applicationId:secret \
-X PUT \
-d '{
"callback": {
"protocol": "<protocol>",
"host": "<host>",
"port": <port>,
"method": "<method>",
"path": "<path>",
"query": "<query>"
}
}'
The Content-Length header is automatically populated by curl. If using another method to access the API, you must calculate and populate the Content-Length header.
Request 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¶m2=false¶m3”)
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.
Debugging Notifications
Consider the webhook.site online tool if you need a way to debug callbacks from our platform.
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"
}'
The Content-Length header is automatically populated by curl. If using another method to access the API, you must calculate and populate the Content-Length header.
Request 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"
}'
The Content-Length header is automatically populated by curl. If using another method to access the API, you must calculate and populate the Content-Length header.
Request 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.
There is one event for each available playlists, e.g. adaptive multi-bitrate and each quality level.
POST <callback.path> HTTP / 1.1
Host : <callback.host>:<callback.port>
Content-Type : application/json
Content-Length : 222
{
"apiVersion" : 0 ,
"entity" , "stream" ,
"what" , "live" ,
"data" : {
"streamId" : "<streamId>" ,
"uri" : "<uri>"
},
"sessionId" : "<sessionId>" ,
"timestamp" : "2019-01-23T21:12:55.384Z"
}
$ curl <callback.url> \
-H "Content-Type: application/json" \
-X POST \
-d '{
"apiVersion": 0,
"entity", "stream",
"what", "live",
"data": {
"streamId": "<streamId>",
"uri": "<uri>",
"isPrimary": true,
"isVariant": false
},
"sessionId": "<sessionId>",
"timestamp": "2019-01-23T21:12:55.384Z"
}'
The Content-Length header is automatically populated by curl. If using another method to access the API, you must calculate and populate the Content-Length header.
Request Fields
Field
Description
apiVersion
The API version the message conforms to
entity
Belongs to the “stream” entity
what
Type “live” indicates a live playlist is available
data
The notification payload
data.streamId
The ID of the stream that started
data.uri
The URI of the playlist. File extensions: HLS -> .m3u8, MPEG-DASH -> .mpd
data.isPrimary
Whether this is a primary playlist containing variant playlists
data.isVariant
Whether this is a variant playlist (Note: This flag is currently wrong. Use isPrimary
until it is fixed.)
sessionId
The session ID of the client this stream belongs to
timestamp
The RFC3339 timestamp of when the request was initiated in Zulu time
On-demand Available Notification
Provide adaptive multi-bitrate on-demand streaming capabilities. Currently HLS and MPEG-DASH playlists as adaptive multi-bitrate and specific quality levels are supported.
This also makes the stream available inside all our SDKs using the “on-demand” capability when subscribing.
There is one event for each available playlists, e.g. adaptive multi-bitrate and each quality level.
POST <callback.path> HTTP / 1.1
Host : <callback.host>:<callback.port>
Content-Type : application/json
Content-Length : 227
{
"apiVersion" : 0 ,
"entity" , "stream" ,
"what" , "on-demand" ,
"data" : {
"streamId" : "<streamId>" ,
"uri" : "<uri>"
},
"sessionId" : "<sessionId>" ,
"timestamp" : "2019-01-23T21:12:55.384Z"
}
$ curl <callback.url> \
-H "Content-Type: application/json" \
-X POST \
-d '{
"apiVersion": 0,
"entity", "stream",
"what", "on-demand",
"data": {
"streamId": "<streamId>",
"uri": "<uri>",
"isPrimary": true,
"isVariant": false
},
"sessionId": "<sessionId>",
"timestamp": "2019-01-23T21:12:55.384Z"
}'
The Content-Length header is automatically populated by curl. If using another method to access the API, you must calculate and populate the Content-Length header.
Request Fields
Field
Description
apiVersion
The API version the message conforms to
entity
Belongs to the “stream” entity
what
Type “on-demand” indicates a on-demand playlist is available
data
The notification payload
data.streamId
The ID of the stream that started
data.uri
The URI of the playlist. File extensions: HLS -> .m3u8, MPEG-DASH -> .mpd
data.isPrimary
Whether this is a primary playlist containing variant playlists
data.isVariant
Whether this is a variant playlist (Note: This flag is currently wrong. Use isPrimary
until it is fixed.)
sessionId
The session ID of the client this stream belongs to
timestamp
The RFC3339 timestamp of when the request was initiated in Zulu time
Note on 5XX Errors
The notification service will automatically retry any 5XX HTTP errors using an exponential back-off algorithm. The first back-off is 3 seconds, the second one is 6 seconds and so on. At most 9 retries will be performed which amounts to a maximum of 25 minutes until a request is dropped.
Order of Notifications
Due to the nature of distributed environments and various effects including retries of transient errors, it’s possible that notifications are delivered out of natural order. For example, it is possible that you receive a stream ended notification before the corresponding stream started notification. Please make sure that your business logic can handle out-of-order notifications.
Note On API version
It is expected that your application can handle any new fields inside a message and any new notification types without a corresponding increment of the “apiVersion” field.
HMAC Authentication
You can authenticate notifications by using the HMAC-SHA256 authentication scheme. HMAC refers to hash-based message authentication code.
To authenticate a notification, you must assert that it contains valid X-PCast-Content-Sha256 and Authorization headers.
Header
Description
Authorization
Authentication information required by the HMAC-SHA256 scheme.
Content-Type
Indicates the original media type before any content encoding was applied for sending.
X-PCast-Content-Sha256
Base64 encoded SHA256 hash of the request body.
X-PCast-Timestamp
The RFC3339 timestamp of when the request was initiated in UNIX time
Validate X-PCast-Content-Sha256
To validate X-PCast-Content-Sha256
header you need to stringify the request body, and generate a SHA-265 hash from it. Then you need to compare generated hash with the hash in X-PCast-Content-Sha256
.
//Validate X-PCast-Content-Sha256
function isContentSha256Valid ( requestStringBody , contentSha256Header ) {
var generatedContentHash = crypto
. createHash ( 'sha256' )
. update ( requestStringBody )
. digest ( 'base64' );
return contentSha256Header === generatedContentHash ;
}
The Authorization
header consists of the HMAC hash of the request prefixed with HMAC-SHA256
.
Authorization = ‘HMAC-SHA256 ’ + hash (HMAC created using the SHA-256 hash algorithm with the application secret as key)
To validate the HMAC hash of the Authorization
header you must compare it with the one regenerated from the canonical representation of the request using your application secret as a key.
String-To-Sign = HTTP_METHOD + path_and_query + content_sha256_header + content_type_header + pcast_timestamp_header
// Generate string to sign
function getStringToSign ( method , path , contentSha256 , contentType , unixTimestamp ) {
return method + path + contentSha256 + contentType + unixTimestamp ;
}
// Validate Authorization header
function isAuthorizationHeaderValid ( secret , stringToSign , authorizationHeader ) {
var generatedHmacSha256Hash = 'HMAC-SHA256 ' + crypto
. createHmac ( 'sha256' , secret )
. update ( stringToSign )
. digest ( 'base64' );
return generatedHmacSha256Hash === authorizationHeader ;
}
Channel API
APIs for channels let you Create, List, Fetch and Delete Channels.
Creating a Channel
This API allows to create a channel.
Request
Send a PUT
request to the /pcast/channel
endpoint as shown:
PUT /pcast/channel HTTP / 1.1
Host : pcast.phenixrts.com
Accept : application/json
Authorization : Basic YXBwbGljYXRpb25JZDpzZWNyZXQ=
Content-Type : application/json
Content-Length : 172
{
"channel" : {
"alias" : "<channelAlias>" ,
"name" : "<channelName>" ,
"description" : "<channelDescription>" ,
"options" : [ <channelOptions> ]
}
}
$ curl https://pcast.phenixrts.com/pcast/channel \
-u applicationId:secret \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-X PUT \
-d '{
"channel": {
"alias": "<channelAlias>",
"name": "<channelName>",
"description": "<channelDescription>",
"options": [<channelOptions>]
}
}'
The Content-Length header is automatically populated by curl. If using another method to access the API, you must calculate and populate the Content-Length header.
Header
Description
Authorization (required)
Use HTTP Basic Authentication with your applicationId and secret
Request Fields
Field
Description
channel (required)
Channel Object
Channel Object
Field
Description
alias (required)
A user friendly unique identifier for the channel. An empty string is required if you want the Streaming platform to generate an alias for your channel.
name (required)
Unique name of the channel.
description (required)
A description for the channel.
options (required)
An array of options for the channel. An empty array is required if there are no options.
Response
The platform will return a successful response that contains a “status” field. The HTTP status code is set according to the “status” field.
HTTP / 1.1 200 OK
Content-Type : application/json; charset=utf-8
Content-Length : 427
{ "status" : "ok" , "channel" :{ "channelId" : "us-central#test#channe1" , "alias" : "morningNews" , "applicationId" : "test" , "name" : "Morning News" , "description" : "Morning News Channel - Chicago" , "type" : "Channel" , "streamKey" : "mRq5pZFuQf21lDgLsip1KhNgXC1CVvzJqftZBOW5vX1Kq06YtosMYyeIppPCC41h34bO1NFBbk4f6YLCHXvGYBvX6UoGYwxL" , "created" : "2018-02-05T18:21:28.280000000Z" , "lastUpdate" : "2018-02-05T18:21:28.280000000Z" , "estimatedSize" : 0 , "options" :[]}}
{
"status" : "ok" ,
"channel" : {
"channelId" : "us-central#test#channel1" ,
"alias" : "morningNews" ,
"applicationId" : "test" ,
"name" : "Morning News" ,
"description" : "Morning News Channel - Chicago" ,
"type" : "Channel" ,
"streamKey" : "mRq5pZFuQf21lDgLsip1KhNgXC1CVvzJqftZBOW5vX1Kq06YtosMYyeIppPCC41h34bO1NFBbk4f6YLCHXvGYBvX6UoGYwxL" ,
"created" : "2018-02-05T18:21:28.280000000Z" ,
"lastUpdate" : "2018-02-05T18:21:28.280000000Z" ,
"estimatedSize" : 0,
"options" : []
}
}
Create Channel API Status Codes
HTTP
Status
Retry
Description
200 OK
ok
never
Channel has been successfully created.
400 Bad Request
<varies>
never
Indicates an issue with the request.
401 Unauthorized
unauthorized
never
The streaming platform was not able to authorize the provided credentials.
409 Conflict
already-exists
never
The channel already exists.
4XX
<varies>
never
Indicates an issue with the request.
503 Service Unavailable
capacity
once
The system is temporarily overloaded. Please try again later.
504 Gateway Timeout
rate-limited
once immediately, then exponential backoff
The system is temporarily overloaded. Please try again later.
5XX
<varies>
once immediately, then exponential backoff
A transient server error.
Error Responses : Please be aware that some server errors 5XX and request validation errors 400 and 401 may result in an arbitrary response body not encoded in JSON.
Create Channel API Response fields
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
Encoding : Channel ID may contain characters that are unsafe for URLs. Be sure to encode the ChannelId in the URL path. For example, the URL encoding of `us-central#us-central` is `us-central%23us-central`
Request URI
Component
Description
urlEncodedChannelId (required)
URL encoded ID of the channel
Header
Description
Authorization (required)
Use HTTP Basic Authentication with your applicationId and secret
Response
The platform will return a successful response that contains a “status” field. The HTTP status code is set according to the “status” field.
HTTP / 1.1 200 OK
Content-Type : application/json; charset=utf-8
Content-Length : 412
{ "status" : "ok" , "channel" :{ "channelId" : "local#test#channel1" , "alias" : "channel1" , "applicationId" : "test" , "name" : "channel 1" , "description" : "a channel description" , "type" : "Channel" , "streamKey" : "F4CIbURu34oYH1OikqZsqaEkK1wgCJ2Lmn4xaJlXGA24ptLip4wKSWnfFeAjj9HDSEJ4b7EafGrEp1d9G3L1A9h0avUC7HPc" , "created" : "2018-02-05T22:20:25.304000000Z" , "lastUpdate" : "2018-02-05T22:20:25.304000000Z" , "estimatedSize" : 13741 , "options" :[]}}
{
"status" : "ok" ,
"channel" : {
"channelId" : "local#test#channel1" ,
"alias" : "channel1" ,
"applicationId" : "test" ,
"name" : "channel 1" ,
"description" : "a channel description" ,
"type" : "Channel" ,
"streamKey" : "F4CIbURu34oYH1OikqZsqaEkK1wgCJ2Lmn4xaJlXGA24ptLip4wKSWnfFeAjj9HDSEJ4b7EafGrEp1d9G3L1A9h0avUC7HPc" ,
"created" : "2018-02-05T22:20:25.304000000Z" ,
"lastUpdate" : "2018-02-05T22:20:25.304000000Z" ,
"estimatedSize" : 13741,
"options" : []
}
}
Fetching a Channel API Status Codes
HTTP
Status
Retry
Description
200 OK
ok
never
Channel was successfully returned.
400 Bad Request
<varies>
never
Indicates an issue with the request.
401 Unauthorized
unauthorized
never
The streaming platform was not able to authorize the provided credentials.
404 Not Found
not-found
never
The channel does not exist.
4XX
<varies>
never
Indicates an issue with the request.
503 Service Unavailable
capacity
once
The system is temporarily overloaded. Please try again later.
504 Gateway Timeout
rate-limited
once immediately, then exponential backoff
The system is temporarily overloaded. Please try again later.
5XX
<varies>
once immediately, then exponential backoff
A transient server error.
Error Responses : Please be aware that some server errors 5XX and request validation errors 400 and 401 may result in an arbitrary response body not encoded in JSON.
Fetching a Channel API Response fields
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
Encoding : Channel ID may contain characters that are unsafe for URLs. Be sure to encode the ChannelId in the URL path. For example, the URL encoding of `us-central#us-central` is `us-central%23us-central`
Request URI
Component
Description
urlEncodedRoomId (required)
ID of the channel.
Header
Description
Authorization (required)
Use HTTP Basic Authentication with your applicationId and secret
Response
The API call returns an HTTP response per the following:
HTTP/2 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 642
{
"status": "ok",
"members": [
{
"sessionId": "us-southwest#DpMPWP3YQu8dmJCN9Vfn2v",
"screenName": "Primary-mrvwman-438728",
"role": "Presenter",
"streams": [
{
"type": "Presentation",
"uri": "pcast://phenixrts.com/us-southwest#us-west2-c.XfFVcxNg.20200205.PYIyIFS4?capabilities=multi-bitrate%2Cfhd",
"audioState": "TrackEnabled",
"videoState": "TrackEnabled"
}
],
"state": "Passive",
"lastUpdate": 1580913727128
}
]
}
{
"status" : "ok" ,
"members" : [
{
"sessionId" : "us-southwest#DpMPWP3YQu8dmJCN9Vfn2v" ,
"screenName" : "Primary-mrvwman-438728" ,
"role" : "Presenter" ,
"streams" : [
{
"type" : "Presentation" ,
"uri" : "pcast://phenixrts.com/us-southwest#us-west2-c.XfFVcxNg.20200205.PYIyIFS4?capabilities=multi-bitrate%2Cfhd" ,
"audioState" : "TrackEnabled" ,
"videoState" : "TrackEnabled"
}
] ,
"state" : "Passive" ,
"lastUpdate" : 1580913727128
}
]
}
Fetch Channel Member API Status Codes
HTTP
Status
Retry
Description
200 OK
ok
never
Channel members were successfully listed.
400 Bad Request
<varies>
never
Indicates an issue with the request.
401 Unauthorized
unauthorized
never
The streaming platform was not able to authorize the provided credentials.
404 Not Found
not found
never
The channel was not found.
4XX
<varies>
never
Indicates an issue with the request.
503 Service Unavailable
capacity
once
The system is temporarily overloaded. Please try again later.
504 Gateway Timeout
rate-limited
once immediately, then exponential backoff
The system is temporarily overloaded. Please try again later.
504 Gateway Timeout
time-exceeded
once immediately, then exponential backoff
The request took to long to execute. Please try again later.
5XX
<varies>
once immediately, then exponential backoff
A transient server error.
Error Responses : Please be aware that some server errors 5XX and request validation errors 400 and 401 may result in an arbitrary response body not encoded in JSON.
Fetch Channel Member API Response fields
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
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
Encoding : Channel ID may contain characters that are unsafe for URLs. Be sure to encode the ChannelId in the URL path. For example, the URL encoding of `us-central#us-central` is `us-central%23us-central`
The Content-Length header is automatically populated by curl. If using another method to access the API, you must calculate and populate the Content-Length header.
Request URI
Component
Description
urlEncodedChannelId (required)
URL encoded ID of the channel
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.
Error Responses : Please be aware that some server errors 5XX and request validation errors 400 and 401 may result in an arbitrary response body not encoded in JSON.
Delete Channel API Response fields
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": []
}'
Encoding : Channel ID may contain characters that are unsafe for URLs. Be sure to encode the ChannelId in the URL path. For example, the URL encoding of `us-central#us-central` is `us-central%23us-central`
The Content-length header is automatically populated by curl. If using another method to access the API, you must calculate and populate the Content-length header.
Request URI
Component
Description
urlEncodedSourceChannelId (required)
URL encoded Channel ID of the source channel to fork from.
urlEncodedDestinationChannelId (required)
URL encoded Channel ID of the destination channel to fork into.
Header
Description
Authorization (required)
Use HTTP Basic Authentication with your applicationId and secret
Request Fields
Field
Description
streamTags (optional)
An array of tags (strings) to apply to the destination streams.
streamCapabilities (optional)
An array of capabilities (strings) to apply to the newly forked stream.
options (optional)
An array of options (strings) for the channel. Current valid options are: “force”, “additive” and “keep-streams”. The default behavior is not touch the stream(s) with matching session IDs that are already publishing to the destination channel. With the “force” option, the stream(s) will be terminated and replaced. With the “additive” option, the stream(s) will be added to any existing members in the channel. “keep-streams” removes the members but leaves the streams alive. Clients will receive the member update, but they are not securely terminated from the stream. In Phenix client implementations the default is to end the client stream, but customer client implementations may vary.
Response
The API call returns an HTTP response per the following:
HTTP/2 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 623
{
"status": "ok",
"members": [
{
"sessionId": "us-southwest#DpMPWP3YQu8dmJCN9Vfn2v",
"screenName": "Primary-mrvwman-438728",
"role": "Presenter",
"streams": [
{
"type": "Presentation",
"uri": "pcast://phenixrts.com/us-southwest#us-west2-c.XfFVcxNg.20200205.PYIyIFS4?capabilities=multi-bitrate%2Cfhd",
"audioState": "TrackEnabled",
"videoState": "TrackEnabled"
}
],
"state": "Passive",
"lastUpdate": 1580913727128
}
]
}
{
"status" : "ok" ,
"members" : [
{
"sessionId" : "us-southwest#DpMPWP3YQu8dmJCN9Vfn2v" ,
"screenName" : "Primary-mrvwman-438728" ,
"role" : "Presenter" ,
"streams" : [
{
"type" : "Presentation" ,
"uri" : "pcast://phenixrts.com/us-southwest#us-west2-c.XfFVcxNg.20200205.PYIyIFS4?capabilities=multi-bitrate%2Cfhd" ,
"audioState" : "TrackEnabled" ,
"videoState" : "TrackEnabled"
}
] ,
"state" : "Passive" ,
"lastUpdate" : 1580913727128
}
]
}
Fork Channel API Status Codes
HTTP
Status
Retry
Description
200 OK
ok
never
Channel was successfully forked.
400 Bad Request
<varies>
never
Indicates an issue with the request. Eg: Options must be an array of strings.
401 Unauthorized
unauthorized
never
The streaming platform was not able to authorize the provided credentials.
404 Not Found
not found
never
One or both of the source and destination channels are not found.
4XX
<varies>
never
Indicates an issue with the request.
503 Service Unavailable
capacity
once
The system is temporarily overloaded. Please try again later.
504 Gateway Timeout
rate-limited
once immediately, then exponential backoff
The system is temporarily overloaded. Please try again later.
504 Gateway Timeout
time-exceeded
once immediately, then exponential backoff
The request took to long to execute. Please try again later.
5XX
<varies>
once immediately, then exponential backoff
A transient server error.
Error Responses : Please be aware that some server errors 5XX and request validation errors 400 and 401 may result in an arbitrary response body not encoded in JSON.
Fork Channel API Response fields
Field
Description
status
See Status Codes .
members
Array of session objects that have been forked.
Kill a Channel
This API allows the caller to remove all the publishers and terminate the corresponding streams within the specified channel.
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": []
}'
Encoding : Channel ID may contain characters that are unsafe for URLs. Be sure to encode the ChannelId in the URL path. For example, the URL encoding of `us-central#us-central` is `us-central%23us-central`
The Content-length header is automatically populated by curl. If using another method to access the API, you must calculate and populate the Content-length header.
Request URI
Component
Description
urlEncodedChannelId (required)
ID of the channel to kill.
Header
Description
Authorization (required)
Use HTTP Basic Authentication with your applicationId and secret
Request Fields
Field
Description
reason (optional)
Arbitrary text string for recording why the stream was killed.
options (optional)
An array of options (strings). Valid options are: “keep-streams”. “keep-streams” removes the members but leaves the streams alive. Clients will receive the member update, but they are not securely terminated from the stream. In Phenix client implementations the default is to end the client stream, but customer client implementations may vary.
Response
The API call returns an HTTP response per the following:
HTTP/2 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 629
{
"status": "ok",
"killedMembers": [
{
"sessionId": "us-southwest#DpMPWP3YQu8dmJCN9Vfn2v",
"screenName": "Primary-mrvwman-438728",
"role": "Presenter",
"streams": [
{
"type": "Presentation",
"uri": "pcast://phenixrts.com/us-southwest#us-west2-c.XfFVcxNg.20200205.PYIyIFS4?capabilities=multi-bitrate%2Cfhd",
"audioState": "TrackEnabled",
"videoState": "TrackEnabled"
}
],
"state": "Passive",
"lastUpdate": 1580913727128
}
]
}
{
"status" : "ok" ,
"killedMembers" : [
{
"sessionId" : "us-southwest#DpMPWP3YQu8dmJCN9Vfn2v" ,
"screenName" : "Primary-mrvwman-438728" ,
"role" : "Presenter" ,
"streams" : [
{
"type" : "Presentation" ,
"uri" : "pcast://phenixrts.com/us-southwest#us-west2-c.XfFVcxNg.20200205.PYIyIFS4?capabilities=multi-bitrate%2Cfhd" ,
"audioState" : "TrackEnabled" ,
"videoState" : "TrackEnabled"
}
] ,
"state" : "Passive" ,
"lastUpdate" : 1580913727128
}
]
}
Kill Channel API Status Codes
HTTP
Status
Retry
Description
200 OK
ok
never
Channel was successfully killed.
400 Bad Request
<varies>
never
Indicates an issue with the request. Eg: Options must be an array of strings.
401 Unauthorized
unauthorized
never
The streaming platform was not able to authorize the provided credentials or Field “reason” must be a string.
404 Not Found
not found
never
The channel was not found.
4XX
<varies>
never
Indicates an issue with the request.
503 Service Unavailable
capacity
once
The system is temporarily overloaded. Please try again later.
504 Gateway Timeout
rate-limited
once immediately, then exponential backoff
The system is temporarily overloaded. Please try again later.
504 Gateway Timeout
time-exceeded
once immediately, then exponential backoff
The request took to long to execute. Please try again later.
5XX
<varies>
once immediately, then exponential backoff
A transient server error while processing the request.
Error Responses : Please be aware that some server errors 5XX and request validation errors 400 and 401 may result in an arbitrary response body not encoded in JSON.
Kill Channel API Response fields
Field
Description
status
See Status Codes .
killedMembers
Array of session objects that have been killed.
Checking the State of a Channel
This API allows to check the number of publishers in a channel. This can be used to verify the health of ingests, e.g. redundant RTMP ingests.
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
Encoding : Channel ID may contain characters that are unsafe for URLs. Be sure to encode the ChannelId in the URL path. For example, the URL encoding of `us-central#us-central` is `us-central%23us-central`
The Content-Length header is automatically populated by curl. If using another method to access the API, you must calculate and populate the Content-Length header.
Request URI
Component
Description
urlEncodedChannelId (required)
URL encoded ID of the channel
Request URI Parameters
Parameter
Description
failIfLess (optional)
The number of required publishers that meet all criteria for the channel.
withStreams (optional)
The number of streams required per publisher to be considered active in the channel. Defaults to 1.
withScreenName (optional)
Only consider publishers with the given screen name. By default all screen names are considered.
Response
The platform will return a successful response that contains a “status” field. The HTTP status code is set according to the “status” field.
HTTP / 1.1 200 OK
Content-Type : application/json; charset=utf-8
Content-Length : 1
1
1
Health Channel API Status Codes
HTTP
Status
Retry
Description
200 OK
ok
never
Number of publishers was successfully reported.
400 Bad Request
never
Indicates an issue with the request.
404 Not Found
not-found
never
Indicates the channel was not found.
4XX
never
Indicates an issue with the request.
412 Precondition Failed
never
There is fewer than the required number of publishers.
503 Service Unavailable
capacity
once
The system is temporarily overloaded. Please try again later.
504 Gateway Timeout
rate-limited
once immediately, then exponential backoff
The system is temporarily overloaded. Please try again later.
504 Gateway Timeout
time-exceeded
once immediately, then exponential backoff
The request took to long to execute. Please try again later.
5XX
once immediately, then exponential backoff
A transient server error.
Error Responses : Please be aware that some server errors 5XX and request validation errors 400 and 401 may result in an arbitrary response body not encoded in JSON.
Channel API Response fields
The response body is a text field with the number of publishers actively publishing a stream to the channel.
Universal Live Manifest for a Channel
This API allows to retrieve a live manifest of any type for a channel. The URL is valid for the lifetime of the channel and always points to the most recent stream in the channel. In order for this to work, the stream must have enabled streaming
capability.
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
Encoding : Channel ID may contain characters that are unsafe for URLs. Be sure to encode the ChannelId in the URL path. For example, the URL encoding of `us-central#us-central` is `us-central%23us-central`
The Content-Length header is automatically populated by curl. If using another method to access the API, you must calculate and populate the Content-Length header.
Request URI
Component
Description
urlEncodedChannelId (required)
URL encoded ID of the channel
manifest (required)
The manifest ID such as live.m3u8 for HLS and live.mpd for DASH.
Request URI Parameters
Parameter
Description
streamToken (optional)
Streams protected with token-auth
require a valid edge auth token to be provided. An edge auth token issued for the channel ID or alias will grant access to the playlist for the channel. Alternatively, if the origin stream ID is known, access can be restricted to just a stream itself.
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
#EXTM 3 U
#EXT-X-STREAM-INF : PROGRAM-ID= 1 , CODECS= "avc1.42c01f,mp4a.40.2" , BANDWIDTH= 1728000 , AVERAGE-BANDWIDTH= 1728000 , FRAME-RATE= 30
live -720 .m 3 u 8
#EXT-X-STREAM-INF : PROGRAM-ID= 1 , CODECS= "avc1.42c01f,mp4a.40.2" , BANDWIDTH= 958000 , AVERAGE-BANDWIDTH= 958000 , FRAME-RATE= 30
live -480 .m 3 u 8
#EXT-X-STREAM-INF : PROGRAM-ID= 1 , CODECS= "avc1.42c01f,mp4a.40.2" , BANDWIDTH= 584000 , AVERAGE-BANDWIDTH= 584000 , FRAME-RATE= 15
live -360 .m 3 u 8
#EXT-X-STREAM-INF : PROGRAM-ID= 1 , CODECS= "avc1.42c01f,mp4a.40.2" , BANDWIDTH= 414000 , AVERAGE-BANDWIDTH= 414000 , FRAME-RATE= 15
live -240 .m 3 u 8
#EXT-X-STREAM-INF : PROGRAM-ID= 1 , CODECS= "avc1.42c01e,mp4a.40.2" , BANDWIDTH= 144000 , AVERAGE-BANDWIDTH= 144000 , FRAME-RATE= 15
live -144 .m 3 u 8
#EXT-X-STREAM-INF : PROGRAM-ID= 1 , CODECS= "mp4a.40.2" , BANDWIDTH= 128000 , AVERAGE-BANDWIDTH= 128000 , FRAME-RATE= 0
live-ahi.m 3 u 8
#EXT-X-STREAM-INF : PROGRAM-ID= 1 , CODECS= "mp4a.40.2" , BANDWIDTH= 64000 , AVERAGE-BANDWIDTH= 64000 , FRAME-RATE= 0
live-alo.m 3 u 8
Found. Redirecting to /video/<applicationId>/<streamId>/live.m3u8
Manifest Channel API Status Codes
HTTP
Status
Retry
Description
302 Found
never
The manifest was successfully located and a redirect URL is provided.
400 Bad Request
never
Indicates an issue with the request.
404 Not Found
not found
never
Indicates the channel or the manifest was not found.
415 Unsupported Media Type
never
The channel does not support streaming
.
4XX
never
Indicates an issue with the request.
503 Service Unavailable
capacity
once
The system is temporarily overloaded. Please try again later.
504 Gateway Timeout
rate-limited
once immediately, then exponential backoff
The system is temporarily overloaded. Please try again later.
504 Gateway Timeout
time-exceeded
once immediately, then exponential backoff
The request took to long to execute. Please try again later.
5XX
once immediately, then exponential backoff
A transient server error.
Manifest Channel API Response fields
The response is redirecting to the manifest file via a standard HTTP redirect response (302).
Sending a Message
This API allows to send a message.
Request
Send a PUT
request to the /pcast/channel/<urlEncodedChannelId>/message
endpoint as shown:
PUT /pcast/channel/<urlEncodedChannelId>/message HTTP / 1.1
Host : pcast.phenixrts.com
Accept : application/json
Authorization : Basic YXBwbGljYXRpb25JZDpzZWNyZXQ=
Content-Type : application/json
Content-Length : 303
{
"message" : {
"from" : {
"screenName" : "Screen Name" ,
"role" : "Moderator" ,
"lastUpdate" : 0
},
"mimeType" : "text/plain" ,
"message" : "My message" ,
"tags" : [ "my-tag" , "my-other-tag" ]
}
}
$ curl https://pcast.phenixrts.com/pcast/channel/<urlEncodedChannelId>/message \
-u applicationId:secret \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-X PUT \
-d '{
"message": {
"from": {
"screenName": "Screen Name",
"role": "Moderator",
"lastUpdate": 0
},
"mimeType": "text/plain",
"message": "My message",
"tags": ["my-tag", "my-other-tag"]
}
}'
Encoding : Channel ID may contain characters that are unsafe for URLs. Be sure to encode the ChannelId in the URL path. For example, the URL encoding of `us-central#us-central` is `us-central%23us-central`
The Content-Length header is automatically populated by curl. If using another method to access the API, you must calculate and populate the Content-Length header.
Header
Description
Authorization (required)
Use HTTP Basic Authentication with your applicationId and secret
Request Fields
Message Object
Field
Description
from (required)
User Object representing the sender of the message.
mimeType (required)
The mime type of the content.
message (required)
The message. Binary messages should be base64 encoded.
tags (required)
An array of tags for the message.
User Object
Field
Description
sessionId (optional)
The session ID of the user.
screenName (required)
The screen name of the user.
role (required)
The role of the user. Valid values are: Participant, Moderator, Presenter, and Audience.
lastUpdate (required)
The last update of the user as a UNIX timestamp.
Response
The platform will return a successful response that contains a “status” field. The HTTP status code is set according to the “status” field.
HTTP / 1.1 200 OK
Content-Type : application/json; charset=utf-8
Content-Length : 310
{ "status" : "ok" , "message" :{ "messageId" : "us-central#room|test#testing.xV1OVWEkOxZm|0000000009" , "timestamp" : 1596088080439 , "deletedTimestamp" : 0 , "from" :{ "sessionId" : "api" , "screenName" : "Screen Name" , "role" : "Moderator" , "lastUpdate" : 0 }, "mimeType" : "text/plain" , "message" : "My message" , "tags" :[ "my-tag" , "my-other-tag" ]}}
{
"status" : "ok" ,
"message" : {
"messageId" : "us-central#room|test#testing.xV1OVWEkOxZm|0000000009" ,
"timestamp" : 1596088080439,
"deletedTimestamp" : 0,
"from" : {
"sessionId" : "api" ,
"screenName" : "Screen Name" ,
"role" : "Moderator" ,
"lastUpdate" : 0
} ,
"mimeType" : "text/plain" ,
"message" : "My message" ,
"tags" : [
"my-tag" ,
"my-other-tag"
]
}
}
Send Channel Message API Status Codes
HTTP
Status
Retry
Description
200 OK
ok
never
Message has been successfully sent.
400 Bad Request
<varies>
never
Indicates an issue with the request.
401 Unauthorized
unauthorized
never
The streaming platform was not able to authorize the provided credentials.
404 Not Found
not-found
never
The channel does not exist.
413 Payload Too Large
<varies>
never
One of the fields exceeds the limits. The size limit for messages is 1024 bytes. The total limit for all tags is 512 bytes. The screen name and mime type each must not exceed 128 bytes.
4XX
<varies>
never
Indicates an issue with the request.
503 Service Unavailable
capacity
once
The system is temporarily overloaded. Please try again later.
504 Gateway Timeout
rate-limited
once immediately, then exponential backoff
The system is temporarily overloaded. Please try again later.
5XX
<varies>
once immediately, then exponential backoff
A transient server error.
Error Responses : Please be aware that some server errors 5XX and request validation errors 400 and 401 may result in an arbitrary response body not encoded in JSON.
Send Channel Message API Response fields
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
Encoding : Channel ID may contain characters that are unsafe for URLs. Be sure to encode the ChannelId in the URL path. For example, the URL encoding of `us-central#us-central` is `us-central%23us-central`
Header
Description
Authorization (required)
Use HTTP Basic Authentication with your applicationId and secret
Request URI Parameters
Parameter
Description
limit (optional)
The number of messages to fetch. Defaults to 100.
beforeMessageId (optional)
The upper bound of the fetch range represented by another message ID.
afterMessageId (optional)
The lower bound of the fetch range represented by another message ID.
mimeTypes (optional)
Comma separated list of mime types. When provided only messages with the specified mime types will be returned. Note the search range is still the same so if no messages within the underlying range match then the result might be zero or less than the requested limit.
Response
The platform will return a successful response that contains a “status” field. The HTTP status code is set according to the “status” field.
HTTP / 1.1 200 OK
Content-Type : application/json; charset=utf-8
Content-Length : 395echo
{ "status" : "ok" , "messages" :[{ "messageId" : "us-central#room|test#testing.xV1OVWEkOxZm|0000000243" , "timestamp" : 1596089241062 , "deletedTimestamp" : 0 , "from" :{ "sessionId" : "local#IrGTKf0ztwN3H5xORrtD9e" , "screenName" : "ScreenName58611" , "role" : "Participant" , "lastUpdate" : 1596089235915 }, "mimeType" : "text/plain" , "message" : "Test message 240:1596089241045" , "tags" :[]}], "hasMoreBefore" : false , "hasMoreAfter" : false }
{
"status" : "ok" ,
"messages" : [
{
"messageId" : "us-central#room|test#testing.xV1OVWEkOxZm|0000000243" ,
"timestamp" : 1596089241062,
"deletedTimestamp" : 0,
"from" : {
"sessionId" : "local#IrGTKf0ztwN3H5xORrtD9e" ,
"screenName" : "ScreenName58611" ,
"role" : "Participant" ,
"lastUpdate" : 1596089235915
} ,
"mimeType" : "text/plain" ,
"message" : "Test message 240:1596089241045" ,
"tags" : []
}
] ,
"hasMoreBefore" : false ,
"hasMoreAfter" : false
}
Fetch Channel Messages API Status Codes
HTTP
Status
Retry
Description
200 OK
ok
never
Messages have been successfully fetched.
400 Bad Request
<varies>
never
Indicates an issue with the request.
401 Unauthorized
unauthorized
never
The streaming platform was not able to authorize the provided credentials.
404 Not Found
not-found
never
The channel does not exist.
413 Payload Too Large
limit-too-large
never
Too many messages are requested. The maximal limit is 128 messages per request.
4XX
<varies>
never
Indicates an issue with the request.
503 Service Unavailable
capacity
once
The system is temporarily overloaded. Please try again later.
504 Gateway Timeout
rate-limited
once immediately, then exponential backoff
The system is temporarily overloaded. Please try again later.
5XX
<varies>
once immediately, then exponential backoff
A transient server error.
Error Responses : Please be aware that some server errors 5XX and request validation errors 400 and 401 may result in an arbitrary response body not encoded in JSON.
Fetch Channel Messages API Response fields
Field
Description
status
See Status Codes
messages
Array of Message Object
hasMoreBefore
A boolean flag indicating if there is potentially more messages before the returned range.
hasMoreAfter
A boolean flag indicating if there is potentially more messages after the returned range.
Purging Messages of a Channel
This API allows to purge all messages of a channel. By default, channel messages are retained for 90 days.
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
Encoding : Channel ID may contain characters that are unsafe for URLs. Be sure to encode the ChannelId in the URL path. For example, the URL encoding of `us-central#us-central` is `us-central%23us-central`
The Content-Length header is automatically populated by curl. If using another method to access the API, you must calculate and populate the Content-Length header.
Request URI
Component
Description
urlEncodedChannelId (required)
URL encoded ID of the channel
Header
Description
Authorization (required)
Use HTTP Basic Authentication with your applicationId and secret
Response
The platform will return a successful response that contains a “status” field. The HTTP status code is set according to the “status” field.
HTTP / 1.1 200 OK
Content-Type : application/json; charset=utf-8
Content-Length : 32
{ "status" : "ok" , "deletedCount" : 1 }
{
"status" : "ok" ,
"deletedCount" : 1
}
Purge Channel Messages API Status Codes
HTTP
Status
Retry
Description
200 OK
ok
never
Channel was successfully deleted.
400 Bad Request
<varies>
never
Indicates an issue with the request.
401 Unauthorized
unauthorized
never
The streaming platform was not able to authorize the provided credentials.
404 Not Found
not-found
never
The channel does not exist.
4XX
<varies>
never
Indicates an issue with the request.
503 Service Unavailable
capacity
once
The system is temporarily overloaded. Please try again later.
504 Gateway Timeout
rate-limited
once immediately, then exponential backoff
The system is temporarily overloaded. Please try again later.
5XX
<varies>
once immediately, then exponential backoff
A transient server error.
Error Responses : Please be aware that some server errors 5XX and request validation errors 400 and 401 may result in an arbitrary response body not encoded in JSON.
Purge Channel Messages API Response fields
Field
Description
status
See Status Codes
deletedCount
The number of deleted messages.
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>]
}
}'
The Content-Length header is automatically populated by curl. If using another method to access the API, you must calculate and populate the Content-Length header.
Header
Description
Authorization (required)
Use HTTP Basic Authentication with your applicationId and secret
Request Fields
Field
Description
room (required)
Room Object
Room Object
Field
Description
alias (required)
A user friendly unique identifier for the room. An empty string is required if you want the Streaming platform to generate an alias for your room.
name (required)
Unique name of the room.
description (required)
A description for the room.
type (required)
Type of the room. Defaults to MultiPartyChat . Valid values include: DirectChat , MultiPartyChat , ModeratedChat and TownHall .
options (required)
An array of options for the room. An empty array is required if there are no options.
Response
The platform will return a successful response that contains a “status” field. The HTTP status code is set according to the “status” field.
HTTP / 1.1 200 OK
Content-Type : application/json; charset=utf-8
Content-Length : 427
{ "status" : "ok" , "room" :{ "roomId" : "us-central#test#channe1" , "alias" : "morningNews" , "applicationId" : "test" , "name" : "Morning News" , "description" : "Morning News Room - Chicago" , "type" : "MultiPartyChat" , "streamKey" : "mRq5pZFuQf21lDgLsip1KhNgXC1CVvzJqftZBOW5vX1Kq06YtosMYyeIppPCC41h34bO1NFBbk4f6YLCHXvGYBvX6UoGYwxL" , "created" : "2018-02-05T18:21:28.280000000Z" , "lastUpdate" : "2018-02-05T18:21:28.280000000Z" , "estimatedSize" : 0 , "options" :[]}}
{
"status" : "ok" ,
"room" : {
"roomId" : "us-central#test#room1" ,
"alias" : "morningNews" ,
"applicationId" : "test" ,
"name" : "Morning News" ,
"description" : "Morning News Room - Chicago" ,
"type" : "MultiPartyChat" ,
"streamKey" : "mRq5pZFuQf21lDgLsip1KhNgXC1CVvzJqftZBOW5vX1Kq06YtosMYyeIppPCC41h34bO1NFBbk4f6YLCHXvGYBvX6UoGYwxL" ,
"created" : "2018-02-05T18:21:28.280000000Z" ,
"lastUpdate" : "2018-02-05T18:21:28.280000000Z" ,
"estimatedSize" : 0,
"options" : []
}
}
Create Room API Status Codes
HTTP
Status
Retry
Description
200 OK
ok
never
Room has been successfully created.
400 Bad Request
<varies>
never
Indicates an issue with the request.
401 Unauthorized
unauthorized
never
The streaming platform was not able to authorize the provided credentials.
409 Conflict
already-exists
never
The room already exists.
4XX
<varies>
never
Indicates an issue with the request.
503 Service Unavailable
capacity
once
The system is temporarily overloaded. Please try again later.
504 Gateway Timeout
rate-limited
once immediately, then exponential backoff
The system is temporarily overloaded. Please try again later.
5XX
<varies>
once immediately, then exponential backoff
A transient server error.
Error Responses : Please be aware that some server errors 5XX and request validation errors 400 and 401 may result in an arbitrary response body not encoded in JSON.
Create Room API Response fields
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
Encoding : Room ID may contain characters that are unsafe for URLs. Be sure to encode the RoomId in the URL path. For example, the URL encoding of `us-central#us-central` is `us-central%23us-central`
Request URI
Component
Description
urlEncodedRoomId (required)
URL encoded ID of the room
Header
Description
Authorization (required)
Use HTTP Basic Authentication with your applicationId and secret
Response
The platform will return a successful response that contains a “status” field. The HTTP status code is set according to the “status” field.
HTTP / 1.1 200 OK
Content-Type : application/json; charset=utf-8
Content-Length : 412
{ "status" : "ok" , "room" :{ "roomId" : "local#test#room1" , "alias" : "room1" , "applicationId" : "test" , "name" : "room 1" , "description" : "a room description" , "type" : "MultiPartyChat" , "streamKey" : "F4CIbURu34oYH1OikqZsqaEkK1wgCJ2Lmn4xaJlXGA24ptLip4wKSWnfFeAjj9HDSEJ4b7EafGrEp1d9G3L1A9h0avUC7HPc" , "created" : "2018-02-05T22:20:25.304000000Z" , "lastUpdate" : "2018-02-05T22:20:25.304000000Z" , "estimatedSize" : 13741 , "options" :[]}}
{
"status" : "ok" ,
"room" : {
"roomId" : "local#test#room1" ,
"alias" : "room1" ,
"applicationId" : "test" ,
"name" : "room 1" ,
"description" : "a room description" ,
"type" : "MultiPartyChat" ,
"streamKey" : "F4CIbURu34oYH1OikqZsqaEkK1wgCJ2Lmn4xaJlXGA24ptLip4wKSWnfFeAjj9HDSEJ4b7EafGrEp1d9G3L1A9h0avUC7HPc" ,
"created" : "2018-02-05T22:20:25.304000000Z" ,
"lastUpdate" : "2018-02-05T22:20:25.304000000Z" ,
"estimatedSize" : 13741,
"options" : []
}
}
Fetching a Room API Status Codes
HTTP
Status
Retry
Description
200 OK
ok
never
Room was successfully returned.
400 Bad Request
<varies>
never
Indicates an issue with the request.
401 Unauthorized
unauthorized
never
The streaming platform was not able to authorize the provided credentials.
404 Not Found
not found
never
The room was not found.
4XX
<varies>
never
Indicates an issue with the request.
503 Service Unavailable
capacity
once
The system is temporarily overloaded. Please try again later.
504 Gateway Timeout
rate-limited
once immediately, then exponential backoff
The system is temporarily overloaded. Please try again later.
5XX
<varies>
once immediately, then exponential backoff
A transient server error.
Error Responses : Please be aware that some server errors 5XX and request validation errors 400 and 401 may result in an arbitrary response body not encoded in JSON.
Fetching a Room API Response fields
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
Encoding : Room ID may contain characters that are unsafe for URLs. Be sure to encode the RoomId in the URL path. For example, the URL encoding of `us-central#us-central` is `us-central%23us-central`
Request URI
Component
Description
urlEncodedRoomId (required)
ID of the room.
Header
Description
Authorization (required)
Use HTTP Basic Authentication with your applicationId and secret
Response
The API call returns an HTTP response per the following:
HTTP/2 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 642
{
"status": "ok",
"members": [
{
"sessionId": "us-southwest#DpMPWP3YQu8dmJCN9Vfn2v",
"screenName": "Primary-mrvwman-438728",
"role": "Presenter",
"streams": [
{
"type": "Presentation",
"uri": "pcast://phenixrts.com/us-southwest#us-west2-c.XfFVcxNg.20200205.PYIyIFS4?capabilities=multi-bitrate%2Cfhd",
"audioState": "TrackEnabled",
"videoState": "TrackEnabled"
}
],
"state": "Passive",
"lastUpdate": 1580913727128
}
]
}
{
"status" : "ok" ,
"members" : [
{
"sessionId" : "us-southwest#DpMPWP3YQu8dmJCN9Vfn2v" ,
"screenName" : "Primary-mrvwman-438728" ,
"role" : "Presenter" ,
"streams" : [
{
"type" : "Presentation" ,
"uri" : "pcast://phenixrts.com/us-southwest#us-west2-c.XfFVcxNg.20200205.PYIyIFS4?capabilities=multi-bitrate%2Cfhd" ,
"audioState" : "TrackEnabled" ,
"videoState" : "TrackEnabled"
}
] ,
"state" : "Passive" ,
"lastUpdate" : 1580913727128
}
]
}
Fetch Room Member API Status Codes
HTTP
Status
Retry
Description
200 OK
ok
never
Room members were successfully listed.
400 Bad Request
<varies>
never
Indicates an issue with the request.
401 Unauthorized
unauthorized
never
The streaming platform was not able to authorize the provided credentials.
404 Not Found
not found
never
The room was not found.
4XX
<varies>
never
Indicates an issue with the request.
503 Service Unavailable
capacity
once
The system is temporarily overloaded. Please try again later.
504 Gateway Timeout
rate-limited
once immediately, then exponential backoff
The system is temporarily overloaded. Please try again later.
504 Gateway Timeout
time-exceeded
once immediately, then exponential backoff
The request took to long to execute. Please try again later.
5XX
<varies>
once immediately, then exponential backoff
A transient server error.
Error Responses : Please be aware that some server errors 5XX and request validation errors 400 and 401 may result in an arbitrary response body not encoded in JSON.
Fetch Room Member API Response fields
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 .
Header
Description
Authorization (required)
Use HTTP Basic Authentication with your applicationId and secret
Response
The platform will return a successful response that contains a “status” field. The HTTP status code is set according to the “status” field.
HTTP / 1.1 200 OK
Content-Type : application/json; charset=utf-8
Content-Length : 830
{ "status" : "ok" , "rooms" :[{ "roomId" : "us-central#test#room1" , "alias" : "morningNews" , "applicationId" : "test" , "name" : "MorningNews" , "description" : "MorningNewsRoom-Chicago" , "type" : "MultiPartyChat" , "streamKey" : "mRq5pZFuQf21lDgLsip1KhNgXC1CVvzJqftZBOW5vX1Kq06YtosMYyeIppPCC41h34bO1NFBbk4f6YLCHXvGYBvX6UoGYwxL" , "created" : "2018-02-04T18:21:28.280000000Z" , "lastUpdate" : "2018-02-04T18:21:28.280000000Z" , "estimatedSize" : null , "options" :[]},{ "roomId" : "us-central#test#room2" , "alias" : "EveningNews" , "applicationId" : "test" , "name" : "EveningNews" , "description" : "EveningNewsRoom-Chicago" , "type" : "MultiPartyChat" , "streamKey" : "8oJgHdxCWht13CdBlmWev6BUm4D1hfiamsX0gpLNFaTCbJBN0Ty8jQiAa0mzmDuCA89AYYXjG8bp0pCFq3ehHFy1DJTbvGfr" , "created" : "2018-02-05T18:21:28.280000000Z" , "lastUpdate" : "2018-02-05T18:21:28.280000000Z" , "estimatedSize" : null , "options" :[]}]}
{
"status" : "ok" ,
"rooms" : [{
"roomId" : "us-central#test#room1" ,
"alias" : "morningNews" ,
"applicationId" : "test" ,
"name" : "Morning News" ,
"description" : "Morning News Room - Chicago" ,
"type" : "MultiPartyChat" ,
"streamKey" : "mRq5pZFuQf21lDgLsip1KhNgXC1CVvzJqftZBOW5vX1Kq06YtosMYyeIppPCC41h34bO1NFBbk4f6YLCHXvGYBvX6UoGYwxL" ,
"created" : "2018-02-04T18:21:28.280000000Z" ,
"lastUpdate" : "2018-02-04T18:21:28.280000000Z" ,
"estimatedSize" : null,
"options" : []
} ,{
"roomId" : "us-central#test#room2" ,
"alias" : "EveningNews" ,
"applicationId" : "test" ,
"name" : "Evening News" ,
"description" : "Evening News Room - Chicago" ,
"type" : "MultiPartyChat" ,
"streamKey" : "8oJgHdxCWht13CdBlmWev6BUm4D1hfiamsX0gpLNFaTCbJBN0Ty8jQiAa0mzmDuCA89AYYXjG8bp0pCFq3ehHFy1DJTbvGfr" ,
"created" : "2018-02-05T18:21:28.280000000Z" ,
"lastUpdate" : "2018-02-05T18:21:28.280000000Z" ,
"estimatedSize" : null,
"options" : []
}]
}
List Room API Status Codes
HTTP
Status
Retry
Description
200 OK
ok
never
Rooms were successfully listed.
400 Bad Request
<varies>
never
Indicates an issue with the request.
401 Unauthorized
unauthorized
never
The streaming platform was not able to authorize the provided credentials.
4XX
<varies>
never
Indicates an issue with the request.
503 Service Unavailable
capacity
once
The system is temporarily overloaded. Please try again later.
504 Gateway Timeout
rate-limited
once immediately, then exponential backoff
The system is temporarily overloaded. Please try again later.
5XX
<varies>
once immediately, then exponential backoff
A transient server error.
Error Responses : Please be aware that some server errors 5XX and request validation errors 400 and 401 may result in an arbitrary response body not encoded in JSON.
List Room API Response fields
Field
Description
status
See Status Codes .
rooms
Array of room objects. See Room fields . Please note that estimatedSize will always be null.
Deleting a Room
This API allows to delete rooms.
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
Encoding : Room ID may contain characters that are unsafe for URLs. Be sure to encode the RoomId in the URL path. For example, the URL encoding of `us-central#us-central` is `us-central%23us-central`
The Content-Length header is automatically populated by curl. If using another method to access the API, you must calculate and populate the Content-Length header.
Request URI
Component
Description
urlEncodedRoomId (required)
URL encoded ID of the room
Header
Description
Authorization (required)
Use HTTP Basic Authentication with your applicationId and secret
Response
The platform will return a successful response that contains a “status” field. The HTTP status code is set according to the “status” field.
HTTP / 1.1 200 OK
Content-Type : application/json; charset=utf-8
Content-Length : 15
{ "status" : "ok" }
{
"status" : "ok"
}
Delete Room API Status Codes
HTTP
Status
Retry
Description
200 OK
ok
never
Room was successfully deleted.
400 Bad Request
<varies>
never
Indicates an issue with the request.
401 Unauthorized
unauthorized
never
The streaming platform was not able to authorize the provided credentials.
4XX
<varies>
never
Indicates an issue with the request.
503 Service Unavailable
capacity
once
The system is temporarily overloaded. Please try again later.
504 Gateway Timeout
rate-limited
once immediately, then exponential backoff
The system is temporarily overloaded. Please try again later.
5XX
<varies>
once immediately, then exponential backoff
A transient server error.
Error Responses : Please be aware that some server errors 5XX and request validation errors 400 and 401 may result in an arbitrary response body not encoded in JSON.
Delete Room API Response fields
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": []
}'
Encoding : Room ID may contain characters that are unsafe for URLs. Be sure to encode the RoomId in the URL path. For example, the URL encoding of `us-central#us-central` is `us-central%23us-central`
The Content-length header is automatically populated by curl. If using another method to access the API, you must calculate and populate the Content-length header.
Request URI
Component
Description
urlEncodedSourceRoomId (required)
URL encoded Room ID of the source room to fork from.
urlEncodedDestinationRoomId (required)
URL encoded Room ID of the destination room to fork into.
Header
Description
Authorization (required)
Use HTTP Basic Authentication with your applicationId and secret
Request Fields
Field
Description
streamTags (optional)
An array of tags (strings) to apply to the destination streams.
streamCapabilities (optional)
An array of capabilities (strings) to apply to the newly forked stream.
options (optional)
An array of options (strings) for the room. Current valid options are: “force”, “additive” and “keep-streams”. The default behavior is not touch the stream(s) with matching session IDs that are already publishing to the destination channel. With the “force” option, the stream(s) will be terminated and replaced. With the “additive” option, the stream(s) will be added to any existing members in the room. “keep-streams” removes the members but leaves the streams alive. Clients will receive the member update, but they are not securely terminated from the stream. In Phenix client implementations the default is to end the client stream, but customer client implementations may vary.
Response
The API call returns an HTTP response per the following:
HTTP/2 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 623
{
"status": "ok",
"members": [
{
"sessionId": "us-southwest#DpMPWP3YQu8dmJCN9Vfn2v",
"screenName": "Primary-mrvwman-438728",
"role": "Presenter",
"streams": [
{
"type": "Presentation",
"uri": "pcast://phenixrts.com/us-southwest#us-west2-c.XfFVcxNg.20200205.PYIyIFS4?capabilities=multi-bitrate%2Cfhd",
"audioState": "TrackEnabled",
"videoState": "TrackEnabled"
}
],
"state": "Passive",
"lastUpdate": 1580913727128
}
]
}
{
"status" : "ok" ,
"members" : [
{
"sessionId" : "us-southwest#DpMPWP3YQu8dmJCN9Vfn2v" ,
"screenName" : "Primary-mrvwman-438728" ,
"role" : "Presenter" ,
"streams" : [
{
"type" : "Presentation" ,
"uri" : "pcast://phenixrts.com/us-southwest#us-west2-c.XfFVcxNg.20200205.PYIyIFS4?capabilities=multi-bitrate%2Cfhd" ,
"audioState" : "TrackEnabled" ,
"videoState" : "TrackEnabled"
}
] ,
"state" : "Passive" ,
"lastUpdate" : 1580913727128
}
]
}
Fork Room API Status Codes
HTTP
Status
Retry
Description
200 OK
ok
never
Room was successfully forked.
400 Bad Request
<varies>
never
Indicates an issue with the request. Eg: Options must be an array of strings.
401 Unauthorized
unauthorized
never
The streaming platform was not able to authorize the provided credentials.
404 Not Found
not found
never
One or both of the source and destination rooms are not found.
4XX
<varies>
never
Indicates an issue with the request.
503 Service Unavailable
capacity
once
The system is temporarily overloaded. Please try again later.
504 Gateway Timeout
rate-limited
once immediately, then exponential backoff
The system is temporarily overloaded. Please try again later.
504 Gateway Timeout
time-exceeded
once immediately, then exponential backoff
The request took to long to execute. Please try again later.
5XX
<varies>
once immediately, then exponential backoff
A transient server error.
Error Responses : Please be aware that some server errors 5XX and request validation errors 400 and 401 may result in an arbitrary response body not encoded in JSON.
Fork Room API Response fields
Field
Description
status
See Status Codes .
members
Array of session objects that have been forked.
Kill a Room
This API allows the caller to remove all the publishers and terminate the corresponding streams within the specified room.
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": []
}'
Encoding : Room ID may contain characters that are unsafe for URLs. Be sure to encode the RoomId in the URL path. For example, the URL encoding of `us-central#us-central` is `us-central%23us-central`
The Content-length header is automatically populated by curl. If using another method to access the API, you must calculate and populate the Content-length header.
Request URI
Component
Description
urlEncodedRoomId (required)
ID of the room to kill.
Header
Description
Authorization (required)
Use HTTP Basic Authentication with your applicationId and secret
Request Fields
Field
Description
reason (optional)
Arbitrary text string for recording why the stream was killed.
options (optional)
An array of options (strings). Valid options are: “keep-streams”. “keep-streams” removes the members but leaves the streams alive. Clients will receive the member update, but they are not securely terminated from the stream. In Phenix client implementations the default is to end the client stream, but customer client implementations may vary.
Response
The API call returns an HTTP response per the following:
HTTP/2 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 648
{
"status": "ok",
"killedMembers": [
{
"sessionId": "us-southwest#DpMPWP3YQu8dmJCN9Vfn2v",
"screenName": "Primary-mrvwman-438728",
"role": "Presenter",
"streams": [
{
"type": "Presentation",
"uri": "pcast://phenixrts.com/us-southwest#us-west2-c.XfFVcxNg.20200205.PYIyIFS4?capabilities=multi-bitrate%2Cfhd",
"audioState": "TrackEnabled",
"videoState": "TrackEnabled"
}
],
"state": "Passive",
"lastUpdate": 1580913727128
}
]
}
{
"status" : "ok" ,
"killedMembers" : [
{
"sessionId" : "us-southwest#DpMPWP3YQu8dmJCN9Vfn2v" ,
"screenName" : "Primary-mrvwman-438728" ,
"role" : "Presenter" ,
"streams" : [
{
"type" : "Presentation" ,
"uri" : "pcast://phenixrts.com/us-southwest#us-west2-c.XfFVcxNg.20200205.PYIyIFS4?capabilities=multi-bitrate%2Cfhd" ,
"audioState" : "TrackEnabled" ,
"videoState" : "TrackEnabled"
}
] ,
"state" : "Passive" ,
"lastUpdate" : 1580913727128
}
]
}
Kill Room API Status Codes
HTTP
Status
Retry
Description
200 OK
ok
never
Room was successfully killed.
400 Bad Request
<varies>
never
Indicates an issue with the request. Eg: Options must be an array of strings.
401 Unauthorized
unauthorized
never
The streaming platform was not able to authorize the provided credentials or Field “reason” must be a string.
404 Not Found
not found
never
The room was not found.
4XX
<varies>
never
Indicates an issue with the request.
503 Service Unavailable
capacity
once
The system is temporarily overloaded. Please try again later.
504 Gateway Timeout
rate-limited
once immediately, then exponential backoff
The system is temporarily overloaded. Please try again later.
504 Gateway Timeout
time-exceeded
once immediately, then exponential backoff
The request took to long to execute. Please try again later.
5XX
<varies>
once immediately, then exponential backoff
A transient server error while processing the request.
Error Responses : Please be aware that some server errors 5XX and request validation errors 400 and 401 may result in an arbitrary response body not encoded in JSON.
Kill Room API Response fields
Field
Description
status
See Status Codes .
killedMembers
Array of session objects that have been killed.
Checking the State of a Room
This API allows to check the number of publishers in a room. This can be used to verify the health of ingests, e.g. redundant RTMP ingests.
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
Encoding : Room ID may contain characters that are unsafe for URLs. Be sure to encode the RoomId in the URL path. For example, the URL encoding of `us-central#us-central` is `us-central%23us-central`
The Content-Length header is automatically populated by curl. If using another method to access the API, you must calculate and populate the Content-Length header.
Request URI
Component
Description
urlEncodedRoomId (required)
URL encoded ID of the room
Request URI Parameters
Parameter
Description
failIfLess (optional)
The number of required publishers that meet all criteria for the room.
withStreams (optional)
The number of streams required per publisher to be considered active in the room. Defaults to 1.
withScreenName (optional)
Only consider publishers with the given screen name. By default all screen names are considered.
Response
The platform will return a successful response that contains a “status” field. The HTTP status code is set according to the “status” field.
HTTP / 1.1 200 OK
Content-Type : application/json; charset=utf-8
Content-Length : 1
1
1
Health Room API Status Codes
HTTP
Status
Retry
Description
200 OK
ok
never
Number of publishers was successfully reported.
400 Bad Request
never
Indicates an issue with the request.
404 Not Found
not-found
never
Indicates the channel was not found.
4XX
never
Indicates an issue with the request.
412 Precondition Failed
never
There is fewer than the required number of publishers.
503 Service Unavailable
capacity
once
The system is temporarily overloaded. Please try again later.
504 Gateway Timeout
rate-limited
once immediately, then exponential backoff
The system is temporarily overloaded. Please try again later.
504 Gateway Timeout
time-exceeded
once immediately, then exponential backoff
The request took to long to execute. Please try again later.
5XX
once immediately, then exponential backoff
A transient server error.
Error Responses : Please be aware that some server errors 5XX and request validation errors 400 and 401 may result in an arbitrary response body not encoded in JSON.
Room API Response fields
The response body is a text field with the number of publishers actively publishing a stream to the room.
Universal Live Manifest for a Room
This API allows to retrieve a live manifest of any type for a room. The URL is valid for the lifetime of the room and always points to the most recent stream in the room. In order for this to work, the stream must have enabled streaming
capability.
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
Encoding : Room ID may contain characters that are unsafe for URLs. Be sure to encode the RoomId in the URL path. For example, the URL encoding of `us-central#us-central` is `us-central%23us-central`
The Content-Length header is automatically populated by curl. If using another method to access the API, you must calculate and populate the Content-Length header.
Request URI
Component
Description
urlEncodedRoomId (required)
URL encoded ID of the room
manifest (required)
The manifest ID such as live.m3u8 for HLS and live.mpd for DASH.
Request URI Parameters
Parameter
Description
streamToken (optional)
Streams protected with token-auth
require a valid edge auth token to be provided. An edge auth token issued for the room ID or alias will grant access to the playlist for the room. Alternatively, if the origin stream ID is known, access can be restricted to just a stream itself.
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
#EXTM 3 U
#EXT-X-STREAM-INF : PROGRAM-ID= 1 , CODECS= "avc1.42c01f,mp4a.40.2" , BANDWIDTH= 1728000 , AVERAGE-BANDWIDTH= 1728000 , FRAME-RATE= 30
live -720 .m 3 u 8
#EXT-X-STREAM-INF : PROGRAM-ID= 1 , CODECS= "avc1.42c01f,mp4a.40.2" , BANDWIDTH= 958000 , AVERAGE-BANDWIDTH= 958000 , FRAME-RATE= 30
live -480 .m 3 u 8
#EXT-X-STREAM-INF : PROGRAM-ID= 1 , CODECS= "avc1.42c01f,mp4a.40.2" , BANDWIDTH= 584000 , AVERAGE-BANDWIDTH= 584000 , FRAME-RATE= 15
live -360 .m 3 u 8
#EXT-X-STREAM-INF : PROGRAM-ID= 1 , CODECS= "avc1.42c01f,mp4a.40.2" , BANDWIDTH= 414000 , AVERAGE-BANDWIDTH= 414000 , FRAME-RATE= 15
live -240 .m 3 u 8
#EXT-X-STREAM-INF : PROGRAM-ID= 1 , CODECS= "avc1.42c01e,mp4a.40.2" , BANDWIDTH= 144000 , AVERAGE-BANDWIDTH= 144000 , FRAME-RATE= 15
live -144 .m 3 u 8
#EXT-X-STREAM-INF : PROGRAM-ID= 1 , CODECS= "mp4a.40.2" , BANDWIDTH= 128000 , AVERAGE-BANDWIDTH= 128000 , FRAME-RATE= 0
live-ahi.m 3 u 8
#EXT-X-STREAM-INF : PROGRAM-ID= 1 , CODECS= "mp4a.40.2" , BANDWIDTH= 64000 , AVERAGE-BANDWIDTH= 64000 , FRAME-RATE= 0
live-alo.m 3 u 8
Found. Redirecting to /video/<applicationId>/<streamId>/live.m3u8
Manifest Room API Status Codes
HTTP
Status
Retry
Description
302 Found
never
The manifest was successfully located and a redirect URL is provided.
400 Bad Request
never
Indicates an issue with the request.
404 Not Found
not found
never
Indicates the channel or the manifest was not found.
415 Unsupported Media Type
never
The channel does not support streaming
.
4XX
never
Indicates an issue with the request.
503 Service Unavailable
capacity
once
The system is temporarily overloaded. Please try again later.
504 Gateway Timeout
rate-limited
once immediately, then exponential backoff
The system is temporarily overloaded. Please try again later.
504 Gateway Timeout
time-exceeded
once immediately, then exponential backoff
The request took to long to execute. Please try again later.
5XX
once immediately, then exponential backoff
A transient server error.
Manifest Room API Response fields
The response is redirecting to the manifest file via a standard HTTP redirect response (302).
Sending a Message
This API allows to send a message.
Request
Send a PUT
request to the /pcast/room/<urlEncodedRoomId>/message
endpoint as shown:
PUT /pcast/room/<urlEncodedRoomId>/message HTTP / 1.1
Host : pcast.phenixrts.com
Accept : application/json
Authorization : Basic YXBwbGljYXRpb25JZDpzZWNyZXQ=
Content-Type : application/json
Content-Length : 267
{
"message" : {
"from" : {
"screenName" : "Screen Name" ,
"role" : "Moderator" ,
"lastUpdate" : 0
},
"mimeType" : "text/plain" ,
"message" : "My message" ,
"tags" : [ "my-tag" , "my-other-tag" ]
}
}
$ curl https://pcast.phenixrts.com/pcast/room/<urlEncodedRoomId>/message \
-u applicationId:secret \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-X PUT \
-d '{
"message": {
"from": {
"screenName": "Screen Name",
"role": "Moderator",
"lastUpdate": 0
},
"mimeType": "text/plain",
"message": "My message",
"tags": ["my-tag", "my-other-tag"]
}
}'
Encoding : Room ID may contain characters that are unsafe for URLs. Be sure to encode the RoomId in the URL path. For example, the URL encoding of `us-central#us-central` is `us-central%23us-central`
The Content-Length header is automatically populated by curl. If using another method to access the API, you must calculate and populate the Content-Length header.
Header
Description
Authorization (required)
Use HTTP Basic Authentication with your applicationId and secret
Request Fields
Message Object
Field
Description
from (required)
User Object representing the sender of the message.
mimeType (required)
The mime type of the content.
message (required)
The message. Binary messages should be base64 encoded.
tags (required)
An array of tags for the message.
User Object
Field
Description
sessionId (optional)
The session ID of the user.
screenName (required)
The screen name of the user.
role (required)
The role of the user. Valid values are: Participant, Moderator, Presenter, and Audience.
lastUpdate (required)
The last update of the user as a UNIX timestamp.
Response
The platform will return a successful response that contains a “status” field. The HTTP status code is set according to the “status” field.
HTTP / 1.1 200 OK
Content-Type : application/json; charset=utf-8
Content-Length : 310
{ "status" : "ok" , "message" :{ "messageId" : "us-central#room|test#testing.xV1OVWEkOxZm|0000000009" , "timestamp" : 1596088080439 , "deletedTimestamp" : 0 , "from" :{ "sessionId" : "api" , "screenName" : "Screen Name" , "role" : "Moderator" , "lastUpdate" : 0 }, "mimeType" : "text/plain" , "message" : "My message" , "tags" :[ "my-tag" , "my-other-tag" ]}}
{
"status" : "ok" ,
"message" : {
"messageId" : "us-central#room|test#testing.xV1OVWEkOxZm|0000000009" ,
"timestamp" : 1596088080439,
"deletedTimestamp" : 0,
"from" : {
"sessionId" : "api" ,
"screenName" : "Screen Name" ,
"role" : "Moderator" ,
"lastUpdate" : 0
} ,
"mimeType" : "text/plain" ,
"message" : "My message" ,
"tags" : [
"my-tag" ,
"my-other-tag"
]
}
}
Send Room Message API Status Codes
HTTP
Status
Retry
Description
200 OK
ok
never
Message has been successfully sent.
400 Bad Request
<varies>
never
Indicates an issue with the request.
401 Unauthorized
unauthorized
never
The streaming platform was not able to authorize the provided credentials.
404 Not Found
not-found
never
The room does not exist.
413 Payload Too Large
<varies>
never
One of the fields exceeds the limits. The size limit for messages is 1024 bytes. The total limit for all tags is 512 bytes. The screen name and mime type each must not exceed 128 bytes.
4XX
<varies>
never
Indicates an issue with the request.
503 Service Unavailable
capacity
once
The system is temporarily overloaded. Please try again later.
504 Gateway Timeout
rate-limited
once immediately, then exponential backoff
The system is temporarily overloaded. Please try again later.
5XX
<varies>
once immediately, then exponential backoff
A transient server error.
Error Responses : Please be aware that some server errors 5XX and request validation errors 400 and 401 may result in an arbitrary response body not encoded in JSON.
Send Room Message API Response fields
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
Encoding : Room ID may contain characters that are unsafe for URLs. Be sure to encode the RoomId in the URL path. For example, the URL encoding of `us-central#us-central` is `us-central%23us-central`
Header
Description
Authorization (required)
Use HTTP Basic Authentication with your applicationId and secret
Request URI Parameters
Parameter
Description
limit (optional)
The number of messages to fetch. Defaults to 100.
beforeMessageId (optional)
The upper bound of the fetch range represented by another message ID.
afterMessageId (optional)
The lower bound of the fetch range represented by another message ID.
mimeTypes (optional)
Comma separated list of mime types. When provided only messages with the specified mime types will be returned. Note the search range is still the same so if no messages within the underlying range match then the result might be zero or less than the requested limit.
Response
The platform will return a successful response that contains a “status” field. The HTTP status code is set according to the “status” field.
HTTP / 1.1 200 OK
Content-Type : application/json; charset=utf-8
Content-Length : 395echo
{ "status" : "ok" , "messages" :[{ "messageId" : "us-central#room|test#testing.xV1OVWEkOxZm|0000000243" , "timestamp" : 1596089241062 , "deletedTimestamp" : 0 , "from" :{ "sessionId" : "local#IrGTKf0ztwN3H5xORrtD9e" , "screenName" : "ScreenName58611" , "role" : "Participant" , "lastUpdate" : 1596089235915 }, "mimeType" : "text/plain" , "message" : "Test message 240:1596089241045" , "tags" :[]}], "hasMoreBefore" : false , "hasMoreAfter" : false }
{
"status" : "ok" ,
"messages" : [
{
"messageId" : "us-central#room|test#testing.xV1OVWEkOxZm|0000000243" ,
"timestamp" : 1596089241062,
"deletedTimestamp" : 0,
"from" : {
"sessionId" : "local#IrGTKf0ztwN3H5xORrtD9e" ,
"screenName" : "ScreenName58611" ,
"role" : "Participant" ,
"lastUpdate" : 1596089235915
} ,
"mimeType" : "text/plain" ,
"message" : "Test message 240:1596089241045" ,
"tags" : []
}
] ,
"hasMoreBefore" : false ,
"hasMoreAfter" : false
}
Fetch Room Messages API Status Codes
HTTP
Status
Retry
Description
200 OK
ok
never
Messages have been successfully fetched.
400 Bad Request
<varies>
never
Indicates an issue with the request.
401 Unauthorized
unauthorized
never
The streaming platform was not able to authorize the provided credentials.
404 Not Found
not-found
never
The room does not exist.
413 Payload Too Large
limit-too-large
never
Too many messages are requested. The maximal limit is 128 messages per request.
4XX
<varies>
never
Indicates an issue with the request.
503 Service Unavailable
capacity
once
The system is temporarily overloaded. Please try again later.
504 Gateway Timeout
rate-limited
once immediately, then exponential backoff
The system is temporarily overloaded. Please try again later.
5XX
<varies>
once immediately, then exponential backoff
A transient server error.
Error Responses : Please be aware that some server errors 5XX and request validation errors 400 and 401 may result in an arbitrary response body not encoded in JSON.
Fetch Room Messages API Response fields
Field
Description
status
See Status Codes
messages
Array of Message Object
hasMoreBefore
A boolean flag indicating if there is potentially more messages before the returned range.
hasMoreAfter
A boolean flag indicating if there is potentially more messages after the returned range.
Purging Messages of a Room
This API allows to purge all messages of a room. By default, room messages are retained for 90 days.
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
Encoding : Room ID may contain characters that are unsafe for URLs. Be sure to encode the RoomId in the URL path. For example, the URL encoding of `us-central#us-central` is `us-central%23us-central`
The Content-Length header is automatically populated by curl. If using another method to access the API, you must calculate and populate the Content-Length header.
Request URI
Component
Description
urlEncodedRoomId (required)
URL encoded ID of the room
Header
Description
Authorization (required)
Use HTTP Basic Authentication with your applicationId and secret
Response
The platform will return a successful response that contains a “status” field. The HTTP status code is set according to the “status” field.
HTTP / 1.1 200 OK
Content-Type : application/json; charset=utf-8
Content-Length : 32
{ "status" : "ok" , "deletedCount" : 1 }
{
"status" : "ok" ,
"deletedCount" : 1
}
Purge Room Messages API Status Codes
HTTP
Status
Retry
Description
200 OK
ok
never
Room was successfully deleted.
400 Bad Request
<varies>
never
Indicates an issue with the request.
401 Unauthorized
unauthorized
never
The streaming platform was not able to authorize the provided credentials.
404 Not Found
not-found
never
The room does not exist.
4XX
<varies>
never
Indicates an issue with the request.
503 Service Unavailable
capacity
once
The system is temporarily overloaded. Please try again later.
504 Gateway Timeout
rate-limited
once immediately, then exponential backoff
The system is temporarily overloaded. Please try again later.
5XX
<varies>
once immediately, then exponential backoff
A transient server error.
Error Responses : Please be aware that some server errors 5XX and request validation errors 400 and 401 may result in an arbitrary response body not encoded in JSON.
Purge Room Messages API Response fields
Field
Description
status
See Status Codes
deletedCount
The number of deleted messages.
Stream API
APIs for streams let you publish, subscribe, destroy and manage streams. In addition, the APIs let you create and fetch replays.
Publishing a URI
This API allows to publish a stream from a URI.
Request
Send a PUT
request to the pcast/:tenancy/stream/publish/uri/:type
endpoint as shown:
PUT pcast/<applicationId>/stream/publish/uri/<type> HTTP / 1.1
Authorization : Bearer <edgeAuthToken>
Host : pcast.phenixrts.com
Accept : application/json
Content-Type : application/json
{
"uri" : "<uri>" ,
"options" : [ <options> ]
}
$ curl https://pcast.phenixrts.com/pcast/<applicationId>/stream/publish/uri/<type > \
-H "Authorization: Bearer <edgeAuthToken>" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-X PUT \
-d '{
"uri": "<uri>",
"options": [<options>]
}'
Header
Description
Authorization (required)
Use Bearer authentication with a EdgeAuthToken
Request URI
Component
Description
applicationId (required)
The application ID that the request belongs to
type (required)
The remote URI type such as mp4, m3u8, udp, srt,…
Request Fields
Field
Description
uri (required)
The URI to publish such as srt://103.19.109.140:4201
options (optional)
For future use
Send a POST
request to the pcast/:tenancy/stream/publish/uri/:type endpoint as shown:
POST pcast/<applicationId>/stream/publish/uri/<type> HTTP / 1.1
Host : pcast.phenixrts.com
Accept : application/json
Content-Type : multipart/form-data
{
"edgeAuthToken": "<edgeAuthToken>",
"uri": "<uri>",
"options": [<options>]
}
$ curl https://pcast.phenixrts.com/pcast/<applicationId>/stream/publish/uri/<type > \
-H "Accept: application/json" \
-H "Content-Type: multipart/form-data" \
-X POST \
-F jsonBody = '{
"edgeAuthToken": "<edgeAuthToken>",
"uri": "<uri>",
"options": [<options>]
}'
Request URI
Component
Description
applicationId (required)
The application ID that the request belongs to
type (required)
The remote URI type such as mp4, m3u8, udp, srt,…
Request Fields
Field
Description
edgeAuthToken (required)
EdgeAuthToken used to connect and authenticate to the platform and publish the stream
uri (required)
The URI to publish such as srt://73.103.226.97:4201
options (optional)
For future use
Response
The platform will return a successful response that contains a “status” field. The HTTP status code is set according to the “status” field.
HTTP / 1.1 200 OK
Content-Type : application/json; charset=utf-8
Content-Length : 518
{ "status" : "ok" , "streamId" : "us-central#us-central1-c.K3hpFbOX.20210913.I9LYKcSz" , "sharedSecret" : "DIGEST:eyJhcHBsaWNhdGlvbklkIjoiZGVtbyIsImRpZ2VzdCI6ImlkdG5oVjc2WEFseUsxSWdNTFJMbkdET01CLzhzdE84N0JEUkNKNkdzNjZzNmFPeEJ5a3RlQzVuU09LSlVUWWxqVGpVdHRJVnphcHJHdlg4THgxUkRBPT0iLCJ0b2tlbiI6IntcInN0cmVhbUlkXCI6XCJldXJvcGUtd2VzdCNldXJvcGUtd2VzdDEtYi40NU9EMDdaQS4yMDIxMDkxNS5JRVp3YTdmeFwiLFwiaW5zdGFuY2VSb3V0ZUtleVwiOlwidW5pY2FzdC5ldXJvcGUtd2VzdC5ldXJvcGUtd2VzdDEtYi40NU9EMDdaQVwiLFwiZXhwaXJlc1wiOjE2MzIzMDM1NDAzNDl9In0=" , "options" :[]} ```
{
"status" : "ok" ,
"streamId" : "us-central#us-central1-c.K3hpFbOX.20210913.I9LYKcSz" ,
"sharedSecret" : "DIGEST:eyJhcHBsaWNhdGlvbklkIjoiZGVtbyIsImRpZ2VzdCI6ImlkdG5oVjc2WEFseUsxSWdNTFJMbkdET01CLzhzdE84N0JEUkNKNkdzNjZzNmFPeEJ5a3RlQzVuU09LSlVUWWxqVGpVdHRJVnphcHJHdlg4THgxUkRBPT0iLCJ0b2tlbiI6IntcInN0cmVhbUlkXCI6XCJldXJvcGUtd2VzdCNldXJvcGUtd2VzdDEtYi40NU9EMDdaQS4yMDIxMDkxNS5JRVp3YTdmeFwiLFwiaW5zdGFuY2VSb3V0ZUtleVwiOlwidW5pY2FzdC5ldXJvcGUtd2VzdC5ldXJvcGUtd2VzdDEtYi40NU9EMDdaQVwiLFwiZXhwaXJlc1wiOjE2MzIzMDM1NDAzNDl9In0=" ,
"options" : []
}
Publish URI API Status Codes
HTTP
Status
Retry
Description
200 OK
ok
never
Stream has been successfully published.
400 Bad Request
<varies>
never
Indicates an issue with the request.
401 Unauthorized
unauthorized
never
The streaming platform was not able to authorize the provided credentials.
402 Unauthorized
geo-restricted
never
The access to the content is geo-restricted.
403 Unauthorized
geo-blocked
never
The access to the content is geo-blocked.
409 Conflict
conflicting-capability
never
Ingest capabilities are conflicting. Only one must be specified at a time.
415 Unsupported Media Type
invalid-source-uri
never
The URI to publish is not a valid URI.
4XX
<varies>
never
Indicates an issue with the request.
503 Service Unavailable
capacity
once
The system is temporarily overloaded. Please try again later.
504 Gateway Timeout
rate-limited
once immediately, then exponential backoff
The system is temporarily overloaded. Please try again later.
5XX
<varies>
once immediately, then exponential backoff
A transient server error.
Error Responses : Please be aware that some server errors 5XX and request validation errors 400 and 401 may result in an arbitrary response body not encoded in JSON.
Publish URI API Response fields
Field
Description
status
See Status Codes
streamId
The stream ID of the ingest stream
sharedSecret
The shared secret used in follow on operations on the stream
options
For future use
Fetching a Replay Manifest
This API allows to create and fetch replay manifests.
Request
Send a Get
request to the /pcast/:tenancy/stream/replay/:type.m3u8
endpoint as shown:
GET /pcast/:tenancy/stream/replay/:type.m3u8?edgeAuthToken=<edgeAuthToken>&startTime=<startTime>&endTime=<endTime> HTTP / 1.1
Host : pcast.phenixrts.com
Accept : application/json
$ curl https://pcast.phenixrts.com/pcast/<applicationId>/stream/replay/primary.m3u8?edgeAuthToken= <edgeAuthToken>&startTime= <startTime>&endTime= <endTime> \
-x GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
Request URI
Component
Description
applicationId (required)
The application ID that the request belongs to.
type (required)
The manifest type such as primary.m3u8 for for primary manifest or xhd.m3u8 for quality manifest.
Request Parameters
Field
Description
edgeAuthToken (required)
EdgeAuthToken used to connect and authenticate to the platform and subscribe to a stream
startTime (required)
The date, formatted as ‘yyyy-MM-dd’T'HH:mm:ss.SSS'Z’‘, from which replay should start
endTime (required)
The date, formatted as 'yyyy-MM-dd’T'HH:mm:ss.SSS'Z’‘, until which replay should last
apiVersion (optional)
The API version the message conforms to. Default to '0’
httpRoundTripTime (optional)
The round trip time
Response
The platform will return a successful response that contains a playlist manifest. Or it will return error object with status on failure.
Success response example for primary manifest
HTTP / 1.1 200 OK
Content-Type : application/vnd.apple.mpegurl; charset=utf-8
Content-Length : 427
#EXTM3U
#EXT-X-STREAM-INF:PROGRAM-ID=1,RESOLUTION=1920x1080,CODECS="avc1.640029,mp4a.40.2",BANDWIDTH=5628000,AVERAGE-BANDWIDTH=5628000,FRAME-RATE=30
xhd.m3u8?tenancy=test&edgeAuthToken=DIGEST%3AeyJhcHBsaWNhdGlvbklkIjoidGVzdCIsImRpZ2VzdCI6IjFuUU90ZnpKTmwwRUVLaHVBWGE4YWd0RGNNaGdGbEhTbksyRElsNTlTS0RTZ2xlUjc3c3NpTmRQcGdhMnZYVEhuSEJCdWIwQmdYRTQ2a3ZvbmNBcmFBPT0iLCJ0b2tlbiI6IntcImV4cGlyZXNcIjoxOTQ0MjE2MDAwMDAwLFwiY2FwYWJpbGl0aWVzXCI6W1wicmVwbGF5XCJdLFwib3JpZ2luU3RyZWFtSWRcIjpcImxvY2FsI3N0YW5kYWxvbmUuVFpkcnkwdjcuMjAyMTA5MTQuUFN5V1E2dk1cIixcInJlcXVpcmVkVGFnXCI6XCJyb29tSWQ6bG9jYWwjdGVzdCN0ZXN0Q2hhbm5lbC40UjBsVHU5Y1o3NjNcIn0ifQ%3D%3D&startTime=Tue+Sep+14+2021+08%3A05%3A52+GMT%2B0000&endTime=Tue+Sep+14+2021+08%3A06%3A02+GMT%2B0000&options=
...
#EXTM3U
#EXT-X-STREAM-INF:PROGRAM-ID=1,RESOLUTION=1920x1080,CODECS="avc1.640029,mp4a.40.2",BANDWIDTH=5628000,AVERAGE-BANDWIDTH=5628000,FRAME-RATE=30
xhd.m3u8?tenancy= test &edgeAuthToken= DIGEST%3AeyJhcHBsaWNhdGlvbklkIjoidGVzdCIsImRpZ2VzdCI6IjFuUU90ZnpKTmwwRUVLaHVBWGE4YWd0RGNNaGdGbEhTbksyRElsNTlTS0RTZ2xlUjc3c3NpTmRQcGdhMnZYVEhuSEJCdWIwQmdYRTQ2a3ZvbmNBcmFBPT0iLCJ0b2tlbiI6IntcImV4cGlyZXNcIjoxOTQ0MjE2MDAwMDAwLFwiY2FwYWJpbGl0aWVzXCI6W1wicmVwbGF5XCJdLFwib3JpZ2luU3RyZWFtSWRcIjpcImxvY2FsI3N0YW5kYWxvbmUuVFpkcnkwdjcuMjAyMTA5MTQuUFN5V1E2dk1cIixcInJlcXVpcmVkVGFnXCI6XCJyb29tSWQ6bG9jYWwjdGVzdCN0ZXN0Q2hhbm5lbC40UjBsVHU5Y1o3NjNcIn0ifQ%3D%3D&startTime= Tue+Sep+14+2021+08%3A05%3A52+GMT%2B0000&endTime= Tue+Sep+14+2021+08%3A06%3A02+GMT%2B0000&options=
Replay Manifest API Status Codes
HTTP
Status
Retry
Description
200 OK
ok
never
Channel has been successfully created.
400 Bad Request
<varies>
never
Indicates an issue with the request.
401 Unauthorized
unauthorized
never
The streaming platform was not able to authorize the provided credentials.
402 Unauthorized
geo-restricted
never
The access to the content is geo-restricted.
403 Unauthorized
geo-blocked
never
The access to the content is geo-blocked.
408 Request Timeout
request-timeout
once immediately, then exponential backoff
Request timed out likely due to temporary resource or network conditions. Please try again.
4XX
<varies>
never
Indicates an issue with the request.
503 Service Unavailable
capacity
once
The system is temporarily overloaded. Please try again later.
504 Gateway Timeout
rate-limited
once immediately, then exponential backoff
The system is temporarily overloaded. Please try again later.
5XX
<varies>
once immediately, then exponential backoff
A transient server error.
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>"]
}
}'
The Content-Length header is automatically populated by curl. If using another method to access the API, you must calculate and populate the Content-Length header.
Request Fields
Field
Description
composition (required)
See Composition object below
tags (optional)
Tags for the Composition stream
credentials (optional)
The preferred way of passing the credentials is with HTTP authentication header . Alternatively they can be passed in the request body .
Composition Object
Field
Description
type (required)
Type of composition that need to be applied. See Composition types below.
streams (required)
Array of streams that need to be composed. See Stream Object below.
capabilities
See Composition Capabilities below
Composition Types
Field
Description
PictureInPicture
Main stream is displayed on the full screen and other streams are displayed in inset windows. The main stream is the first stream of all streams.
Stream Object
Field
Description
streamId (required)
The stream ID of the the input.
offset (optional)
The offset of the input video relative to the composition canvas. See Offset Object below.
width (optional)
The width of the input on the composition canvas.
height (optional)
The height of the input on the composition canvas.
Offset Object
Field
Description
anchor (optional)
The anchor for the offset. See Anchor Object below.
x (optional)
The horizontal offset relative to the anchor.
y (optional)
The vertical offset relative to the anchor.
Anchor Object
Value
Description
TopLeft
Anchor relative to top left corner.
TopRight
Anchor relative to top right corner.
BottomLeft
Anchor relative to bottom left corner.
BottomRight
Anchor relative to bottom right corner.
Center
Anchor relative to the center.
Composition Capabilities
Value
Description
prefer-h264
Output H.264 stream if possible
prefer-vp8
Output VP8 stream if possible
multi-bitrate
Multi bitrate stream
multi-bitrate-codec=vp8
Multi bitrate VP8 stream
multi-bitrate-codec=h264
Multi bitrate H.264 stream
uld
Output Ultra low definition - 80kbps stream
vld
Output Very low definition - 350kbps stream
ld
Output Low definition - 520kbps stream
sd
Output Standard definition - 830kbps - default stream
hd
Output High definition - 1600kbps stream
fhd
Output Full high definition - 3000kbps stream
xhd
Output Extended high definition - 5500kbps stream
uhd
Output Ultra high definition - 8500kbps stream
Response
The platform will return a successful response that contains a “status” field. The HTTP status code is set according to the “status” field.
HTTP / 1.1 200 OK
Content-Type : application/json; charset=utf-8
Content-Length : 85
{ "status" : "ok" , "compositionId" : "us-central#us-central1-c.8q9rSY86.20180412.CCiaENCV" }
{
"status" :"ok" ,
"compositionId" :"us-central#us-central1-c.8q9rSY86.20180412.CCiaENCV"
}
Create Composition API Response fields
Field
Description
status
See status codes below
compositionId
ID of the composed stream
Create Composition API Status Codes
HTTP
Status
Retry
Description
200 OK
ok
never
Composition was successfully created.
400 Bad Request
<varies>
never
Indicates an issue with the request.
401 Unauthorized
unauthorized
never
The streaming platform was not able to authorize the provided credentials.
4XX
<varies>
never
Indicates an issue with the request.
503 Service Unavailable
capacity
once
The system is temporarily overloaded. Please try again later.
5XX
<varies>
once immediately, then exponential backoff
A transient server error.
Error Responses : Please be aware that some server errors 5XX and request validation errors 400 and 401 may result in an arbitrary response body not encoded in JSON.
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>"
}
]
}'
The Content-Length header is automatically populated by curl. If using another method to access the API, you must calculate and populate the Content-Length header.
Request 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.
Error Responses : Please be aware that some server errors 5XX and request validation errors 400 and 401 may result in an arbitrary response body not encoded in JSON.
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>"
}'
Encoding : Composition ID may contain characters that are unsafe for URLs. Be sure to encode the CompositionlId in the URL path. For example, the URL encoding of `us-central#us-central` is `us-central%23us-central`
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.
Error Responses : Please be aware that some server errors 5XX and request validation errors 400 and 401 may result in an arbitrary response body not encoded in JSON.
Start Transcoding
This API allows for transcoding an ongoing stream.
Request
Send a POST
request to /pcast/transcoding
endpoint as shown:
POST /pcast/transcoding HTTP / 1.1
Host : pcast.phenixrts.com
Accept : application/json
Content-Type : application/json
Content-Length : 210
Authorization : Basic YXBwbGljYXRpb25JZDpzZWNyZXQ=
{
"transcoding" : {
"type" : "DASH" ,
"originStreamId" : "<streamId>" ,
"onDemand" : true ,
"audioOnly" : false ,
"quality" : "hd" ,
"tags" : [ "<tag1>" , "<tag2>" ]
}
}
$ curl https://pcast.phenixrts.com/pcast/transcoding \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Content-Length: 210" \
-u applicationId:secret \
-X PUT \
-d '{
"transcoding": {
"type": "DASH",
"originStreamId": "<streamId>",
"onDemand": true,
"audioOnly": false,
"quality": "hd",
"tags": ["<tag1>", "<tag2>"]
}
}'
Request Fields
Field
Description
transcoding (required)
See Transcoding object below
credentials (optional)
The preferred way of passing the credentials is with HTTP authentication header . Alternatively they can be passed in the request body .
Transcoding Object
Field
Description
type (required)
Format the stream will be transcoded to. See Transcoding types below.
originStreamId (required)
ID of the Stream that will be transcoded
onDemand (optional)
Persist the transcoded live stream for on-demand playback. The stream features the same capabilities as the adaptive multi-bit rate live stream and can be accessed time delayed.
audioOnly (optional)
Transcode audio only stream. This is mutually exclusive with videoOnly
.
videoOnly (optional)
Transcode video only stream. This is mutually exclusive with audioOnly
.
quality (optional)
See Transcoding qualities below
tags (optional)
Tags for the Transcoded stream
Transcoding Types
Field
Description
DASH
Dynamic Adaptive Streaming over HTTP
HLS
HTTP Live Streaming
Transcoding Qualities
Field
Description
uld
Output Ultra low definition - 80kbps stream
vld
Output Very low definition - 350kbps stream
ld
Output Low definition - 520kbps stream
sd
Output Standard definition - 830kbps - default stream
hd
Output High definition - 1600kbps stream
fhd
Output Full high definition - 3000kbps stream
xhd
Output Extended high definition - 5500kbps stream
uhd
Output Ultra high definition - 8500kbps stream
Response
The platform will return a successful response that contains a “status” field. The HTTP status code is set according to the “status” field.
HTTP / 1.1 200 OK
Content-Type : application/json; charset=utf-8
Content-Length : 85
{ "status" : "ok" , "transcodingId" : "us-central#us-central1-c.8q9rSY86.20180412.PNGRcHO8" }
{
"status" : "ok" ,
"transcodingId" : "us-central#us-central1-c.8q9rSY86.20180412.PNGRcHO8"
}
Start Transcoding API Response fields
Field
Description
status
See status codes below
transcodingId
ID of the transcoded stream
Start Transcoding API Status Codes
HTTP
Status
Retry
Description
200 OK
ok
never
Transcoding was successfully created.
400 Bad Request
<varies>
never
Indicates an issue with the request.
401 Unauthorized
unauthorized
never
The streaming platform was not able to authorize the provided credentials.
409 Conflict
already-exists
never
4XX
<varies>
never
Indicates an issue with the request.
503 Service Unavailable
capacity
once
The system is temporarily overloaded. Please try again later.
5XX
<varies>
once immediately, then exponential backoff
A transient server error.
Error Responses : Please be aware that some server errors 5XX and request validation errors 400 and 401 may result in an arbitrary response body not encoded in JSON.
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>"
}'
Encoding : Transcoding ID may contain characters that are unsafe for URLs. Be sure to encode the TranscodingId in the URL path. For example, the URL encoding of `us-central#us-central` is `us-central%23us-central`
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.
Error Responses : Please be aware that some server errors 5XX and request validation errors 400 and 401 may result in an arbitrary response body not encoded in JSON.
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
Header
Description
Authorization (required)
Use HTTP Basic Authentication with your applicationId and secret
Request Query Parameters
Name
Description
version (optional)
Must be in the format of ‘YYYY-MM-dd’. If absent, a default value will be used as described in Publishing Report Versions
Publishing Report Versions
Version
Description
2021-09-07
The default if request is made before 2022-04-19 14:00:00 UTC.
2021-10-20
The default if request is made on or after 2022-04-19 14:00:00 UTC.
Request Fields
Field
Description
publishingReport (required)
See PublishingReport object below
PublishingReport Object
Field
Description
applicationIds (optional)
Array of applications IDs to report for. By default, it will report publishing for the application ID from credentials.
streamIds (optional)
Array of stream IDs to report for. Limits the report to just these streams.
channelIds (optional)
Array of channel IDs to report for. Limits the report to just these channels.
channelAliases (optional)
Array of channel aliases to report for. Limits the report to just these channels.
roomIds (optional)
Array of room IDs to report for. Limits the report to just these rooms.
roomAliases (optional)
Array of room aliases to report for. Limits the report to just these rooms.
tags (optional)
Array of tags to report for. Limits the report to just these tags.
start (required)
The report start time. Either an RFC3339 timestamp string or an integer of UNIX epoch time in milliseconds.
end (required)
The report end time. Either an RFC3339 timestamp string or an integer of UNIX epoch time in milliseconds.
Note: All filter conditions are cumulative.
Response
The response is in CSV format.
Report Response Fields (Version 2021-09-07)
Column
Description
ReportTimestamp
Time of report generation
PeriodStartTimestamp
Start time of the reporting period
PeriodEndTimestamp
End time of the reporting period
ApplicationId
Application ID of the stream
ChannelAlias
Channel alias of the stream
ChannelId
Channel ID of the stream
RoomAlias
Room alias of the stream
RoomId
Room ID of the stream
StreamId
Stream ID of the publisher
Region
Region of the publisher
AudioQuality
Audio quality of the publisher, or “video-only” if the publisher was video-only
VideoQuality
Video quality of the publisher, or “audio-only” if the publisher was audio-only
PublishedMinutesDuringPeriod
The duration published during the report period
PublishedMinutesTotal
Total duration of the publishing stream, empty if stream did not end within the report period
PeakConcurrentViews
Peak number of concurrent viewing streams
TotalViews
Total number of viewing streams
FramesPerSecond
Frames per second of the publishing stream
StartTimestamp
Timestamp at which the publishing stream started
EndTimestamp
Timestamp at which the publishing stream ended
StartedDuringPeriod
Whether the publishing stream started during the period
EndedDuringPeriod
Whether the publishing stream ended during the period
EndedReason
Why the publishing stream ended, empty if stream did not end within the report period
DeviceId
Unique device ID of the publisher
RemoteAddress
IP address of the publisher
IngestStreamId
Stream ID of the ingest stream, empty if stream did not have a corresponding ingest stream
IngestStreamEndedReason
Why the ingest stream ended, empty if stream did not have a corresponding ingest stream
Live
Does the publisher have “streaming” capability
VOD
Does the publisher have “on-demand” or “on-demand-archive=PT…” capability
RTMP
Does the publisher have “rtmp” capability
LiveLite
Does the publisher have “streaming-lite” capability
VODLite
Does the publisher have “on-demand-lite” capability
MBR
Does the publisher have “multi-bitrate” capability
MBRContribution
Does the publisher have “multi-bitrate-contribution” capability
AudioOnly
Does the publisher have “audio-only” capability
Tags
Tags on the publishing stream
Capabilities
Capabilities on the publishing stream
EncodingProfile
Encoding profile of the publishing stream
Report Response Fields (Version 2021-10-20)
Column
Description
ReportTimestamp
Time of report generation
PeriodStartTimestamp
Start time of the reporting period
PeriodEndTimestamp
End time of the reporting period
ApplicationId
Application ID of the stream
ChannelAlias
Channel alias of the stream
ChannelId
Channel ID of the stream
RoomAlias
Room alias of the stream
RoomId
Room ID of the stream
StreamId
Stream ID of the publisher
Region
Region of the publisher
AudioQuality
Audio quality of the publisher, or “video-only” if the publisher was video-only
VideoQuality
Video quality of the publisher, or “audio-only” if the publisher was audio-only
PublishedMinutesDuringPeriod
The duration published during the report period
PublishedMinutesTotal
Total duration of the publishing stream, empty if stream did not end within the report period
FramesPerSecond
Frames per second of the publishing stream
PeakConcurrentViews
Peak number of concurrent viewing streams
TotalViews
Total number of viewing streams
StartTimestamp
Timestamp at which the publishing stream started
EndTimestamp
Timestamp at which the publishing stream ended
StartedDuringPeriod
Whether the publishing stream started during the period
EndedDuringPeriod
Whether the publishing stream ended during the period
EndedReason
Why the publishing stream ended, empty if stream did not end within the report period
DeviceId
Unique device ID of the publisher
RemoteAddress
IP address of the publisher
ContributionMethod
The method of publishing, either “URI”, “RTMP”, or “ITP-WebRTC”
IngestStreamId
Stream ID of the ingest stream, empty if stream did not have a corresponding ingest stream
IngestStreamEndedReason
Why the ingest stream ended, empty if stream did not have a corresponding ingest stream
IngestSource
Source of the published stream, one of “iOS SDK”, “Android SDK”, “Web SDK”, “Phenix Encoder”, “RTMP Encoder”, or “Admin API”
MultiBitrateTranscoding
Whether MultiBitrate transcoding is done for the stream. “TRUE” if either 1) “streaming” capability is set and “streaming-lite” capability is missing, or 2) “on-demand” capability is set and “on-demand-lite” capability is missing, or 3) “multi-bitrate” capability is set.
Repackaging
Whether repackaging work is done for the stream. “TRUE” if any of the capabilities “streaming”, “on-demand”, or “rtmp” is presernt, or if ContributionMethod is “URI” or “RTMP”
Composition
Whether composition work is done for the stream. “TRUE” if the capability “composition” is set.
Tags
Tags on the publishing stream
Capabilities
Capabilities on the publishing stream
audio_only
Does the publisher have “audio-only” capability
video_only
Does the publisher have “video-only” capability
encoding_profile
Encoding profile of the publishing stream
multi_bitrate
Does the publisher have “multi-bitrate” capability
multi_bitrate_contribution
Does the publisher have “multi-bitrate-contribution” capability
streaming
Does the publisher have “streaming” capability
on_demand
Does the publisher have “on-demand” or “on-demand-archive=PT…” capability
rtmp
Does the publisher have “rtmp” capability
streaming_lite
Does the publisher have “streaming-lite” capability
on_demand_lite
Does the publisher have “on-demand-lite” capability
HTTP / 1.1 200 OK
Content-Type : application/json; charset=utf-8
Content-Length : 1,522
Content-Disposition : attachment; filename="20200305T161052Z-START20200101T000000Z-END20200201T000000Z-Publishing-fGGvDe.csv"
ReportTimestamp , PeriodStartTimestamp , PeriodEndTimestamp , ApplicationId , ChannelAlias , ChannelId , RoomAlias , RoomId , StreamId , Region , AudioQuality , VideoQuality , PublishedMinutesDuringPeriod , PublishedMinutesTotal , PeakConcurrentViews , TotalViews , FramesPerSecond , StartTimestamp , EndTimestamp , StartedDuringPeriod , EndedDuringPeriod , EndedReason , DeviceId , RemoteAddress , Ingest , Live , VOD , RTMP , LiveLite , VODLite , MBR , MBRContribution , AudioOnly , Tags , Capabilities , EncodingProfile
2020-03-05 T 16 : 10 : 53.769 Z , 2020-01-01 T 00 : 00 : 0 0.000 Z , 2020-02-01 T 00 : 00 : 0 0.000 Z , example.com ,, us-northeast#example.com#channel 123456 .S 1 b 486 elbH 4 I ,,, us-northeast#US-ASHBURN-AD -1 .abc 1 dmrQ. 20191204 .LggGuzQ 8 , us-northeast ,, sd , 44640 ,,,, 60.12 , 2019-12-04 T 12 : 36 : 22.476 Z ,, FALSE , FALSE ,, a 18 af 5 b 7 cf 914765 bd 066 b 13 ba 842 a 90953 d 0 bb 92 bf 58 c 7 cfd 7 b 6839 b 861 e 5 ed ,:: ffff : 52.4 . 228.111 , FALSE , FALSE , TRUE , FALSE , FALSE , FALSE , FALSE , FALSE , FALSE , channelId : us-northeast#example.com#channel 123456 .S 1 b 486 elbH 4 I|Status : STREAMING , sd|detached|rtmp|publish-uri , phenix -2020
2020-03-05 T 16 : 10 : 53.769 Z , 2020-01-01 T 00 : 00 : 0 0.000 Z , 2020-02-01 T 00 : 00 : 0 0.000 Z , example.com ,,, exampleRoomAlias , asia-south#example#roomName.abcdee , asia-south#asia-south 1 -c.Bqac 2 GbH. 20191203 .Vxg 6 P 1 AD , asia-south ,, sd , 44640 ,,,, 59.89 , 2019-12-03 T 02 : 57 : 15.756 Z ,, FALSE , FALSE ,, 3 d 14957 e 6209 e 1 c 77 db 3086557 d 6 a 42655 f 8 a 54 ded 2 a 2 cea 33 c 9 f 43506 c 56297 ,:: ffff : 53.5 . 212.150 , FALSE , FALSE , FALSE , FALSE , FALSE , TRUE , FALSE , FALSE , FALSE , x-ingest , publish-uri|resilient|monitor-tracks|no-session-stream-events|transcoding= {} |sd|multi-bitrate|prefer-h 264 |origin-shield , phenix -2020
curl: Saved to filename '20200204T171148Z-START20200101T000000Z-END20200201T000000Z-RealTime-RWYkT1.csv'
If the request fails, the platform will return a failed response that contains a “status” field. The HTTP status code is set according to the “status” field.
HTTP / 1.1 400 Bad request
Content-Type : application/json; charset=utf-8
Content-Length : 37
{ "status" : "excessive-report-interval" }
$ cat publishing
{
"status" :"excessive-report-interval"
}
Publishing report API Response fields
Field
Description
status
See status codes below
Publishing report API Status Codes
HTTP
Status
Retry
Description
200 OK
ok
never
Report was successfully created.
400 Bad Request
<varies>
never
Indicates an issue with the request.
400 Bad Request
excessive-report-interval
never
The interval for the report exceed 1 year.
400 Bad Request
period-start-outside-supported-window
never
The year of the start of period is more than 1 year before the current year.
400 Bad Request
period-end-must-be-in-past
never
The end of period is in future.
400 Bad Request
period-end-must-be-after-start
never
The end of period is less than or equal to the start of the period.
400 Bad Request
malformed-version-in-request-query-parameter
never
The supplied version in HTTP query parameter does not conform to the format “YYYY-MM-dd”.
400 Bad Request
version-does-not-exist
never
The supplied version in HTTP query parameter does not exist, see Publishing Report Versions for supported versions.
400 Bad Request
unsupported
never
The parameter combination is not supported.
401 Unauthorized
unauthorized
never
The streaming platform was not able to authorize the provided credentials.
408 Request Timeout
request-timeout
once immediately, then exponential backoff
Request timed out likely due to temporary resource or network conditions. Please try again.
4XX
<varies>
never
Indicates an issue with the request.
503 Service Unavailable
capacity
once
The system is temporarily overloaded. Please try again later.
5XX
<varies>
once immediately, then exponential backoff
A transient server error.
Error Responses : Please be aware that some server errors 5XX and request validation errors 400 and 401 may result in an arbitrary response body not encoded in JSON.
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
Header
Description
Authorization (required)
Use HTTP Basic Authentication with your applicationId and secret
Request Fields
Field
Description
viewingReport (required)
See ViewingReport object below
ViewingReport Object
Field
Description
kind (required)
Kind of viewing report to generate.
applicationIds (optional)
Array of applications IDs to report for. By default, it will report viewing for the application ID from credentials.
streamIds (optional)
Array of stream IDs to report for. Limits the report to just these streams.
sessionIds (optional)
Array of session IDs to report for. Limits the report to just these sessions.
originStreamIds (optional)
Array of origin stream IDs to report for. Limits the report to just these origin streams.
channelIds (optional)
Array of channel IDs to report for. Limits the report to just these channels.
channelAliases (optional)
Array of channel aliases to report for. Limits the report to just these channel aliases.
tags (optional)
Array of tags to report for. Limits the report to just these tags.
originTags (optional)
Array of origin tags to report for. Limits the report to just these origin tags.
start (required)
The report start time. Either an RFC3339 timestamp string or an integer of UNIX epoch time in milliseconds.
end (required)
The report end time. Either an RFC3339 timestamp string or an integer of UNIX epoch time in milliseconds.
Note: All filter conditions are cumulative.
ViewingReport Kinds
Field
Description
RealTime
Report for real time viewing.
RTMP
Report for RTMP viewing.
HLS
Report for HLS viewing.
DASH
Report for DASH viewing.
Response
The response is in CSV format.
Report Response Fields
Column
Description
Real Time
RTMP
HLS
DASH
ReportTimestamp
Time of report generation
✔
✔
✔
✔
PeriodStartTimestamp
Start time of the reporting period
✔
✔
✔
✔
PeriodEndTimestamp
End time of the reporting period
✔
✔
✔
✔
ApplicationId
Application ID of the stream
✔
✔
✔
✔
ChannelAlias
Channel alias of the stream
✔
✔
✔
✔
ChannelId
Channel ID of the stream
✔
✔
✔
✔
OriginStreamId
Stream ID of the origin
✔
✔
✔
✔
OriginRegion
Region of the origin
✔
✔
✔
✔
OriginFramesPerSecond
Frames per second of the origin
✔
✔
✔
✔
OriginAudioQuality
Audio quality of the origin, or “video-only” if the origin was video-only
✔
✔
✔
✔
OriginVideoQuality
Video quality of the origin, or “audio-only” if the origin was audio-only
✔
✔
✔
✔
OriginTags
Tags on the origin stream
✔
✔
✔
✔
ViewedMinutesDuringPeriod
The duration viewed during the report period
✔
✔
✔
✔
ViewedMinutesTotal
Total duration of the viewing stream, empty if stream did not end within the report period
✔
✔
×
×
TotalBytes
The total bytes bidirectionally transferred for the stream
✔
✔
✔
✔
StartTimestamp
Timestamp at which the viewing stream started
✔
✔
✔
✔
EndTimestamp
Timestamp at which the viewing stream ended
✔
✔
✔
✔
StartedDuringPeriod
Whether the viewing stream started during the period
✔
✔
✔
✔
EndedDuringPeriod
Whether the viewing stream ended during the period
✔
✔
✔
✔
StreamId
Stream ID of the viewer
✔
✔
×
×
Region
Region of the viewer
✔
✔
×
×
FramesPerSecond
Frames per second of the viewer
✔
✔
×
×
AudioQuality
Audio quality of the viewing stream, or “video-only” if the viewer or corresponding origin was video-only
✔
✔
×
×
VideoQuality
Video quality of the viewing stream, or “audio-only” if the viewer or corresponding origin was audio-only
✔
✔
×
×
DeviceId
Unique device ID of the viewer
✔
✔
✔
✔
RemoteAddress
IP address of the viewer
✔
✔
✔
✔
Continent
Continent of the viewer
✔
✔
✔
✔
Country
Country of the viewer
✔
✔
✔
✔
State
State of the viewer
✔
✔
✔
✔
City
City of the viewer
✔
✔
✔
✔
PostalCode
Postal code of the viewer
✔
✔
✔
✔
UserAgent
User agent of the viewer
✔
✔
✔
✔
Tags
Tags on the viewing stream
✔
✔
✔
✔
NumberOfRequests
Total number of HTTP requests made by the viewer within the report period
×
×
✔
✔
HTTP / 1.1 200 OK
Content-Type : application/json; charset=utf-8
Content-Length : 905
Content-Disposition : attachment; filename="20200204T171148Z-START20200101T000000Z-END20200201T000000Z-RealTime-RWYkT1.csv"
ReportTimestamp , PeriodStartTimestamp , PeriodEndTimestamp , ApplicationId , ChannelAlias , ChannelId , OriginStreamId , OriginRegion , OriginFramesPerSecond , OriginAudioQuality , OriginVideoQuality , OriginTags , TotalBytes , ViewedMinutesDuringPeriod , ViewedMinutesTotal , StartTimestamp , EndTimestamp , StartedDuringPeriod , EndedDuringPeriod , StreamId , Region , FramesPerSecond , AudioQuality , VideoQuality , DeviceId , RemoteAddress , UserAgent , Tags
2020-02-04 T 17 : 11 : 49.734 Z , 2020-01-01 T 00 : 00 : 0 0.000 Z , 2020-02-01 T 00 : 00 : 0 0.000 Z , applicationId , test , europe-west#applicationId#test. 123456 , europe-west#europe-west 1 -b. 98 iO 2 zP 0.20190102 .PUFMxKEZ , europe-west , 30.01 ,, hd , “” , 52130 , 4 , 4 , 2020-01-02 T 13 : 38 : 58.114 Z , 2020-01-02 T 13 : 42 : 49.042 Z , TRUE , TRUE , europe-west#europe-west 1 -b. 98 iO 2 zP 0.20190102 .PoohNQEi , europe-west , 30.00 ,, hd , 64 dabda 4 d 6 fae 4 ac 0926290 c 6851 ff 8586 e 0 cd 9 f 58067 c 0 ee 0013 c 6 a 73060 dd 1 , 1.2 . 3.4 , Mozilla/ 5.0 (Windows NT 6.1 ; Trident/ 7.0 ; rv : 11.0 ) like Gecko , “”
curl: Saved to filename '20200204T171148Z-START20200101T000000Z-END20200201T000000Z-RealTime-RWYkT1.csv'
If the request fails, the platform will return a failed response that contains a “status” field. The HTTP status code is set according to the “status” field.
HTTP / 1.1 400 Bad request
Content-Type : application/json; charset=utf-8
Content-Length : 37
{ "status" : "excessive-report-interval" }
$ cat viewing
{
"status" :"excessive-report-interval"
}
Viewing report API Response fields
Field
Description
status
See status codes below
Viewing report API Status Codes
HTTP
Status
Retry
Description
200 OK
ok
never
Report was successfully created.
400 Bad Request
<varies>
never
Indicates an issue with the request.
400 Bad Request
excessive-report-interval
never
The interval for the report exceed 1 year.
400 Bad Request
period-start-outside-supported-window
never
The year of the start of period is more than 1 year before the current year.
400 Bad Request
period-end-must-be-in-past
never
The end of period is in future.
400 Bad Request
period-end-must-be-after-start
never
The end of period is less than or equal to the start of the period.
400 Bad Request
unsupported
never
The parameter combination is not supported.
401 Unauthorized
unauthorized
never
The streaming platform was not able to authorize the provided credentials.
408 Request Timeout
request-timeout
once immediately, then exponential backoff
Request timed out likely due to temporary resource or network conditions. Please try again.
4XX
<varies>
never
Indicates an issue with the request.
503 Service Unavailable
capacity
once
The system is temporarily overloaded. Please try again later.
5XX
<varies>
once immediately, then exponential backoff
A transient server error.
Error Responses : Please be aware that some server errors 5XX and request validation errors 400 and 401 may result in an arbitrary response body not encoded in JSON.
Generate a Fork History Report
This API retrieves history of fork-channel API calls .
In order to be able to generate reports, your account needs to be provisioned accordingly. Please contact your primary Phenix technical support contact if you wish to use reporting.
Request
Send a PUT
request to pcast/reporting/fork/history
endpoint as shown:
PUT pcast/reporting/fork/history HTTP / 1.1
Host : pcast.phenixrts.com
Accept : application/json
Content-Type : application/json
Content-Length : 158
Authorization : Basic YXBwbGljYXRpb25JZDpzZWNyZXQ=
{
"forkHistoryReport" : {
"applicationIds" : [ "example.com" ],
"start" : "2020-01-01T00:00:00Z" ,
"end" : "2020-01-02T00:00:00Z"
}
}
$ curl https://pcast.phenixrts.com/pcast/reporting/fork/history \
-u <applicationId>:<secret> \
-H "Accept: text/csv" \
-H "Content-Type: application/json" \
-X PUT \
-d '{
"forkHistoryReport": {
"applicationIds": ["example.com"],
"start": "2020-01-01T00:00:00Z",
"end": "2020-01-02T00:00:00Z"
}
}'
--remote-name
--remote-header-name
Header
Description
Authorization (required)
Use HTTP Basic Authentication with your applicationId and secret
Request Fields
ForkHistoryReport Object
Field
Description
start (required)
The report start time. Either an RFC3339 timestamp string or an integer of UNIX epoch time in milliseconds.
end (required)
The report end time. Either an RFC3339 timestamp string or an integer of UNIX epoch time in milliseconds.
applicationIds (optional)
Array of applications IDs to report for. By default, it will report fork requests for the application ID from credentials. A record is selected as long as at least one of the target or destination channel belongs to the supplied application ID.
sourceChannelIds (optional)
Array of source channel IDs to report for.
destinationChannelIds (optional)
Array of destination channel IDs to report for.
Note: All filter conditions are cumulative.
Response
The response is in CSV format.
Report Response Fields
Column
Description
Timestamp
The time at which an fork API call is made.
ApplicationId
The application ID that the request belongs to.
SourceId
The ID of the room that was forked from.
DestinationId
The ID of the room that was forked to.
RequestMethod
The HTTP request method of the API call.
RequestURL
The URL of the request.
RequestSize
The size of the request.
Status
The status code of the request.
ResponseSize
The size of the response.
UserAgent
The useragent from which the request was sent.
RemoteAddress
The remote address from which the request was sent.
HTTP / 1.1 200 OK
Content-Type : application/json; charset=utf-8
Content-Length : 85
Content-Disposition : attachment; filename="20200204T171148Z-START20200101T000000Z-END20200102T000000Z-ForkHistory-RWYkT1.csv"
Timestamp , ApplicationId , SourceId , DestinationId , RequestMethod , RequestURL , RequestSize , Status , ResponseSize , UserAgent , RemoteAddress
2020-01-01 03 : 10 : 00 , example.com , us-east#example.com# 2 , uk-southeast#example.com# 1 , PUT , https : //pcast.phenixrts.com/pcast/channel/uk-southeast#example.com# 1 /fork/us-east#example.com# 2 , 465 , 200 , 978 , okhttp/ 3.12 . 1 , 111.22 . 333.444
2020-01-02 03 : 12 : 00 , example.com , us-east#example.com# 4 , uk-southeast#example.com# 3 , PUT , https : //pcast.phenixrts.com/pcast/channel/uk-southeast#example.com# 3 /fork/us-east#example.com# 4 , 482 , 200 , 938 , okhttp/ 3.12 . 1 , 555.66 . 777.888
curl: Saved to filename '20200204T171148Z-START20200101T000000Z-END20200102T000000Z-ForkHistory-RWYkT1.csv'
If the request fails, the platform will return a failed response that contains a “status” field. The HTTP status code is set according to the “status” field.
HTTP / 1.1 400 Bad request
Content-Type : application/json; charset=utf-8
Content-Length : 37
{ "status" : "excessive-report-interval" }
$ cat history
{
"status" :"excessive-report-interval"
}
Fork History Report API Response Fields
Field
Description
status
See status codes below
Fork History Report API Status Codes
HTTP
Status
Retry
Description
200 OK
ok
never
Report was successfully created.
400 Bad Request
<varies>
never
Indicates an issue with the request.
400 Bad Request
excessive-report-interval
never
The interval for the report exceed 1 day.
400 Bad Request
period-start-outside-supported-window
never
The year of the start of period is more than 1 year before the current year.
400 Bad Request
period-end-must-be-in-past
never
The end of period is in future.
400 Bad Request
period-end-must-be-after-start
never
The end of period is less than or equal to the start of the period.
400 Bad Request
unsupported
never
The parameter combination is not supported.
401 Unauthorized
unauthorized
never
The streaming platform was not able to authorize the provided credentials.
408 Request Timeout
request-timeout
once immediately, then exponential backoff
Request timed out likely due to temporary resource or network conditions. Please try again.
413 Payload Too Large
maximal-result-size-exceeded
never
The size of the result exceeds the maximum allowed (10GB).
4XX
<varies>
never
Indicates an issue with the request.
503 Service Unavailable
capacity
once
The system is temporarily overloaded. Please try again later.
5XX
<varies>
once immediately, then exponential backoff
A transient server error.
Error Responses : Please be aware that some server errors 5XX and request validation errors 400 and 401 may result in an arbitrary response body not encoded in JSON.
Generate an Ingest Report
This API generates an ingest report for the given interval.
In order to be able to generate reports, your account needs to be provisioned accordingly. Please contact your primary Phenix technical support contact if you wish to use reporting.
Request
Send a PUT
request to pcast/ingest/buffer
endpoint as shown:
PUT pcast/ingest/buffer HTTP / 1.1
Host : pcast.phenixrts.com
Accept : application/json
Content-Type : application/json
Content-Length : 174
Authorization : Basic YXBwbGljYXRpb25JZDpzZWNyZXQ=
{
"ingestReport" : {
"kind" : "BufferUnderrun" ,
"applicationIds" : [ "example.com" ],
"start" : "2020-01-01T00:00:00Z" ,
"end" : "2020-01-02T00:00:00Z"
}
}
$ curl https://pcast.phenixrts.com/pcast/ingest/buffer \
-u <applicationId>:<secret> \
-H "Accept: text/csv" \
-H "Content-Type: application/json" \
-X PUT \
-d '{
"ingestReport": {
"kind": "BufferUnderrun",
"applicationIds": ["example.com"],
"start": "2020-01-01T00:00:00Z",
"end": "2020-01-02T00:00:00Z"
}
}'
--remote-name
--remote-header-name
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_ 2 audio , us-northeast#demo#mt 2 Audio. 8 sV 13 fIRnn 4 D , asia-east#asia-east 1 -b. 4 O 506 ci 8.20200601 .PSfVsDhh , asia-east#asia-east 1 -b. 4 O 506 ci 8.20200601 .ItnIMcjA , audio , 4155586604 , 2020-01-01 T 20 : 16 : 38.294 Z , 2020-01-01 T 20 : 16 : 38.378 Z , 84
example.com , MT_ 2 audio , us-northeast#demo#mt 2 Audio. 8 sV 13 fIRnn 4 D , asia-east#asia-east 1 -b. 4 O 506 ci 8.20200601 .PSfVsDhh , asia-east#asia-east 1 -b. 4 O 506 ci 8.20200601 .ItnIMcjA , audio , 4155586604 , 2020-01-01 T 20 : 16 : 38.922 Z , 2020-01-01 T 20 : 16 : 39.007 Z , 85
curl: Saved to filename '20200204T171148Z-START20200101T000000Z-END20200102T000000Z-BufferUnderrun-RWYkT1.csv'
If the request fails, the platform will return a failed response that contains a “status” field. The HTTP status code is set according to the “status” field.
HTTP / 1.1 400 Bad request
Content-Type : application/json; charset=utf-8
Content-Length : 37
{ "status" : "excessive-report-interval" }
$ cat ingest
{
"status" :"excessive-report-interval"
}
Ingest Report API Response Fields
Field
Description
status
See status codes below
Ingest Report API Status Codes
HTTP
Status
Retry
Description
200 OK
ok
never
Report was successfully created.
400 Bad Request
<varies>
never
Indicates an issue with the request.
400 Bad Request
excessive-report-interval
never
The interval for the report exceed 1 day.
400 Bad Request
period-start-outside-supported-window
never
The year of the start of period is more than 1 year before the current year.
400 Bad Request
period-end-must-be-in-past
never
The end of period is in future.
400 Bad Request
period-end-must-be-after-start
never
The end of period is less than or equal to the start of the period.
400 Bad Request
unsupported
never
The parameter combination is not supported.
401 Unauthorized
unauthorized
never
The streaming platform was not able to authorize the provided credentials.
408 Request Timeout
request-timeout
once immediately, then exponential backoff
Request timed out likely due to temporary resource or network conditions. Please try again.
4XX
<varies>
never
Indicates an issue with the request.
503 Service Unavailable
capacity
once
The system is temporarily overloaded. Please try again later.
5XX
<varies>
once immediately, then exponential backoff
A transient server error.
Error Responses : Please be aware that some server errors 5XX and request validation errors 400 and 401 may result in an arbitrary response body not encoded in JSON.
Generate a Network Throughput Report
This API generates a network throughput report for the given interval.
In order to be able to generate reports, your account needs to be provisioned accordingly. Please contact your primary Phenix technical support contact if you wish to use reporting.
Request
Send a PUT
request to pcast/network/throughput
endpoint as shown:
PUT pcast/network/throughput HTTP / 1.1
Host : pcast.phenixrts.com
Accept : application/json
Content-Type : application/json
Content-Length : 185
Authorization : Basic YXBwbGljYXRpb25JZDpzZWNyZXQ=
{
"networkReport" : {
"applicationIds" : [ "example.com" ],
"start" : "2021-01-01T00:00:00Z" ,
"end" : "2021-01-02T00:00:00Z"
}
}
$ curl https://pcast.phenixrts.com/pcast/network/throughput \
-u <applicationId>:<secret> \
-H "Accept: text/csv" \
-H "Content-Type: application/json" \
-X PUT \
-d '{
"networkReport": {
"applicationIds": ["example.com"],
"start": "2021-01-01T00:00:00Z",
"end": "2021-01-02T00:00:00Z"
}
}'
--remote-name
--remote-header-name
Header
Description
Authorization (required)
Use HTTP Basic Authentication with your applicationId and secret
Request Fields
Field
Description
networkReport (required)
See NetworkReport object below
NetworkReport Object
Field
Description
applicationIds (optional)
Array of applications IDs to report for. By default, it will report network for the application ID from credentials.
streamIds (optional)
Array of stream IDs to report for. Limits the report to just these streams.
channelIds (optional)
Array of channel IDs to report for. Limits the report to just these channels IDs.
channelAliases (optional)
Array of channel aliases to report for. Limits the report to just these channel aliases.
roomIds (optional)
Array of room IDs to report for. Limits the report to just these rooms.
roomAliases (optional)
Array of room aliases to report for. Limits the report to just these rooms.
start (required)
The report start time. Either an RFC3339 timestamp string or an integer of UNIX epoch time in milliseconds.
end (required)
The report end time. Either an RFC3339 timestamp string or an integer of UNIX epoch time in milliseconds.
Note: All filter conditions are cumulative.
Response
The response is in CSV format.
Report Response Fields
Column
Description
Throughput
TimeBucket
Aggregated time bucket (in invervals of SECONDS)
✔
MinimalTimestamp
Minimal timestamp window of normalized throughput
✔
MaximalTimestamp
Maximal timestamp window of normalized throughput
✔
Kind
Kind/Media type of the stream
✔
NumberOfSsrc
Total number of Synchronization Source(s) in TimeBucket
✔
NumberOfStreams
Total number of Stream(s) in TimeBucket
✔
MediaBitsPerSecondThroughput
Number of payload bits sent as part of Media packets in TimeBucket
✔
FecBitsPerSecondThroughput
Number of payload bits sent as part of FEC packets in TimeBucket
✔
RtpBitsPerSecondThroughput
Number of payload bits sent as part of RTP packets in TimeBucket
✔
HTTP / 1.1 200 OK
Content-Type : application/json; charset=utf-8
Content-Length : 1604
Content-Disposition : attachment; filename="20210915T230840Z-START20210903T173000Z-END20210903T180000Z-Throughput-eTe4HH.csv"
TimeBucket , MinimalTimestamp , MaximalTimestamp , Kind , NumberOfSsrc , NumberOfStreams , MediaBitsPerSecondThroughput , FecBitsPerSecondThroughput , RtpBitsPerSecondThroughput
2021-09-03 17 : 45 : 35 UTC , 2021-09-03 17 : 45 : 41.775 UTC , 2021-09-03 17 : 45 : 41.775 UTC , audio , 1 , 1 , 29116 ,, 43260
2021-09-03 17 : 45 : 36 UTC , 2021-09-03 17 : 45 : 41.775 UTC , 2021-09-03 17 : 45 : 41.775 UTC , audio , 1 , 1 , 29116 ,, 43260
2021-09-03 17 : 45 : 37 UTC , 2021-09-03 17 : 45 : 41.775 UTC , 2021-09-03 17 : 45 : 41.775 UTC , audio , 1 , 1 , 29116 ,, 43260
2021-09-03 17 : 45 : 38 UTC , 2021-09-03 17 : 45 : 41.775 UTC , 2021-09-03 17 : 45 : 41.775 UTC , audio , 1 , 1 , 29116 ,, 43260
2021-09-03 17 : 45 : 39 UTC , 2021-09-03 17 : 45 : 41.775 UTC , 2021-09-03 17 : 45 : 41.775 UTC , audio , 1 , 1 , 29116 ,, 43260
2021-09-03 17 : 45 : 40 UTC , 2021-09-03 17 : 45 : 41.775 UTC , 2021-09-03 17 : 45 : 41.775 UTC , audio , 1 , 1 , 29116 ,, 43260
2021-09-03 17 : 45 : 41 UTC , 2021-09-03 17 : 45 : 41.775 UTC , 2021-09-03 17 : 45 : 41.775 UTC , audio , 1 , 1 , 29116 ,, 43260
2021-09-03 17 : 45 : 35 UTC , 2021-09-03 17 : 45 : 41.773 UTC , 2021-09-03 17 : 45 : 41.773 UTC , video , 1 , 1 , 51600 ,, 59784
2021-09-03 17 : 45 : 36 UTC , 2021-09-03 17 : 45 : 41.773 UTC , 2021-09-03 17 : 45 : 41.773 UTC , video , 1 , 1 , 51600 ,, 59784
2021-09-03 17 : 45 : 37 UTC , 2021-09-03 17 : 45 : 41.773 UTC , 2021-09-03 17 : 45 : 41.773 UTC , video , 1 , 1 , 51600 ,, 59784
2021-09-03 17 : 45 : 38 UTC , 2021-09-03 17 : 45 : 41.773 UTC , 2021-09-03 17 : 45 : 41.773 UTC , video , 1 , 1 , 51600 ,, 59784
2021-09-03 17 : 45 : 39 UTC , 2021-09-03 17 : 45 : 41.773 UTC , 2021-09-03 17 : 45 : 41.773 UTC , video , 1 , 1 , 51600 ,, 59784
2021-09-03 17 : 45 : 40 UTC , 2021-09-03 17 : 45 : 41.773 UTC , 2021-09-03 17 : 45 : 41.773 UTC , video , 1 , 1 , 51600 ,, 59784
2021-09-03 17 : 45 : 41 UTC , 2021-09-03 17 : 45 : 41.773 UTC , 2021-09-03 17 : 45 : 41.773 UTC , video , 1 , 1 , 51600 ,, 59784
curl: Saved to filename '20210915T230840Z-START20210903T173000Z-END20210903T180000Z-Throughput-eTe4HH.csv'
If the request fails, the platform will return a failed response that contains a “status” field. The HTTP status code is set according to the “status” field.
HTTP / 1.1 400 Bad request
Content-Type : application/json; charset=utf-8
Content-Length : 39
{ "status" : "excessive-report-interval" }
$ cat network
{
"status" :"excessive-report-interval"
}
Network Throughput Report API Response Fields
Field
Description
status
See status codes below
Network Throughput Report API Status Codes
HTTP
Status
Retry
Description
200 OK
ok
never
Report was successfully created.
400 Bad Request
<varies>
never
Indicates an issue with the request.
400 Bad Request
excessive-report-interval
never
The interval for the report exceed 1 day.
400 Bad Request
period-start-outside-supported-window
never
The year of the start of period is more than 1 year before the current year.
400 Bad Request
period-end-must-be-in-past
never
The end of period is in future.
400 Bad Request
period-end-must-be-after-start
never
The end of period is less than or equal to the start of the period.
400 Bad Request
unsupported
never
The parameter combination is not supported.
401 Unauthorized
unauthorized
never
The streaming platform was not able to authorize the provided credentials.
408 Request Timeout
request-timeout
once immediately, then exponential backoff
Request timed out likely due to temporary resource or network conditions. Please try again.
4XX
<varies>
never
Indicates an issue with the request.
503 Service Unavailable
capacity
once
The system is temporarily overloaded. Please try again later.
5XX
<varies>
once immediately, then exponential backoff
A transient server error.
Error Responses : Please be aware that some server errors 5XX and request validation errors 400 and 401 may result in an arbitrary response body not encoded in JSON.
Generate a Network Packet Loss Rate Report
This API generates a network packet loss rate report for the given interval.
In order to be able to generate reports, your account needs to be provisioned accordingly. Please contact your primary Phenix technical support contact if you wish to use reporting.
Request
Send a PUT
request to pcast/network/packet-loss-rate
endpoint as shown:
PUT pcast/network/packet-loss-rate HTTP / 1.1
Host : pcast.phenixrts.com
Accept : application/json
Content-Type : application/json
Content-Length : 185
Authorization : Basic YXBwbGljYXRpb25JZDpzZWNyZXQ=
{
"networkReport" : {
"applicationIds" : [ "example.com" ],
"start" : "2021-01-01T00:00:00Z" ,
"end" : "2021-01-02T00:00:00Z"
}
}
$ curl https://pcast.phenixrts.com/pcast/network/packet-loss-rate \
-u <applicationId>:<secret> \
-H "Accept: text/csv" \
-H "Content-Type: application/json" \
-X PUT \
-d '{
"networkReport": {
"applicationIds": ["test"],
"start": "2022-04-05T10:00:00Z",
"end": "2022-04-05T18:10:00Z",
"streamIds": ["local#standalone.WHFHRnl6.20220405.PS3S3QsW"]
}
}'
--remote-name
--remote-header-name
Header
Description
Authorization (required)
Use HTTP Basic Authentication with your applicationId and secret
Request Fields
Field
Description
networkReport (required)
See NetworkReport object below
NetworkReport Object
Field
Description
applicationIds (optional)
Array of applications IDs to report for. By default, it will report network for the application ID from credentials.
streamIds (optional)
Array of stream IDs to report for. Limits the report to just these streams.
channelIds (optional)
Array of channel IDs to report for. Limits the report to just these channels IDs.
channelAliases (optional)
Array of channel aliases to report for. Limits the report to just these channel aliases.
roomIds (optional)
Array of room IDs to report for. Limits the report to just these rooms.
roomAliases (optional)
Array of room aliases to report for. Limits the report to just these rooms.
start (required)
The report start time. Either an RFC3339 timestamp string or an integer of UNIX epoch time in milliseconds.
end (required)
The report end time. Either an RFC3339 timestamp string or an integer of UNIX epoch time in milliseconds.
Note: All filter conditions are cumulative.
Response
The response is in CSV format.
Report Response Fields
Column
Description
TimeBucket
Aggregated time bucket (in invervals of SECONDS)
✔
MinimalTimestamp
Minimal timestamp window of normalized PacketLossRate
✔
MaximalTimestamp
Maximal timestamp window of PacketLossRate
✔
Kind
Kind/Media type of the stream
✔
NumberOfSsrc
Total number of Synchronization Source(s) in TimeBucket
✔
NumberOfStreams
Total number of Stream(s) in TimeBucket
✔
PacketLossRate
Average Packet loss rate over set of filtered SSRC streams in TimeBucket
✔
HTTP / 1.1 200 OK
Content-Type : application/json; charset=utf-8
Content-Length : 1604
Content-Disposition : attachment; filename="20220422T110526Z-START20220405T100000Z-END20220405T181000Z-PacketLossRate-JdxuIr.csv"
TimeBucket , MinimalTimestamp , MaximalTimestamp , Kind , NumberOfSsrc , NumberOfStreams , PacketLossRate
2022-04-05 13 : 40 : 36 UTC , 2022-04-05 13 : 40 : 36.498 UTC , 2022-04-05 13 : 40 : 36.498 UTC , audio , 1 , 1 , 0.5
2022-04-05 13 : 40 : 37 UTC , 2022-04-05 13 : 40 : 37.501 UTC , 2022-04-05 13 : 40 : 37.501 UTC , audio , 1 , 1 , 0.2578125
2022-04-05 13 : 40 : 38 UTC , 2022-04-05 13 : 40 : 38.502 UTC , 2022-04-05 13 : 40 : 38.899 UTC , audio , 1 , 1 , 0.275390625
2022-04-05 13 : 40 : 39 UTC ,,, audio , 1 , 1 ,
2022-04-05 13 : 40 : 40 UTC , 2022-04-05 13 : 40 : 40.418 UTC , 2022-04-05 13 : 40 : 40.902 UTC , audio , 1 , 1 , 0.376953125
2022-04-05 13 : 40 : 41 UTC , 2022-04-05 13 : 40 : 41.903 UTC , 2022-04-05 13 : 40 : 41.903 UTC , audio , 1 , 1 , 0.42578125
2022-04-05 13 : 40 : 42 UTC ,,, audio , 1 , 1 ,
2022-04-05 13 : 40 : 43 UTC , 2022-04-05 13 : 40 : 43.42 UTC , 2022-04-05 13 : 40 : 43.42 UTC , audio , 1 , 1 , 0.31640625
2022-04-05 13 : 40 : 44 UTC , 2022-04-05 13 : 40 : 44.42 UTC , 2022-04-05 13 : 40 : 44.42 UTC , audio , 1 , 1 , 0.40625
2022-04-05 13 : 40 : 45 UTC , 2022-04-05 13 : 40 : 45.421 UTC , 2022-04-05 13 : 40 : 45.421 UTC , audio , 1 , 1 , 0.2578125
2022-04-05 13 : 40 : 46 UTC , 2022-04-05 13 : 40 : 46.899 UTC , 2022-04-05 13 : 40 : 46.899 UTC , audio , 1 , 1 , 0.30859375
2022-04-05 13 : 40 : 47 UTC ,,, audio , 1 , 1 ,
2022-04-05 13 : 40 : 48 UTC , 2022-04-05 13 : 40 : 48.418 UTC , 2022-04-05 13 : 40 : 48.418 UTC , audio , 1 , 1 , 0.27734375
2022-04-05 13 : 40 : 49 UTC , 2022-04-05 13 : 40 : 49.419 UTC , 2022-04-05 13 : 40 : 49.419 UTC , audio , 1 , 1 , 0.27734375
2022-04-05 13 : 40 : 50 UTC ,,, audio , 1 , 1 ,
2022-04-05 13 : 40 : 51 UTC , 2022-04-05 13 : 40 : 51.423 UTC , 2022-04-05 13 : 40 : 51.423 UTC , audio , 1 , 1 , 0.5
2022-04-05 13 : 40 : 52 UTC , 2022-04-05 13 : 40 : 52.419 UTC , 2022-04-05 13 : 40 : 52.419 UTC , audio , 1 , 1 , 0.1171875
2022-04-05 13 : 40 : 53 UTC , 2022-04-05 13 : 40 : 53.422 UTC , 2022-04-05 13 : 40 : 53.422 UTC , audio , 1 , 1 , 0.1171875
2022-04-05 13 : 40 : 54 UTC , 2022-04-05 13 : 40 : 54.421 UTC , 2022-04-05 13 : 40 : 54.421 UTC , audio , 1 , 1 , 0.4140625
2022-04-05 13 : 40 : 55 UTC , 2022-04-05 13 : 40 : 55.419 UTC , 2022-04-05 13 : 40 : 55.419 UTC , audio , 1 , 1 , 0.20703125
2022-04-05 13 : 40 : 56 UTC , 2022-04-05 13 : 40 : 56.422 UTC , 2022-04-05 13 : 40 : 56.422 UTC , audio , 1 , 1 , 0.23828125
2022-04-05 13 : 40 : 57 UTC ,,, audio , 1 , 1 ,
2022-04-05 13 : 40 : 58 UTC , 2022-04-05 13 : 40 : 58.418 UTC , 2022-04-05 13 : 40 : 58.418 UTC , audio , 1 , 1 , 0.25
2022-04-05 13 : 40 : 59 UTC , 2022-04-05 13 : 40 : 59.422 UTC , 2022-04-05 13 : 40 : 59.9 UTC , audio , 1 , 1 , 0.2578125
2022-04-05 13 : 41 : 00 UTC ,,, audio , 1 , 1 ,
2022-04-05 13 : 41 : 01 UTC , 2022-04-05 13 : 41 : 0 1.42 UTC , 2022-04-05 13 : 41 : 0 1.42 UTC , audio , 1 , 1 , 0.3984375
2022-04-05 13 : 41 : 02 UTC , 2022-04-05 13 : 41 : 0 2.421 UTC , 2022-04-05 13 : 41 : 0 2.421 UTC , audio , 1 , 1 , 0.31640625
2022-04-05 13 : 41 : 03 UTC , 2022-04-05 13 : 41 : 0 3.422 UTC , 2022-04-05 13 : 41 : 0 3.422 UTC , audio , 1 , 1 , 0.28515625
2022-04-05 13 : 41 : 04 UTC , 2022-04-05 13 : 41 : 0 4.421 UTC , 2022-04-05 13 : 41 : 0 4.421 UTC , audio , 1 , 1 , 0.3515625
2022-04-05 13 : 41 : 05 UTC , 2022-04-05 13 : 41 : 0 5.42 UTC , 2022-04-05 13 : 41 : 0 5.42 UTC , audio , 1 , 1 , 0.30078125
2022-04-05 13 : 41 : 06 UTC , 2022-04-05 13 : 41 : 0 6.423 UTC , 2022-04-05 13 : 41 : 0 6.423 UTC , audio , 1 , 1 , 0.359375
2022-04-05 13 : 41 : 07 UTC , 2022-04-05 13 : 41 : 0 7.423 UTC , 2022-04-05 13 : 41 : 0 7.423 UTC , audio , 1 , 1 , 0.33203125
2022-04-05 13 : 41 : 08 UTC , 2022-04-05 13 : 41 : 0 8.903 UTC , 2022-04-05 13 : 41 : 0 8.903 UTC , audio , 1 , 1 , 0.2734375
2022-04-05 13 : 41 : 09 UTC ,,, audio , 1 , 1 ,
2022-04-05 13 : 41 : 10 UTC , 2022-04-05 13 : 41 : 10.423 UTC , 2022-04-05 13 : 41 : 10.423 UTC , audio , 1 , 1 , 0.28125
2022-04-05 13 : 41 : 11 UTC , 2022-04-05 13 : 41 : 11.422 UTC , 2022-04-05 13 : 41 : 11.422 UTC , audio , 1 , 1 , 0.2578125
2022-04-05 13 : 41 : 12 UTC , 2022-04-05 13 : 41 : 12.422 UTC , 2022-04-05 13 : 41 : 12.422 UTC , audio , 1 , 1 , 0.18359375
2022-04-05 13 : 41 : 13 UTC ,,, audio , 1 , 1 ,
2022-04-05 13 : 41 : 14 UTC , 2022-04-05 13 : 41 : 14.421 UTC , 2022-04-05 13 : 41 : 14.421 UTC , audio , 1 , 1 , 0.27734375
2022-04-05 13 : 41 : 15 UTC , 2022-04-05 13 : 41 : 15.422 UTC , 2022-04-05 13 : 41 : 15.422 UTC , audio , 1 , 1 , 0.375
2022-04-05 13 : 41 : 16 UTC , 2022-04-05 13 : 41 : 16.422 UTC , 2022-04-05 13 : 41 : 16.903 UTC , audio , 1 , 1 , 0.265625
2022-04-05 13 : 41 : 17 UTC ,,, audio , 1 , 1 ,
2022-04-05 13 : 41 : 18 UTC , 2022-04-05 13 : 41 : 18.423 UTC , 2022-04-05 13 : 41 : 18.903 UTC , audio , 1 , 1 , 0.330078125
2022-04-05 13 : 41 : 19 UTC , 2022-04-05 13 : 41 : 19.903 UTC , 2022-04-05 13 : 41 : 19.903 UTC , audio , 1 , 1 , 0.15625
2022-04-05 13 : 41 : 20 UTC ,,, audio , 1 , 1 ,
2022-04-05 13 : 41 : 21 UTC , 2022-04-05 13 : 41 : 21.422 UTC , 2022-04-05 13 : 41 : 21.422 UTC , audio , 1 , 1 , 0.1640625
2022-04-05 13 : 41 : 22 UTC , 2022-04-05 13 : 41 : 22.423 UTC , 2022-04-05 13 : 41 : 22.904 UTC , audio , 1 , 1 , 0.240234375
2022-04-05 13 : 41 : 23 UTC , 2022-04-05 13 : 41 : 23.903 UTC , 2022-04-05 13 : 41 : 23.903 UTC , audio , 1 , 1 , 0.2578125
2022-04-05 13 : 41 : 24 UTC , 2022-04-05 13 : 41 : 24.903 UTC , 2022-04-05 13 : 41 : 24.903 UTC , audio , 1 , 1 , 0.296875
2022-04-05 13 : 41 : 25 UTC ,,, audio , 1 , 1 ,
2022-04-05 13 : 41 : 26 UTC , 2022-04-05 13 : 41 : 26.422 UTC , 2022-04-05 13 : 41 : 26.422 UTC , audio , 1 , 1 , 0.21484375
2022-04-05 13 : 41 : 27 UTC ,,, audio , 1 , 1 ,
2022-04-05 13 : 41 : 28 UTC ,,, audio , 1 , 1 ,
2022-04-05 13 : 41 : 29 UTC ,,, audio , 1 , 1 ,
2022-04-05 13 : 41 : 30 UTC , 2022-04-05 13 : 41 : 30.419 UTC , 2022-04-05 13 : 41 : 30.419 UTC , audio , 1 , 1 , 0.27734375
2022-04-05 13 : 41 : 31 UTC , 2022-04-05 13 : 41 : 31.418 UTC , 2022-04-05 13 : 41 : 31.903 UTC , audio , 1 , 1 , 0.234375
2022-04-05 13 : 41 : 32 UTC ,,, audio , 1 , 1 ,
2022-04-05 13 : 41 : 33 UTC , 2022-04-05 13 : 41 : 33.422 UTC , 2022-04-05 13 : 41 : 33.903 UTC , audio , 1 , 1 , 0.279296875
2022-04-05 13 : 41 : 34 UTC ,,, audio , 1 , 1 ,
2022-04-05 13 : 41 : 35 UTC , 2022-04-05 13 : 41 : 35.422 UTC , 2022-04-05 13 : 41 : 35.899 UTC , audio , 1 , 1 , 0.2578125
2022-04-05 13 : 40 : 37 UTC , 2022-04-05 13 : 40 : 37.399 UTC , 2022-04-05 13 : 40 : 37.399 UTC , video , 1 , 1 , 0.10546875
2022-04-05 13 : 40 : 38 UTC , 2022-04-05 13 : 40 : 38.65 UTC , 2022-04-05 13 : 40 : 38.65 UTC , video , 1 , 1 , 0.12890625
2022-04-05 13 : 40 : 39 UTC , 2022-04-05 13 : 40 : 39.497 UTC , 2022-04-05 13 : 40 : 39.497 UTC , video , 1 , 1 , 0
2022-04-05 13 : 40 : 40 UTC , 2022-04-05 13 : 40 : 40.538 UTC , 2022-04-05 13 : 40 : 40.538 UTC , video , 1 , 1 , 0.046875
2022-04-05 13 : 40 : 41 UTC , 2022-04-05 13 : 40 : 41.523 UTC , 2022-04-05 13 : 40 : 41.523 UTC , video , 1 , 1 , 0.12109375
2022-04-05 13 : 40 : 42 UTC , 2022-04-05 13 : 40 : 42.491 UTC , 2022-04-05 13 : 40 : 42.491 UTC , video , 1 , 1 , 0.0859375
2022-04-05 13 : 40 : 43 UTC , 2022-04-05 13 : 40 : 43.534 UTC , 2022-04-05 13 : 40 : 43.534 UTC , video , 1 , 1 , 0.078125
2022-04-05 13 : 40 : 44 UTC , 2022-04-05 13 : 40 : 44.65 UTC , 2022-04-05 13 : 40 : 44.65 UTC , video , 1 , 1 , 0.07421875
2022-04-05 13 : 40 : 45 UTC , 2022-04-05 13 : 40 : 45.618 UTC , 2022-04-05 13 : 40 : 45.618 UTC , video , 1 , 1 , 0.05078125
2022-04-05 13 : 40 : 46 UTC , 2022-04-05 13 : 40 : 46.623 UTC , 2022-04-05 13 : 40 : 46.623 UTC , video , 1 , 1 , 0.10546875
2022-04-05 13 : 40 : 47 UTC , 2022-04-05 13 : 40 : 47.609 UTC , 2022-04-05 13 : 40 : 47.609 UTC , video , 1 , 1 , 0.08203125
2022-04-05 13 : 40 : 48 UTC , 2022-04-05 13 : 40 : 48.682 UTC , 2022-04-05 13 : 40 : 48.682 UTC , video , 1 , 1 , 0.0546875
2022-04-05 13 : 40 : 49 UTC , 2022-04-05 13 : 40 : 49.137 UTC , 2022-04-05 13 : 40 : 49.137 UTC , video , 1 , 1 , 0.0859375
2022-04-05 13 : 40 : 50 UTC , 2022-04-05 13 : 40 : 50.185 UTC , 2022-04-05 13 : 40 : 50.185 UTC , video , 1 , 1 , 0.0859375
2022-04-05 13 : 40 : 51 UTC , 2022-04-05 13 : 40 : 51.656 UTC , 2022-04-05 13 : 40 : 51.656 UTC , video , 1 , 1 , 0.0546875
2022-04-05 13 : 40 : 52 UTC , 2022-04-05 13 : 40 : 52.655 UTC , 2022-04-05 13 : 40 : 52.655 UTC , video , 1 , 1 , 0.0859375
2022-04-05 13 : 40 : 53 UTC , 2022-04-05 13 : 40 : 53.695 UTC , 2022-04-05 13 : 40 : 53.695 UTC , video , 1 , 1 , 0.06640625
2022-04-05 13 : 40 : 54 UTC , 2022-04-05 13 : 40 : 54.215 UTC , 2022-04-05 13 : 40 : 54.215 UTC , video , 1 , 1 , 0.0625
2022-04-05 13 : 40 : 55 UTC , 2022-04-05 13 : 40 : 55.246 UTC , 2022-04-05 13 : 40 : 55.246 UTC , video , 1 , 1 , 0.0625
2022-04-05 13 : 40 : 56 UTC , 2022-04-05 13 : 40 : 56.275 UTC , 2022-04-05 13 : 40 : 56.275 UTC , video , 1 , 1 , 0.1015625
2022-04-05 13 : 40 : 57 UTC , 2022-04-05 13 : 40 : 57.309 UTC , 2022-04-05 13 : 40 : 57.309 UTC , video , 1 , 1 , 0.06640625
2022-04-05 13 : 40 : 58 UTC , 2022-04-05 13 : 40 : 58.39 UTC , 2022-04-05 13 : 40 : 58.92 UTC , video , 1 , 1 , 0.0546875
2022-04-05 13 : 40 : 59 UTC , 2022-04-05 13 : 40 : 59.89 UTC , 2022-04-05 13 : 40 : 59.89 UTC , video , 1 , 1 , 0.04296875
2022-04-05 13 : 41 : 00 UTC ,,, video , 1 , 1 ,
2022-04-05 13 : 41 : 01 UTC , 2022-04-05 13 : 41 : 0 1.46 UTC , 2022-04-05 13 : 41 : 0 1.46 UTC , video , 1 , 1 , 0.0625
2022-04-05 13 : 41 : 02 UTC , 2022-04-05 13 : 41 : 0 2.46 UTC , 2022-04-05 13 : 41 : 0 2.46 UTC , video , 1 , 1 , 0.05078125
2022-04-05 13 : 41 : 03 UTC , 2022-04-05 13 : 41 : 0 3.532 UTC , 2022-04-05 13 : 41 : 0 3.532 UTC , video , 1 , 1 , 0.08203125
2022-04-05 13 : 41 : 04 UTC , 2022-04-05 13 : 41 : 0 4.56 UTC , 2022-04-05 13 : 41 : 0 4.56 UTC , video , 1 , 1 , 0.05859375
2022-04-05 13 : 41 : 05 UTC , 2022-04-05 13 : 41 : 0 5.524 UTC , 2022-04-05 13 : 41 : 0 5.524 UTC , video , 1 , 1 , 0.10546875
2022-04-05 13 : 41 : 06 UTC , 2022-04-05 13 : 41 : 0 6.56 UTC , 2022-04-05 13 : 41 : 0 6.56 UTC , video , 1 , 1 , 0.04296875
2022-04-05 13 : 41 : 07 UTC , 2022-04-05 13 : 41 : 0 7.524 UTC , 2022-04-05 13 : 41 : 0 7.524 UTC , video , 1 , 1 , 0.08203125
2022-04-05 13 : 41 : 08 UTC , 2022-04-05 13 : 41 : 0 8.045 UTC , 2022-04-05 13 : 41 : 0 8.987 UTC , video , 1 , 1 , 0.052734375
2022-04-05 13 : 41 : 09 UTC ,,, video , 1 , 1 ,
2022-04-05 13 : 41 : 10 UTC , 2022-04-05 13 : 41 : 10.503 UTC , 2022-04-05 13 : 41 : 10.503 UTC , video , 1 , 1 , 0.1171875
2022-04-05 13 : 41 : 11 UTC , 2022-04-05 13 : 41 : 11.085 UTC , 2022-04-05 13 : 41 : 11.085 UTC , video , 1 , 1 , 0.0625
2022-04-05 13 : 41 : 12 UTC , 2022-04-05 13 : 41 : 12.649 UTC , 2022-04-05 13 : 41 : 12.649 UTC , video , 1 , 1 , 0.0546875
2022-04-05 13 : 41 : 13 UTC , 2022-04-05 13 : 41 : 13.631 UTC , 2022-04-05 13 : 41 : 13.631 UTC , video , 1 , 1 , 0.0703125
2022-04-05 13 : 41 : 14 UTC , 2022-04-05 13 : 41 : 14.196 UTC , 2022-04-05 13 : 41 : 14.196 UTC , video , 1 , 1 , 0.08203125
2022-04-05 13 : 41 : 15 UTC , 2022-04-05 13 : 41 : 15.739 UTC , 2022-04-05 13 : 41 : 15.739 UTC , video , 1 , 1 , 0.02734375
2022-04-05 13 : 41 : 16 UTC , 2022-04-05 13 : 41 : 16.286 UTC , 2022-04-05 13 : 41 : 16.286 UTC , video , 1 , 1 , 0.14453125
2022-04-05 13 : 41 : 17 UTC , 2022-04-05 13 : 41 : 17.325 UTC , 2022-04-05 13 : 41 : 17.777 UTC , video , 1 , 1 , 0.05078125
2022-04-05 13 : 41 : 18 UTC ,,, video , 1 , 1 ,
2022-04-05 13 : 41 : 19 UTC , 2022-04-05 13 : 41 : 19.348 UTC , 2022-04-05 13 : 41 : 19.841 UTC , video , 1 , 1 , 0.06640625
2022-04-05 13 : 41 : 20 UTC ,,, video , 1 , 1 ,
2022-04-05 13 : 41 : 21 UTC , 2022-04-05 13 : 41 : 21.337 UTC , 2022-04-05 13 : 41 : 21.337 UTC , video , 1 , 1 , 0.05859375
2022-04-05 13 : 41 : 22 UTC ,,, video , 1 , 1 ,
2022-04-05 13 : 41 : 23 UTC , 2022-04-05 13 : 41 : 23.464 UTC , 2022-04-05 13 : 41 : 23.464 UTC , video , 1 , 1 , 0.0546875
2022-04-05 13 : 41 : 24 UTC , 2022-04-05 13 : 41 : 24.053 UTC , 2022-04-05 13 : 41 : 24.053 UTC , video , 1 , 1 , 0.0546875
2022-04-05 13 : 41 : 25 UTC , 2022-04-05 13 : 41 : 25.58 UTC , 2022-04-05 13 : 41 : 25.58 UTC , video , 1 , 1 , 0.109375
2022-04-05 13 : 41 : 26 UTC , 2022-04-05 13 : 41 : 26.653 UTC , 2022-04-05 13 : 41 : 26.653 UTC , video , 1 , 1 , 0.11328125
2022-04-05 13 : 41 : 27 UTC , 2022-04-05 13 : 41 : 27.754 UTC , 2022-04-05 13 : 41 : 27.754 UTC , video , 1 , 1 , 0.09765625
2022-04-05 13 : 41 : 28 UTC , 2022-04-05 13 : 41 : 28.684 UTC , 2022-04-05 13 : 41 : 28.684 UTC , video , 1 , 1 , 0.07421875
2022-04-05 13 : 41 : 29 UTC , 2022-04-05 13 : 41 : 29.156 UTC , 2022-04-05 13 : 41 : 29.156 UTC , video , 1 , 1 , 0.05078125
2022-04-05 13 : 41 : 30 UTC , 2022-04-05 13 : 41 : 30.756 UTC , 2022-04-05 13 : 41 : 30.756 UTC , video , 1 , 1 , 0.03515625
2022-04-05 13 : 41 : 31 UTC , 2022-04-05 13 : 41 : 31.684 UTC , 2022-04-05 13 : 41 : 31.684 UTC , video , 1 , 1 , 0.0703125
2022-04-05 13 : 41 : 32 UTC , 2022-04-05 13 : 41 : 32.776 UTC , 2022-04-05 13 : 41 : 32.776 UTC , video , 1 , 1 , 0.04296875
2022-04-05 13 : 41 : 33 UTC , 2022-04-05 13 : 41 : 33.29 UTC , 2022-04-05 13 : 41 : 33.29 UTC , video , 1 , 1 , 0.07421875
2022-04-05 13 : 41 : 34 UTC , 2022-04-05 13 : 41 : 34.782 UTC , 2022-04-05 13 : 41 : 34.782 UTC , video , 1 , 1 , 0.08203125
2022-04-05 13 : 41 : 35 UTC , 2022-04-05 13 : 41 : 35.36 UTC , 2022-04-05 13 : 41 : 35.36 UTC , video , 1 , 1 , 0.11328125
2022-04-05 13 : 41 : 36 UTC , 2022-04-05 13 : 41 : 36.297 UTC , 2022-04-05 13 : 41 : 36.297 UTC , video , 1 , 1 , 0.02734375
curl: Saved to filename '20220407T125518Z-START20220405T100000Z-END20220405T181000Z-PacketLossRate-3VreKW.csv'
If the request fails, the platform will return a failed response that contains a “status” field. The HTTP status code is set according to the “status” field.
HTTP / 1.1 400 Bad request
Content-Type : application/json; charset=utf-8
Content-Length : 39
{ "status" : "excessive-report-interval" }
$ cat network
{
"status" :"excessive-report-interval"
}
Network Packet Loss Rate Report API Response Fields
Field
Description
status
See status codes below
Network Packet Loss Rate Report API Status Codes
HTTP
Status
Retry
Description
200 OK
ok
never
Report was successfully created.
400 Bad Request
<varies>
never
Indicates an issue with the request.
400 Bad Request
excessive-report-interval
never
The interval for the report exceed 1 day.
400 Bad Request
period-start-outside-supported-window
never
The year of the start of period is more than 1 year before the current year.
400 Bad Request
period-end-must-be-in-past
never
The end of period is in future.
400 Bad Request
period-end-must-be-after-start
never
The end of period is less than or equal to the start of the period.
400 Bad Request
unsupported
never
The parameter combination is not supported.
401 Unauthorized
unauthorized
never
The streaming platform was not able to authorize the provided credentials.
408 Request Timeout
request-timeout
once immediately, then exponential backoff
Request timed out likely due to temporary resource or network conditions. Please try again.
4XX
<varies>
never
Indicates an issue with the request.
503 Service Unavailable
capacity
once
The system is temporarily overloaded. Please try again later.
5XX
<varies>
once immediately, then exponential backoff
A transient server error.
Error Responses : Please be aware that some server errors 5XX and request validation errors 400 and 401 may result in an arbitrary response body not encoded in JSON.
Analytics API
APIs for generating analytics reports
Generate a Concurrent Viewing Streams Report
This API generates a concurrent viewing streams report for the given interval.
In order to be able to generate reports, your account needs to be provisioned accordingly. Please contact your primary Phenix technical support contact if you wish to use analytics.
Request
Send a PUT
request to pcast/streams/concurrent
endpoint as shown:
PUT pcast/streams/concurrent HTTP / 1.1
Host : pcast.phenixrts.com
Accept : application/json
Content-Type : application/json
Content-Length : 174
Authorization : Basic YXBwbGljYXRpb25JZDpzZWNyZXQ=
{
"concurrentViewingStreamsReport" : {
"applicationIds" : [ "example.com" ],
"start" : "2020-01-01T00:00:00Z" ,
"end" : "2020-01-02T00:00:00Z"
}
}
$ curl https://pcast.phenixrts.com/pcast/streams/concurrent \
-u <applicationId>:<secret> \
-H "Accept: text/csv" \
-H "Content-Type: application/json" \
-X PUT \
-d '{
"concurrentViewingStreamsReport": {
"applicationIds": ["example.com"],
"start": "2020-01-01T00:00:00Z",
"end": "2020-01-02T00:00:00Z"
}
}'
--remote-name
--remote-header-name
Header
Description
Authorization (required)
Use HTTP Basic Authentication with your applicationId and secret
Request Fields
Field
Description
concurrentViewingStreamsReport (required)
See ConcurrentViewingStreamsReport object below
ConcurrentViewingStreamsReport Object
Field
Description
applicationIds (optional)
Array of applications IDs to report for. By default, it will report viewing streams for the application ID from credentials.
streamIds (optional)
Array of origin stream IDs to report for. Limits the report to viewing streams of just these origin streams.
channelIds (optional)
Array of channel IDs to report for. Limits the report to just these channel IDs.
channelAliases (optional)
Array of channel aliases to report for. Limits the report to just these channel aliases.
originTags (optional)
Array of origin Tags to report for. Limits the report to viewing streams of only origin streams with these tags.
viewerTags (optional)
Array of viewer Tags to report for. Limist the report to only viewing streams with these tags.
start (required)
The report start time. Either an RFC3339 timestamp string or an integer of UNIX epoch time in milliseconds.
end (required)
The report end time. Either an RFC3339 timestamp string or an integer of UNIX epoch time in milliseconds.
Note: All filter conditions are cumulative.
Response
The response is in CSV format.
Report Response Fields
Column
Description
ApplicationId
Application ID for which number of concurrent viewing streams is counted
Timestamp
The time at which number of concurrent viewing streams is counted
Concurrent
Number of concurrent viewing streams
HTTP / 1.1 200 OK
Content-Type : application/json; charset=utf-8
Content-Length : 85
Content-Disposition : attachment; filename="20200204T171148Z-START20200101T000000Z-END20200102T000000Z-ConcurrentViewingStreams-RWYkT1.csv"
ApplicationId , Timestamp , Concurrent
example.com , 2020-01-01 20 : 16 : 38 , 200
example.com , 2020-01-01 20 : 16 : 39 , 15
example.com , 2020-01-01 20 : 16 : 40 , 2
curl: Saved to filename '20200204T171148Z-START20200101T000000Z-END20200102T000000Z-ConcurrentViewingStreams-RWYkT1.csv'
If the request fails, the platform will return a failed response that contains a “status” field. The HTTP status code is set according to the “status” field.
HTTP / 1.1 400 Bad request
Content-Type : application/json; charset=utf-8
Content-Length : 37
{ "status" : "excessive-report-interval" }
$ cat concurrent
{
"status" :"excessive-report-interval"
}
Concurrent Viewing Streams Report API Response Fields
Field
Description
status
See status codes below
Concurrent Viewing Streams Report API Status Codes
HTTP
Status
Retry
Description
200 OK
ok
never
Report was successfully created.
400 Bad Request
<varies>
never
Indicates an issue with the request.
400 Bad Request
excessive-report-interval
never
The interval for the report exceed 1 day.
400 Bad Request
period-start-outside-supported-window
never
The year of the start of period is more than 1 year before the current year.
400 Bad Request
period-end-must-be-in-past
never
The end of period is in future.
400 Bad Request
period-end-must-be-after-start
never
The end of period is less than or equal to the start of the period.
400 Bad Request
unsupported
never
The parameter combination is not supported.
401 Unauthorized
unauthorized
never
The streaming platform was not able to authorize the provided credentials.
4XX
<varies>
never
Indicates an issue with the request.
503 Service Unavailable
capacity
once
The system is temporarily overloaded. Please try again later.
5XX
<varies>
once immediately, then exponential backoff
A transient server error.
Error Responses : Please be aware that some server errors 5XX and request validation errors 400 and 401 may result in an arbitrary response body not encoded in JSON.
Authentication
Authentication is required for working with our HTTP APIs. Currently there are 2 ways of sending credentials in the request.
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
Combine the applicationId
and the secret
with a colon applicationId:secret
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 \
base64 Encoding : base64 is a reversible encoding. Please use HTTPS along with Basic Authentication.
HTTP Request Body Authentication (deprecated)
You can pass credentials in the request body as shown:
{
"credentials": {
"applicationId": "<applicationId>",
"secret": "<secret>"
}
}
Credentials Object
Field
Description
applicationId (required)
Application ID
secret (required)
Appplication secret
Passing the Credentials in request body is deprecated and supported only for backward compatibility. The preferred way of passing the Credentials is through HTTP Authentication Header
RTMP Ingest
Phenix supports ingest via RTMP push directly into a channel.
Push your RTMP feed to rtmp://ingest.phenixrts.com:80/ingest/
using this stream key from the channel API .
The basic RTMP URL looks as follows:
rtmp://ingest.phenixrts.com:80/ingest/{STREAMKEY}
Additional options, such as capabilities and tags, may be provided in the URL separated by semicolons, for example:
rtmp://ingest.phenixrts.com:80/ingest/{STREAMKEY};capabilities=hd,multi-bitrate,prefer-h264;tags=my-awesome-stream-id,my-customer-id
If your system does not allow the inclusion of semicolons in the URL, the |
(pipe) can be used instead, for example:
rtmp://ingest.phenixrts.com:80/ingest/{STREAMKEY}|capabilities=hd,multi-bitrate,prefer-h264|tags=my-awesome-stream-id,my-customer-id
RTMP URL Options
Option
Default
Description
capabilities
hd,multi-bitrate
A comma separated list of capabilities for the published stream.
tags
A comma separated list of custom tags.
maxFps
30
[Advanced] Controls the maximal frame rate sampled from the source signal. Support of signals with more than 30 FPS is experimental.
buffer
500
[Advanced] The amount of buffer to use on the ingest side to compensate for network jitter.
prerollSkipDuration
500
[Experimental] Milliseconds to skip at the beginning of the stream.
jitterBuffer
${buffer}
[Experimental] The amount of jitter buffer to use after decoding and sampling of the ingest signal. This value should generally equal or larger than buffer
.
screenName
[Experimental] The screen name of the channel member representing this ingest. The screen name is automatically chosen to properly enable functionality like HA publishing.
Please note that changing options marked as experimental may alter expected behavior and may have unintended side effects and therefore should only be modified after consultation with the Phenix support staff.
High Availability
The Phenix platform is built with high availability (HA) in mind for all system components from encoding and ingest through to client connections to the platform. The autonomous operation architecture ensures that faults are detected and corrected without any administrative or end-user impacts.
HA Ingest is the ability to send data into multiple redundant data centers over redundant networking connections effectively addresses risks of origin and first mile failures. Thus providing a deployment with complete end-to-end redundancy.
Please contact your primary Phenix technical support contact if you wish to use HA Ingest and for instructions on how to set it up.