REST API Overview
The REST 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.
Authentication
Authentication is required for working with our HTTP APIs. Currently there are 2 ways of sending credentials in the request.
HTTP Authentication Header
Pass credentials for authentication using the HTTP Authorization request header as shown:
Authorization: <type> <credentials>
Authorization Type
Field | Description |
---|---|
Basic | Use "Basic" authentication scheme |
Authorization Credentials
- Combine the
applicationId
and thesecret
with a colonapplicationId:secret
- base64 encoded the resulting string
YXBwbGljYXRpb25JZDpzZWNyZXQ=
For example:
1POST /pcast/composition HTTP/1.12Host: pcast.phenixrts.com3Accept: application/json4Content-Type: application/json5Content-Length: 2496Authorization: Basic YXBwbGljYXRpb25JZDpzZWNyZXQ=
1curl https://pcast.phenixrts.com/pcast/composition \2-H "Accept: application/json" \3-H "Content-Type: application/json" \4-H "Content-Length: 249" \5-u "applicationId:secret" \
HTTP Request Body Authentication (deprecated)
You can pass credentials in the request body as shown:
1{2 "credentials": {3 "applicationId": "<applicationId>",4 "secret": "<secret>"5 }6}
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
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.
1DELETE /pcast/stream HTTP/1.12Host: pcast.phenixrts.com3Accept: application/json4Content-Type: application/json5Content-Length: 12467{8 "applicationId": "<applicationId>",9 "secret": "<secret>",10 "streamId": "<streamId>",11 "reason": "<reason>"12}
1curl https://pcast.phenixrts.com/pcast/stream \2-H "Accept: application/json" \3-H "Content-Type: application/json" \4-X DELETE \5-d '{6 "applicationId": "<applicationId>",7 "secret": "<secret>",8 "streamId": "<streamId>",9 "reason": "<reason>",10 }'
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.
1HTTP/1.1 200 OK2Content-Type: application/json; charset=utf-83Content-Length: 1545{"status":"ok"}
1{2 "status":"ok"3}
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. |