Tools and software

REST API reference

Overview

Scalable Pixel Streaming REST API allows users to send curl requests or scripted calls directly to the SPS endpoint to query any information from the formation or manipulate any of the existing applications and versions. See this page for examples of creating a new application and assigning a version to it via REST API.

The schema of the Scalable Pixel Streaming public REST API is represented as an OpenAPI definition document, which makes it compatible with the broad ecosystem of tooling configured according to the OpenAPI standard. The documentation for the API is generated using Redoc and is available in two formats: static and dynamic.

Accessing the static API documentation

You can access the static documentation for the latest stable version of the REST API on this page.

Static documentation can be accessed at any time without needing to first install Scalable Pixel Streaming. Note that the static documentation always reflects the latest stable release of Scalable Pixel Streaming, and may differ from the version of Scalable Pixel Streaming that you are using.

Accessing the dynamic API documentation

To access the dynamic documentation after installing your SPS formation, append /api/docs to the end of the REST API endpoint URL, which is listed in the outputs of your installation. Refer to this page to locate them on your cloud provider.

Once your Scalable Pixel Streaming has been installed, the dynamic documentation is served to web browsers by the REST API server itself. This documentation reflects the REST API of your specific Scalable Pixel Streaming installation version.

Examples of REST API requests

Below are several examples of CURL REST API requests that you can use as scaffolding for your pipelines.

GET requests to retrieve information

GET requests are usually straightforward and follow the same pattern as below, differing only by the endpoint. Refer to the API schema for the exact endpoints. For example, this call retrieves the applications list:

curl -X GET \
    -H "Content-Type: application/json" \
    -u admin:<your_rest_api_access_key> \
    https://<sps-your-endpoint-url.com>/api/v1/application

And his call retrieves the details of a specific version of a specific application:

curl -X GET \
    -H "Content-Type: application/json" \
    -u admin:<your_rest_api_access_key> \
    https://<sps-your-endpoint-url.com>/api/v1/application/<your-application-name>/v1/versions/<your-version-name>

GET request to test the access key

Use this request to test your access key and check if it’s valid. This request requires your access key to be encoded in base64:

curl -X GET \
    -H "accessKey:<your_rest_api_access_key_encoded_in_base64>" \
    https://<sps-your-endpoint-url.com>/api/v1/auth

POST requests to create new entries

Use this POST request to create a new application with minimal configuration. You can first make a GET call to /api/v1/skeleton/application endpoint to retrieve the application skeleton, see its structure, and use it in your POST calls with more complicated configurations.

curl -X POST \
    -H "Content-Type: application/json" \
    -u admin:<your_rest_api_access_key> \
    https://<sps-your-endpoint-url.com>/api/v1/application \
    -d "{\"name\":\"<new-application-name>\"}"

Use this POST request to create a version for your application from a public container tag:

curl -X POST \
    -H "Content-Type: application/json" \
    -u admin:<your_rest_api_access_key> \
    https://<sps-your-endpoint-url.com>/api/v1/application/<your-application-name>/v1/versions \
    -d "{\"buildOptions\":{\"input\":{\"type\":\"imageTag\", \"containerTag\":\"<your-container-tag>\"}}, \"name\":\"<new-version-name>\"}"

To create an application from a .zip compressed UE application on supported cloud platforms, first create a blob version:

curl -X POST \
    -H "Content-Type: application/json" \
    -u admin:<your_rest_api_access_key> \
    https://<sps-your-endpoint-url.com>/api/v1/application/<your-application-name>/v1/versions \
    -d "{\"buildOptions\":{\"input\":{\"type\":\"blob\"}}, \"name\":\"<blob-version-name>\"}"

And then use the multiformat POST call to upload your compressed application:

curl -X POST \
    -H "Content-Type: multipart/form-data" \
    -u admin:<your_rest_api_access_key> \
    https://<sps-your-endpoint-url.com>/api/v1/application/<your-application-name>/v1/versions/<blob-version-name> \
    -F file=@"C:\Path\To\Your\Compressed\Application.zip"

PATCH request to update applications

Since versions and instances are immutable, only applications can be edited and updated after creation. You can use a PATCH call to update specific values in your application’s configuration. For example, to update the active version of an application, use this PATCH call:

curl -X PATCH \
    -H "Content-Type: application/json" \
    -u admin:<your_rest_api_access_key> \
    https://<sps-your-endpoint-url.com>/api/v1/application/<your-application-name> \
    -d "[{\"op\": \"replace\",\"path\": \"activeVersion\",\"value\": \"<your-version-name>\"}]"

To update an object, PATCH each of its values individually. For example, to PATCH a resources:{cpu:4,memory:4G} object, use the following PATCH call:

curl -X PATCH \
    -H "Content-Type: application/json" \
    -u admin:<your_rest_api_access_key> \
    https://<sps-your-endpoint-url.com>/api/v1/application/<your-application-name> \
    -d "[{\"op\": \"replace\",\"path\": \"resources/cpu\",\"value\": \"6\" },{\"op\": \"replace\",\"path\": \"resources/memory\",\"value\": \"8G\"}]"

PUT request to update applications

Since versions and instances are immutable, only applications can be edited and updated after creation. You can use a PUT call to update the entire application entity. Use a GET call to /api/v1/skeleton/application endpoint to retrieve the application skeleton and include it in the -d payload with updated values, including the name of the application being updated. The bare minimum call could look like:

curl -X PUT \
    -H "Content-Type: application/json" \
    -u admin:<your_rest_api_access_key> \
    https://<sps-your-endpoint-url.com>/api/v1/application/ \
    -d "{\"cloudPlatformParameters\":\"\",\"hardware\":[],\"name\":\"<your-application-name>\",\"resources\":{\"cpu\":\"6\",\"memory\":\"8G\"},\"signallingServer\":{\"authPluginEndpoint\":\"\",\"builtinPlugins\":{\"authentication\":{\"authType\":\"noop\",\"maxReplicas\":10,\"minReplicas\":2,\"providers\":[{\"name\":\"\",\"oAuthConfig\":{\"endpoint\":{\"authStyle\":0},\"scopes\":[]}}]},\"instanceManager\":{\"customEndpoints\":[],\"maxReplicas\":5,\"minReplicas\":1}},\"customDomainName\":\"\",\"maxReplicas\":10,\"minReplicas\":1,\"peerConnectionOptions\":\"\"}}"

Similarly, you can update your formation configuration via a PUT call to the /api/v1/config endpoint.

DELETE requests to delete entities

You can delete individual applications, versions, and instances by using their name in the endpoint. Refer to the API documentation for the exact endpoints. For example, to delete a version, use this DELETE request:

curl -X DELETE \
    -H "Content-Type: application/json" \
    -u admin:<your_rest_api_access_key> \
    https://<sps-your-endpoint-url.com>/api/v1/application/<your-application-name>/v1/versions/<your-version-name>

Note that to delete applications (whether individually or all), you must pass a ForceDelete flag in the body of the message. This flag needs to be set to true if the application is stuck and truly needs to be force-deleted, or false if it’s a regular delete:

curl -X DELETE \
    -H "Content-Type: application/json" \
    -u admin:<your_rest_api_access_key> \
    https://<sps-your-endpoint-url.com>/api/v1/application/<your-application-name> \
    -d "false"

You can mass-delete all applications or all versions of an application by sending a DELETE call to applicationsAll or versionsAll endpoints respectively (and including a ForceDelete flag for applications), for example:

curl -X DELETE \
    -H "Content-Type: application/json" \
    -u admin:<your_rest_api_access_key> \
    https://<sps-your-endpoint-url.com>/api/v1/application/<your-application-name>/v1/versionsAll \

DELETE supports deleting an array of applications:

curl -X DELETE \
    -H "Content-Type: application/json" \
    -u admin:<your_rest_api_access_key> \
    https://<sps-your-endpoint-url.com>/api/v1/application/ \
    -d "[{\"name\":\"<your-application-1>\", \"force\": false},{\"name\":\"<your-application-2>\",\"force\": true}]"

And, respectively, a list of instances:

curl -X DELETE \
    -H "Content-Type: application/json" \
    -u admin:<your_rest_api_access_key> \
    https://<sps-your-endpoint-url.com>/api/v1/instance/ \
    -d "[\"<sps-instance-1-name>\", \"<sps-instance-2-name>\"]"

Refer to the REST API schema for more details.