mimoLive User Manual

The mimoLive User Manual Developer Hub

Welcome to the mimoLive User Manual developer hub. You'll find comprehensive guides and documentation to help you start working with mimoLive User Manual as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

HTTP API

You can control mimoLive through a built-in webserver with http requests.

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 or something similar that can talk to a HTTP server) that control various aspects of mimoLive - the possibilities are nearly endless.

In this document 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.

Demo Scripts

In addition to the documentation you can also have a look at our demo scripts on github.

API Endpoint

The mimoLive API is accessible on the same machine mimoLive is running on (via localhost) and on the local network (via <MacHostname>.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: <APIKey>
  • Appending the query parameter ?pwSHA256=<APIKey>

In both cases, <APIKey> 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: <Password> or the query parameter ?pw=<Password> 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"
    }
  ]
}

What's Next

To discover what's inside the HTTP API, check out the endpoint documentation and data types.

Endpoints
Data Types