mimoLive® - User Manual

Generic selectors
Exact matches only
Search in title
Search in content
Post Type Selectors

Manual – Table of Content

HTTP API

Table of Contents

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 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 an 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 yourself 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 an example for Shell and Apple Script 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 an 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 hard-coding these values is safe 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 the development of custom scripts and applications, mimoLive shows this API key and allows copying to the clipboard in the Remote Controls preference pane:

dddc6bf5 964b 493c b35e ee5b37e44e40

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 an 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 the 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 a public network is to establish a secure tunnel to your mimoLive host computer using ngrok.

Your Feedback

How would you rate your experience with this feature of mimoLive®?

Email Newsletter

English

Join the 24/7 Live Zoom® Demo

*required