Control Panel — API documentation

ScaleEngine RESTful API

This API implements a RESTful approach to access and manipulate data. A REST API defines a set of functions which developers can perform requests and receive responses via HTTP protocol such as GET and POST.

Our API makes use of the GET (read), PUT (create), POST (updated), and DELETE (delete) HTTP verbs. Requests are made to their respective endpoints which are named after the specific object desired. To retrieve a stream, the "streams" endpoint would be called with the name of the stream (GET {url}/streams/<stream_name>). To retrieve all streams, no stream name would be given (GET {url}/streams/)

We have two main APIs that can be called, our main for most objects is located on While our file api is located on the file server Make sure to check the objects documentation to verify you are calling the correct server.



Fields are the properties of an object and are included in the responses from their respective endpoints. Fields are defined by the follow attributes:

  • Access type - how the field may be modified (see Access Types page)
  • Type - data type of the field
  • Default - value used on creation if one is not provided
  • Required - whether the field is required on create
  • Unique - whether the field must be unique from all other objects
  • Length - maximum length the value can be set

Parameters are additional data that may be required to fullfil the request, but are not returned in the response. Parameters should be sent as POST data.


Filters are GET parameters that are used to limit or modify results found when retrieving objects. Generally, any non-synthetic field can be used as filters. Some objects may have special filters, known as "options", that modify the results being returned. These filters must be prefixed with option:. The files endpoint can take a "recursive" option and would be requested as option:recursive=2, assuming we want 2 levels of directories to be searched. For example:

The filters section of the object documentation is where you can find details on what filters are allowed and what values are permitted.

You can also prefix a GET parameter with a pipe | operator to do a bitwise AND operation on an integer field. For eg:- |flags=4 will filter objects that return a non-zero value when doing a bitwise AND operation with the value of the flags field. So, valid values of the flags field for |flags=4 would be 4,5,6,7,12 etc.


Objects may have related information that can be accessed through different endpoints, these related objects are not returned by default. To retrieve relational data with the base object the "related" GET parameter is used.

The related parameter takes a comma separated list of objects to include in the response. See the response fields section below for details on the response format.

For example, streamfetches have are related to streams, so we can have the related stream object returned along with the streamfetch:

There are also "children" objects. While a related object is a single item linked to the object in question, there may be multiple child items linked to a single item. Players are children of a stream, because you can have multiple players set up for a single stream. So we can get the child players of a stream:

You can specify multiple child and/or related objects at the same time. Either pass a comma separated list of objects, i.e. option:children=players,streamfetches or send them as http array elements: option:children[]=players&option:children[]=streamfetches


Responses from each endpoint will set a meaningful HTTP status code that be used to determine if the call was successful, unauthorized, or any other type of error that may have occured along with a generic message (see HTTP Status Codes page).

One or more of the following fields will be returned as json.

data Object or Array

Upon success the data field will be set to the respective object based on the endpoint being called or an array of objects when a GET request is made without an ID. If an error occurs the data field will not be present.

related Array

When an object is retrieved using the "related" parameter, the related field will be added to the object. This field is an associative array with the object's type as the key containing an array of those objects.

errors Array

When an error occurs, the errors array will be set containing error objects that need to be corrected before attempting another call. The errors object will include status code, a title, and details on the specific error (see the Errors page)