REST API Overview - PhenixRTS Docs

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

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

For example:

POST /pcast/composition HTTP/1.1
Host: pcast.phenixrts.com
Accept: application/json
Content-Type: application/json
Content-Length: 249
Authorization: Basic YXBwbGljYXRpb25JZDpzZWNyZXQ=
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) Application 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.

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

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