Skip to main content

Introducing the MistServer API

The majority of the MistServer configurations can be done through the API. The API is based on JSON messages over HTTP through HTTP POST and HTTP GET on the default API port 4242. You should send your commands as JSON Objects and MistServer will return the result as a JSON Object depending on the API call made.

Configurations that cannot be done through the API must be done through command line parameters. Options that cannot be set through the API are:

  • Changing the API Port.
  • Changing the Configuration file location
  • Changing admin account/password information
  • Changing configuration read/write behaviour

When MistServer boots an UDP port will also be opened on the ephemeral range, this port is used by MistController to communicate. This port is not intended to be used, though localhost tasks can certainly can access this for the API as well.

Authorization​

More detailed information about authorization can be found in the API reference. Only a basic overview will be given here. Any non-authenticated API request will receive a challenge. This challenge has a value that should be used for your authentication and can be re-used for as long as the login is perceived as active.

{
  "authorize": {
    "username": "test", 
    "password": "MD5( MD5("secret") + challenge)"
  }
}
tip
  • You will need to md5 twice, once for the secret value then once more for the md5(secret)+challenge
  • secret - The password of the account
  • challenge - The challenge response of MistServer when authentication is first attempted.

API requests need authorization against the account/password information you have filled in when you first started with MistServer. The exception to this rule is when the API is accessed from a localhost address. We assume that since you have physical access to the server you are allowed access to the API.

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

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.

API vs API2​

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.

Proxying the API/Interface​

If you're reverse proxying the interface you will want to include either X-Real-IP or X-Forwarded-For to make sure MistServer always requires a login. Without this header API requests will be seen as if they're coming from localhost and will bypass authentication.

Websocket API​

This is the best endpoint to use when receiving near real-time information from the server is important. This does require another authenticate (unless coming from localhost).

The authentication is the same as for the normal API, with the difference that there's no further authentication calls you are now connected and are receiving the data as requested.

There's some small changes in comparison to normal authentication.

  • The server answers with an array
    • The first entry is the type of message ["AUTH","value"]
      • "value" = true - You're logged in
      • "value" = false - You need to log in. The authentication information should be send as an {object}. The authentication follows the same method as HTTP Post.
tip
  • You can re-use authentication information from the HTTP Post login

You can request the following live information:

  • ws://server:4242/ws?logs=amount - Live logs starting with the previous amount of logs
  • ws://server:4242/ws?accs=amount - Live access information with the previous amount available
  • ws://server:4242/ws?streams=1 - Simple live active stream information of all streams
  • ws://server:4242/ws/stream/streamname - Detailed live active stream information of a specific stream.
tip
  • The ws/stream/streamname sends all values every second, not just when a change happens
  • The ws/stream/streamname contains a few admin only values that might not be interesting to know outside of MistServer.
  • Instead of amount since:UNIXTIMESTAMP can also be requested to receive logs starting from a specific point in time.

Localhost only UDP API​

In addition to the above HTTP-based API, it is also possible to access the API from the local machine on UDP port 4242 on the "localhost" address. Whether that is IPv4 or IPv6 localhost is dependent on your operating system default address family, so preferably connect to the hostname "localhost" verbatim to prevent issues.

All regular API requests are supported, and must be sent to port 4242 over UDP. The payload is the raw JSON object with the request(s).

This API endpoint will reply with a UDP packet to the same address and port it received requests from, containing a JSON object with the response. The minimal flag is set automatically for UDP API requests.

This endpoint is particularly useful when combined with the api_endpoint API call.