Skip to main content

API

All of the configuration of MistServer can be done through its API. The API is based on JSON messages over HTTP.

A default interface implementing this API as a single HTML page is included in the controller itself. This default interface will be send for invalid API requests (to any other URL than /api), and is thus triggered by default when a browser attempts to access the API port directly. The default API port is 4242 - but this can be changed through both the API itself and through command line parameters.

To send an API request, simply send a HTTP request to this port for any file, and include either a GET or POST parameter called "command", containing a JSON object string as payload. When requesting /api or /api2, you are guaranteed to receive a JSON object in return; otherwise sending an invalid request will serve the HTML5 API implementation web interface.

An API call consists of one or more members being sent in the JSON object passed through the "command" parameter, and combining multiple members into a single call is allowed. The output will be similarly combined in that case.

You may also include a "callback" or "jsonp" HTTP parameter, to trigger JSONP compatibility mode. JSONP is useful for getting around the cross-domain scripting protection in most modern browsers. Developers creating non-JavaScript applications will most likely not want or need to use JSONP mode.

An example of an authorization request to the API looks like this:

GET /api?command={"authorize":{"username":"test","password":"941d7b88b2312d4373aff526cf7b6114"}} HTTP/1.0

Or, properly URL encoded:

GET /api?command=%7B%22authorize%22%3A%7B%22username%22%3A%22test%22%2C%22password%22%3A%2294... HTTP/1.0

The server is quite lenient about not URL encoding your strings, but it's a good idea to always URL encode the entire command parameter to prevent it from being interpreted wrongly.

Each API command available will be explained in the following sections.

For historical reasons, the "streams", "config" and "log" API responses are always given, even if not requested, unless the request ""minimal": 1" is sent along with the API requests. When requesting through /api2, the minimal flag is always set automatically.

All versions of MistServer 3.0 will always include the response ""LTS":1" to indicate that they are Pro versions. This is for backwards compatibility, there are no longer any Pro versions, just the open source version.