Minut API

Base URL: /v1, Version: v1, Get started with the Minut API

A reference to Minut's HTTP API.

For an introductory guide to the API, see https://minut.com/developers.

Default request content-types: application/json
Default response content-types: application/json
Schemes: https

Summary

Tag: Devices

Operation Description
GET /devices

Get devices

GET /devices/{device_id}

Get a device

PUT /devices/{device_id}

Update a device

GET /devices/{device_id}/temperature

Get temperature readings

GET /devices/{device_id}/humidity

Get humidity readings

GET /devices/{device_id}/pressure

Get barometric pressure readings

GET /devices/{device_id}/sound_level

Get sound level readings

GET /devices/{device_id}/battery

Get battery voltage readings

GET /devices/{device_id}/motion_events

Get motion events for a time period

Tag: Events

Operation Description
GET /events

Get events

Tag: Homes

Operation Description
GET /homes

Get homes

GET /homes/{home_id}

Get a home

PUT /homes/{home_id}

Update a home

PUT /homes/{home_id}/alarm

Update detailed alarm status

Tag: OAuth

Operation Description
GET /oauth/authorize

Request an authorization code

POST /oauth/token

Token exchange

POST /oauth/revoke

Revoke a refresh token

Tag: Users

Operation Description
GET /users

Get users

PUT /users

Update a user

Tag: Webhooks

Operation Description
POST /webhooks

Create a webhook

GET /webhooks

Get all webhooks

DELETE /webhooks/{hook_id}

Delete a webhook

POST /webhooks/{hook_id}/ping

Trigger a sample event

Tag: Invitations

Operation Description
GET /homes/{home_id}/invitations

Get invitations

POST /homes/{home_id}/invitations

Create invitations

PUT /homes/{home_id}/invitations/{code}

Accept invitations

DELETE /homes/{home_id}/invitations/{code}

Delete invitations

PUT /invitations

Accept invitations

Security

OAuth

Type: oauth2
Flow:

accessCode

AuthorizationUrl:

https://api.minut.com/v1/oauth/authorize

TokenUrl:

https://api.minut.com/v1/oauth/token

Scopes:
all: access all endpoints accessible to the user

Description:

Access Code

Paths

Get devices

GET /devices

Tags: Devices

Returns a list of all devices the authenticated user has access to.

Uses default content-types: application/json

200 OK

A list of devices

devices: object[]
Get a device

GET /devices/{device_id}

Tags: Devices

Returns a device

device_id

Device ID

path string #/parameters/device_id

Uses default content-types: application/json

200 OK

A Device

401 Unauthorized

User is not authorized access

404 Not Found

The Device does not exist

Update a device

PUT /devices/{device_id}

Tags: Devices

Update one or multiple fields of a device.

This endpoint also allows you to change the settings for a device.

Allowed notifications are:

Type Description
push A push notification is sent to the user's phone
light Point pulsates in bright yellow
beep Point plays a ringing bell sound

Uses default content-types: application/json

Configuration values to change on a device

device_id

Device ID

path string #/parameters/device_id

Uses default content-types: application/json

200 OK

An updated device

400 Bad Request

Bad input

error: string
status: integer (int32)
context: string[]
string
401 Unauthorized

User is not authorized access

404 Not Found

The Device does not exist

Get battery voltage readings

GET /devices/{device_id}/battery

Tags: Devices
device_id

Device ID

path string #/parameters/device_id
start_at

The date-time to start fetching data from

query string #/parameters/start_at
end_at

The date-time to stop fetching data from

query string #/parameters/end_at
raw

Returns raw data as received from the device

query boolean #/parameters/raw

Uses default content-types: application/json

200 OK

Battery readings

401 Unauthorized

User is not authorized access

404 Not Found

The Device does not exist

Get humidity readings

GET /devices/{device_id}/humidity

Tags: Devices
device_id

Device ID

path string #/parameters/device_id
start_at

The date-time to start fetching data from

query string #/parameters/start_at
end_at

The date-time to stop fetching data from

query string #/parameters/end_at
raw

Returns raw data as received from the device

query boolean #/parameters/raw

Uses default content-types: application/json

200 OK

Humidity readings

401 Unauthorized

User is not authorized access

404 Not Found

The Device does not exist

Get motion events for a time period

GET /devices/{device_id}/motion_events

Tags: Devices

Get a a list of motion event counts for a specific time period aggregated over a time interval in seconds that is defined by the parameter time_resolution.

device_id

Device ID

path string #/parameters/device_id
start_at

The date-time to start fetching data from

query string #/parameters/start_at
end_at

The date-time to stop fetching data from

query string #/parameters/end_at
time_resolution

The time window in seconds to aggregate events

query number #/parameters/time_resolution

Uses default content-types: application/json

200 OK

Aggregated motion event counts

401 Unauthorized

User is not authorized access

404 Not Found

The Device does not exist

Get barometric pressure readings

GET /devices/{device_id}/pressure

Tags: Devices
device_id

Device ID

path string #/parameters/device_id
start_at

The date-time to start fetching data from

query string #/parameters/start_at
end_at

The date-time to stop fetching data from

query string #/parameters/end_at
raw

Returns raw data as received from the device

query boolean #/parameters/raw

Uses default content-types: application/json

200 OK

Pressure readings

401 Unauthorized

User is not authorized access

404 Not Found

The Device does not exist

Get sound level readings

GET /devices/{device_id}/sound_level

Tags: Devices
device_id

Device ID

path string #/parameters/device_id
start_at

The date-time to start fetching data from

query string #/parameters/start_at
end_at

The date-time to stop fetching data from

query string #/parameters/end_at
raw

Returns raw data as received from the device

query boolean #/parameters/raw

Uses default content-types: application/json

200 OK

Average sound level

401 Unauthorized

User is not authorized access

404 Not Found

The Device does not exist

Get temperature readings

GET /devices/{device_id}/temperature

Tags: Devices
device_id

Device ID

path string #/parameters/device_id
start_at

The date-time to start fetching data from

query string #/parameters/start_at
end_at

The date-time to stop fetching data from

query string #/parameters/end_at
raw

Returns raw data as received from the device

query boolean #/parameters/raw

Uses default content-types: application/json

200 OK

Temperature readings

401 Unauthorized

User is not authorized access

404 Not Found

The Device does not exist

Get events

GET /events

Tags: Events

Get a sorted list of events belonging to the authenticated user.

Type Description
alarm_heard An alarm sound was recognised
glassbreak The sound of glass break was detected
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
avg_sound_high Average sound levels are higher than the configured threshold
sound_level_high_quiet_hours Sound levels high during quiet hours
sound_level_high_despite_warning Sound levels continue to be high despite warnings
sound_level_dropped_normal Sound levels are back down 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 are soon empty, approximately 2 weeks left
battery_empty The batteries are empty
start_at

The date-time to start fetching data from

query string #/parameters/start_at
end_at

The date-time to stop fetching data from

query string #/parameters/end_at
limit

Limit how many results to fetch. Default is 500

query number #/parameters/limit
offset

Starting offset when fetching results. Default is 0

query number #/parameters/offset
order

Defines the time sorting order. Default is 'asc'

query string , x ∈ { asc , desc } #/parameters/order

Uses default content-types: application/json

200 OK

A list of events

Get homes

GET /homes

Tags: Homes

Returns a list of all homes the user has access to

Uses default content-types: application/json

200 OK

A list of homes

devices: object[]
Get a home

GET /homes/{home_id}

Tags: Homes

Returns a home

home_id

Home ID

path string #/parameters/home_id

Uses default content-types: application/json

200 OK

A Home

401 Unauthorized

User is not authorized access

404 Not Found

The home does not exist

Update a home

PUT /homes/{home_id}

Tags: Homes

Update one or multiple fields of a home.

Uses default content-types: application/json

Configuration values to change on a home

home_id

Home ID

path string #/parameters/home_id

Uses default content-types: application/json

200 OK

An updated home

400 Bad Request

Bad input

error: string
status: integer (int32)
context: string[]
string
401 Unauthorized

User is not authorized access

404 Not Found

The home does not exist

Update detailed alarm status

PUT /homes/{home_id}/alarm

Tags: Homes

Update the detailed alarm status of a home

Uses default content-types: application/json

Configuration values to change for the alarm status on a home

home_id path string

Uses default content-types: application/json

200 OK

An updated home

400 Bad Request

Bad input

401 Unauthorized

User is not authorized access

404 Not Found

The home does not exist

Get invitations

GET /homes/{home_id}/invitations

Tags: Invitations

Returns invitations

home_id

Home ID

path string #/parameters/home_id

Uses default content-types: application/json

200 OK

List of invitations to the home

home_id: string
invitations: object[]
Create invitations

POST /homes/{home_id}/invitations

Tags: Invitations

Uses default content-types: application/json

group: string , x ∈ { friends , family }
email: string
name: string
phone_number: string
home_id

Home ID

path string #/parameters/home_id

Uses default content-types: application/json

201 Created

Invitation created

Delete invitations

DELETE /homes/{home_id}/invitations/{code}

Tags: Invitations
home_id

Home ID

path string #/parameters/home_id
code path string

Uses default content-types: application/json

200 OK

Invitation deleted

Accept invitations

PUT /homes/{home_id}/invitations/{code}

Tags: Invitations

Uses default content-types: application/json

accept: boolean
home_id

Home ID

path string #/parameters/home_id
code path string

Uses default content-types: application/json

200 OK

Invitation accepted

Accept invitations

PUT /invitations

Tags: Invitations

Accept an invitation using an invitation code

Uses default content-types: application/json

invitation_code: string

Uses default content-types: application/json

200 OK

Invitation confirmation

home_id: string
home_name: string
group: string
400 Bad Request

Invalid invitation code

Request an authorization code

GET /oauth/authorize

Tags: OAuth
response_type

Must be set to "code"

query string
client_id

The client id

query string
redirect_uri

Where to redirect the user-agent after performing the request. Must match the redirect_uri specified when the client was created.

query string
scope

Space separated list of scopes to request.

query string
state

An opaque value used by the client to maintain state between the request and the callback.

query string

Uses default content-types: application/json

200 OK

An authorization code

code: string
400 Bad Request

Bad request

401 Unauthorized

Unauthorized

Revoke a refresh token

POST /oauth/revoke

Tags: OAuth

Uses default content-types: application/json

Refresh token to revoke

Uses default content-types: application/json

200 OK

Status of revokation

revoked: boolean
Token exchange

POST /oauth/token

Tags: OAuth

There are three ways to get a bearer token which are requried for all other endpoints.

  1. Exchange an authorization_code
  2. Exchange username and password
  3. Exchange a refresh_token

All exchange methods will return a short-lived bearer token and a refresh token.

Uses default content-types: application/json

Set the TokenExchange parameters required for the grant_type used.

Uses default content-types: application/json

200 OK

A bearer and refresh token token

access_token: string
refresh_token: string
expires_in: integer

Token expiry time in seconds

token_type: string

The API only issues Bearer tokens.

user_id: string

The ID of the user who owns the token.

400 Bad Request

Bad request

401 Unauthorized

Unauthorized

Get users

GET /users

Tags: Users
user_id query string

Uses default content-types: application/json

200 OK

Return a user

Update a user

PUT /users

Tags: Users

Uses default content-types: application/json

user_id query string

Uses default content-types: application/json

200 OK

User updated

Get all webhooks

GET /webhooks

Tags: Webhooks

Uses default content-types: application/json

200 OK

A list of webhooks

hooks: object[]
401 Unauthorized

Unauthorized

Create a webhook

POST /webhooks

Tags: Webhooks

Uses default content-types: application/json

Information about where to POST events

Uses default content-types: application/json

201 Created

A webhook

400 Bad Request

Bad request

401 Unauthorized

Unauthorized

Delete a webhook

DELETE /webhooks/{hook_id}

Tags: Webhooks
hook_id

Webhook ID

path string #/parameters/hook_id

Uses default content-types: application/json

200 OK

Returns an empty object on success {}

400 Bad Request

Bad request

401 Unauthorized

Unauthorized

404 Not Found

Not Found

Trigger a sample event

POST /webhooks/{hook_id}/ping

Tags: Webhooks
hook_id

Webhook ID

path string #/parameters/hook_id

Uses default content-types: application/json

201 Created

Returns an empty object on success {}

400 Bad Request

Bad request

404 Not Found

Not Found

Parameter definitions

device_id device_id

Device ID

path string
home_id home_id

Home ID

path string
event_id event_id

Event ID

path string
start_at start_at

The date-time to start fetching data from

query string
end_at end_at

The date-time to stop fetching data from

query string
time_resolution time_resolution

The time window in seconds to aggregate events

query number
raw raw

Returns raw data as received from the device

query boolean
hook_id hook_id

Webhook ID

path string
limit limit

Limit how many results to fetch. Default is 500

query number
offset offset

Starting offset when fetching results. Default is 0

query number
order order

Defines the time sorting order. Default is 'asc'

query string , x ∈ { asc , desc }

Schema definitions

AlarmDetailedStatus: object

alarm_status: string , x ∈ { on , off , on_grace_period , off_grace_period }
"on_grace_period"
                                                        

ClientApplication: object

owner: string
name: string
description: string
url: string
client_id: string
client_secret: string
created_at: string (date-time)

Device: object

device_id: string
device_mac: string
device_bluetooth_address: string
owner: string
home: string
active: boolean

false if the device has been moved to a different account

offline: boolean

true if the backend hasn't heard from the device in 3 hours

first_seen_at: string (date-time)
last_heard_from_at: string (date-time)
last_heartbeat_at: string (date-time)
firmware: object
installed: integer (int32)
wanted: integer (int32)
hardware_version: integer (int32)
description: string
timezone: string

The Olson ID describing the timezone, e.g., Europe/Stockholm

configuration: object
version: integer (int32)
installed_on_device_at: string (date-time)
updated_at: string (date-time)
room_type: string
glassbreak_config: object
active_until: string
active_from: string
quiet_hours: object
enabled: boolean
start: string
end: string
reactions: object[]
ongoing_events: string[]
string
battery: object
voltage: number (float)
low_warning_sent_at: string (date-time)
percent: number (float)
location: object
longitude: number
latitude: number

DeviceConfig: object

description: string
home: string
timezone: string

The Olson ID for a timezone, e.g., Europe/Stockholm

glassbreak_config: object
active_from: string
"2017-04-18T12:17:37.172Z"
                                                                                    
active_until: string
"2017-04-19T12:17:37.172Z"
                                                                                    
quiet_hours: object
enabled: boolean
start: string
end: string
room_type: string
location: object
type: string , x ∈ { Point }
coordinates: number[] (2 to 2 chars)

Must contain [longitude, latitude]

number
reactions: object[]

Event: object

event_id: string
type: string
created_at: string (date-time)
user_id: string
device_id: string
home_id: string
sensor_value: number
sensor_threshold: number
start_created_at: string (date-time)
feedback_question_id: string
text_params: object[]
object
key: string
value: string
actions: object[]
object
url: string
graph: object
start_at: string (date-time)
end_at: string (date-time)
unit: string , x ∈ { c , % , hPa , }
sensor_type: number

Home: object

home_id: string
name: string
created_at: string (date-time)
created_by: string
timezone: string
location: object
longitude: number
latitude: number
alarm_status: string , x ∈ { on , off , off_grace_period }
detailed_alarm_status: string , x ∈ { on , off , off_grace_period , on_grace_period }
alarm_off_grace_period_secs: number
grace_period_expires_at: string (date-time)
devices: object[]
object
device_id: string
members: object[]
object
user_id: string
joined_at: string (date-time)
fullname: string
email: string
status: string , x ∈ { away , home }

HomeConfig: object

name: string
timezone: string
location: object
longitude: number
latitude: number

Invitation: object

invitation_id: string
invitation_code: string
email: string
phone_number: string
group: string , x ∈ { family , friends }
accepted: boolean
created_at: string (date-time)
invited_by: object
name: string
user_id: string

Reaction: object

type: string
notifications: string[]
string
value: number

TimeSeries: object

unit: string , x ∈ { c , % , hPa , }
values: object[]
object
value: number
datetime: string (date-time)

TokenExchange: object

grant_type: string , x ∈ { refresh_token , authorization_code , password }

Grant type to exchange for access token

redirect_uri: string

Required if redirect_uri was provided in the authorize request and must be identical in that case.

client_id: string

Client ID if not provided using HTTP Basic Auth

client_secret: string

Client secret if not provided using HTTP Basic Auth

code: string

Authorization code is grant_type is authorization_code

username: string

Username if grant_type is password.

password: string

Password if grant_type is password.

refresh_token: string

Refresh token if grant_type is refresh_token.

token: string

Token if grant_type implies converting from a trusted third-party token.

TokenRevoke: object

token: string

The refresh token to revoke

client_id: string
client_secret: string

User: object

user_id: string
fullname: string
nick: string
email: string
subscribe_newsletter: boolean
created_at: string (date-time)
updated_at: string (date-time)
roles: string[]
string
share_location: boolean

Webhook: object

hook_id: string
hook_secret: string

Only returned when the webhook is created. Can be used by the receiver to identify Minut and a particular webhook when a POST request is issued.

url: string

The URL to POST events to.

token: string

Will be attached to the Authorization header of the outgoing POST request

events: string[]
string

Use '*' to subscribe to all events.