Developers

Introduction

Welcome to the Minut developer documentation. Here you will find an introduction to the Minut API, how to setup your first application, and how to subscribe to events from Point.

The requirements to start using the API are few. You need a Minut user account and an API client application. This guide will help you set up both. If you already have a Minut account you may jump directly to creating the client application.

Here you will also find code snippets to get you started and the API reference.

Getting Started

Setup a Minut account

  1. Download the iOS or Android app on your phone.
  2. Create a user account with your email address and password.
  3. Done 🙂

Setup an API client application

For now you have to email marcus@minut.com and request an API client manually. We are going to make this smoother in the future.

Good to know

  • All of Minut’s endpoints are served over HTTPS. Anything else would be a mistake.
  • All references to dates and times are in UTC.
  • We try our best to return meaningful HTTP status codes and error messages.
  • The API only consumes and produces application/json.

Authentication

Minut uses OAuth2 to allow third-party applications to make requests against the API on users behalf. DigitalOcean wrote a great introduction to OAuth that might be worth starting with if you are new to it. Either way, we will walk you through the steps you need to get started.

OAuth2 consists of two steps: first, requesting an authorization code for a specific user, and second, exchanging that authorisation code for a bearer token and refresh token. The first step requires the authenticating user sign-in, if not already, through a web page and authorize your application to access Minut data on his/her behalf. The grant given by the user allows your application to make API requests with a short-lived bearer token to access user data. When the bearer token expires the app can automatically renew it using a refresh token.

To retrieve an authorization code we must first have something that is able to capture it. A simple way to get started is by serving a local python web server.

python -m SimpleHTTPServer .

This will start a web server on port 8000 on your localhost. Having previously configured your client application to redirect to http://localhost:8000 when a user authorizes your app we can now capture the authorization code that we need in the second step.

Send the user to a web browser to authorize your app:

https://api.minut.com/v1/oauth/authorize?client_id=55e77060be6dcf4b&response_type=code&redirect_uri=http://localhost:8000

In the example above the user is logged in as Marcus and is about to authorize Marcus API Test client application to make API requests on the user’s behalf.

api_auth_code

On clicking accept, the user is automatically redirected to our local webserver running on http://localhost:8000 with the authorization code appropriately generated. Needless to say, in a real scenario you probably won’t redirect the user to localhost but to a web service you host.

Now we have everything we need for the second step: exchanging the authorization code for a bearer token. On Mac OS X/Linux you may use curl from the command line to issue this request.

curl -X POST -H "Content-Type: application/json" \
-H "Cache-Control: no-cache" \
-d '{
 "redirect_uri": "http://localhost:8000",
 "client_id": "55e77060be6dcf4b",
 "client_secret": "dd3c962b7e8853f630145c5093d85d75",
 "code": "idWRGknMZH0uKueG",
 "grant_type": "authorization_code"
}' "https://api.minut.com/v1/oauth/token"

The response is as follows:

{
 "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VySWQiOiI1NWE1MDQxYjkwODUyNGZkMGZmZTJiOGMiLCJyb2xlcyI6WyJkZW1vLXVzZXIiXSwib3JnSWQiOiJtaW51dCIsInNjb3BlIjoiIiwiaWF0IjoxNDkwNjM2OTQyLCJleHAiOjE0OTA2NDA1NDIsImlzcyI6Ik1pbnV0LCBJbmMuIn0.KTZPwfOwYTJlZRxNctJDHSN2QeHG7JE2wLYlOsXymmQ",
 "refresh_token": "5QwnZ2qq47gLj6A0E86Ejgmy7EAkd3YI",
 "expires_in": "3600",
 "user_id": "55a5041b908524fd0ffe2b8c",
 "token_type": "Bearer"
}

Let’s break that down.

  1. The `access_token` is the token that you will include in all consecutive API requests on the user’s behalf. This token will be included in the `Authorization` header.
  2. The `refresh_token` can be used to get a new `access_token` once it has expired.
  3. The `access_token` `expires_in` 3600 seconds, or 1 hour.
  4. The `user_id` is the ID of the user which this token belongs to.
  5. The `token_type` will always be “Bearer” since Minut doesn’t support any other token types as of now.

Finally, let’s see how to refresh the access token once it has expired.

curl -X POST -H "Content-Type: application/json" \
-H "Cache-Control: no-cache" \
-d '{
 "client_id": "55e77060be6dcf4b",
 "client_secret": "dd3c962b7e8853f630145c5093d85d75",
 "refresh_token": "5QwnZ2qq47gLj6A0E86Ejgmy7EAkd3YI",
 "grant_type": "refresh_token"
}' "https://api.minut.com/v1/oauth/token"

The response is similar to the first exchange we did. You’ll get a new access token every time you refresh.

Armed with access tokens you are now ready to make requests against the API. 😎

Architecture

Before we dive into the API Reference it is useful to get a brief understanding about how Point works, what it communicates, and how it does so.

Point runs on batteries and as such a lot of care is taken to make the batteries last as long as possible. This means that for the most time, communication channels like Wi-Fi, is turned off. It is only activated when necessary and that happens for two reasons. The first reason is regular checkins, called Heartbeats. The heartbeat is a message that Point sends roughly once an hour to indicate to the backend that it is still alive and well. This message contains all the sensor readings since the last heartbeat, usually some diagnostics, and a check for new configuration or software updates. The other reason is when something out of the ordinary happens, for example, when the Point detects a sudden temperature drop, an alarm, or other activity. These messages are called Events.

Sensor data

While heartbeats are sent regularly Minut does not expose them directly the API. Instead, and much more useful, is the sensor data they contain. The API provides endpoints to retrieve temperature, humidity, pressure, ambient light, sound, and battery data as continuous time series.

Events

Point is mostly about events. Events are sent when something out of the ordinary is detected, when a long-running analysis on the backend has yielded some result, or if the user performs certain actions.

There exists a broad range of events that describe user actions, activity in the home, and system information. The most common events are listed in the table below:

Type Description
alarm_heard An alarm sound was recognised
short_button_press The button on Point was pressed
temperature_high Temperature is higher than the configured threshold
temperature_low Temperature is lower than the configured threshold
temperature_dropped_normal Temperature is back down to normal
temperature_risen_normal Temperature is back up to normal
humidity_high Humidity is higher than the configured threshold
humidity_low Humidity is lower than the configured threshold
humidity_dropped_normal Humidity is back down to normal
humidity_risen_normal Humidity is back up to normal
device_offline Device went offline
device_online Device went online
tamper Point was removed from or put back on its mounting plate
battery_low The batteries need to be replaced
activity_detected Point has detected activity

 

Events can be retrieved both from the API and subscribed to via Webhooks. We will explain how to subscribe to events in the next section.

Depending on the type of the event, the fields in the event varies. For instance, an event generated by a sensor value crossing a threshold will contain a reference to the threshold crossed. Whereas a tamper event will only contain a reference to which device was tampered with. Events at least contain the following fields:

{
 “event_id”: “string”,
 “created_at”: “datetime”,
 “type”: “string”
}

Most of the time they will also include either “device_id” or “user_id”.

Webhooks

Webhooks are a great way to react to events as they happen. Rather than implementing a mechanism where you would poll the Minut API at regular intervals, you tell the API about an endpoint that you control to which Minut can send events as they happen.

Requirements:

  • An API client application
  • A web service that you control

For sake of simplifying this example we are going to use a temporary requestb.in. It’s an online service that lists HTTP requests directed to it. Since they are only temporary they are not recommended for continued use.

Create a request bin at http://requestb.in. Make a note of the URL.

Now we need to set up the subscription. This is done with a POST request to `/webhooks` as an authenticated user.

curl -X POST -H "Authorization: Bearer $token" \
-H "Content-Type: application/json" \
-d '{
 "url": "http://requestb.in/vkw8bavk",
 "events": ["short_button_press"]
}' "https://api.minut.com/draft1/webhooks/"

In return you will get a Webhook. If you wanted to subscribe to all events (note: there may be a lot), then you can use the ‘*’ wildcard in the `events` list.

There’s a simple way to test that your subscription works without having to wait for Point to generate an event.

curl -X POST -H "Authorization: Bearer $token" \ 
-H "Content-Type: application/json" \
-d '{}' "https://api.minut.com/draft1/webhooks/WEBHOOK_ID/ping"

From now on all events that belongs to the user are forwarded to your web service. Minut will automatically retry sending the event roughly 10 times with an exponential back-off. In case all attempts fail, we will not try sending the message again and you have to implement some form of recovery of lost messages yourselves by asking the `/events` endpoint.

API Reference

The Minut API is specified using the OpenAPI specification. The full API reference can be found here.

API Status

Minut uses Uptimerobot to measure API availability. You can check the most recent status here: https://status.minut.com

Support

Community support for the Minut API is available at https://discuss.minut.com.

Partner with Minut

We partner with insurances, telcos, and utilities around the world to provide new types of services for end users.

For integrations we provide enterprise APIs tailored to managing thousands of devices, SLAs and support. Feel free to reach out to Nils for more information at nils@minut.com.

Table of Contents
  • Introduction
  • Developer Guide
    • Getting Started
    • Good to Know
    • Authentication
    • Architecture
    • Webhooks
  • API Reference
  • API Status
  • Support
  • Partner with Minut