HTTP API

On one hand, mimoLive publishes a Remote Control UI which you can use to create custom user interfaces that you can use on a tablet or similar device to remote control mimoLive.

Additionally, mimoLive also provides access to the bare HTTP API so you can create custom scripts (via bash and curl, AppleScript, build-in Automation Layer or something similar that can talk to a HTTP server) that control various aspects of mimoLive – the possibilities are nearly endless. (See Examples of API usage)

In this topic we will focus on the bare HTTP API. As the API is based on the json:api specification be sure to familiarize with it before working with the mimoLive API.

*In addition to the documentation you can also have a look at our PHP demo scripts on github .
Also there is a “example for Shell and Apple Script”:doc:examples-of-api-usage available.

API Endpoint

The mimoLive API is accessible on the same machine mimoLive is running on (via “localhost”) and on the local network (via “.local”).

If enabled mimoLive serves a HTTP server on “port 8989”.

All the API calls are prefixed with a path of “/api/v1/” so if you want to get a list of opened documents you would call “http://localhost:8989/api/v1/documents”.

All IDs (for documents, layers, etc.) are stored and persisted to disk, so it is safe to hard code these values as long as the same document is used inside mimoLive.

Authentication

Starting with mimoLive 3.1, if the user enabled authentication in the mimoLive preferences, you need to provide the user password for every request to the API which can be done in two ways:

• Setting the custom HTTP header “X-MimoLive-Password-SHA256: xxxxxxx”
• Appending the query parameter “?pwSHA256=xxxxxxx”

In both cases, xxxxxxx has to be replaced by the original password (in UTF-8 encoding) hashed using SHA-256 and encoded as a string of hexadecimal digits.
To ease development of custom scripts and application, mimoLive shows this API key and allows copying to the clipboard in the Remote Controls preference pane:

Deprecated Authentication Method

Prior to mimoLive version 3.1, requests against the API would be authenticated using the special HTTP header “X-MimoLive-Password: “ or the query parameter “?pw=” on every request.
Unfortunately, this method sends the password in the clear over a potentially insecure network connection which may expose sensitive data if the HTTP API password is being reused elsewhere.
While it continues to work, this authentication method is therefore discouraged and may be removed in the future.

Errors

If an error occurs during a request, mimoLive will stop processing that request and return a HTTP response with its status code indicating the error. The response also contains a JSON payload array of error objects containing additional information about each error that occurred:

{
  "errors": [
    {
      "status": "404",
      "title": "Not Found",
      "description": "The requested object could not be found"
    }
  ]
}

Remote Access via Internet

As the HTTP API is enabled by a webserver built into mimoLive, remote access to the HTTP API from anywhere on the Internet could be enabled by giving the mimoLive computer a public IP number. Since the HTTP API isn’t very well protected, this is a bad idea. A better way to enable remote access to the HTTP API via public network is to establish a secure tunnel to your mimoLive host computer using ngrok.