Mount Kelvin Cloud API

A brief introduction to the Mount Kelvin 3.0 Cloud API

The Mount Kelvin API uses API keys to authenticate requests. You can view and manage your API keys in the Mount Kelvin Fleet Manager.

Provide your API key as header Authorization: Bearer 7b1mX9SrgQy...MPEPZrf6IY.

Tools

The examples are illustrated using the following command-line tools:


Sites and site groups

Site is a logical unit representing single independant areas like hotel rooms. Site group consists of one or more sites.

Sites are identified by an siteId. siteId for target site can by found from the site group members list.

Getting the site configuration

To get the single site configuration:

curl -s -H 'authorization: Bearer 7b1mX9SrgQy' https://api.mountkelvin.com/v2/sites/<siteId>

The response is the site configuration (a.k.a. site.json).

Controlling individual devices

To list the devices in site.json, do

curl -s -H 'authorization: Bearer 7b1mX9SrgQy' https://api.mountkelvin.com/v2/sites/<siteId> \
  | jq '.devices[] | {id, type, name}

Pick the light device you want to control. Then, write a state for the device, such as

{
  "id": "<deviceId>",
  "state": {
    "on": true,
    "bri": 255
  }
}

and pass it as a request body

curl -s -X POST \
  -H 'authorization: Bearer 7b1mX9SrgQy' \
  -H 'content-type: application/json' \
  -d '{ "id": "<deviceId>", "state": { "on": true, "bri": 255 } }' \
  https://api.mountkelvin.com/v2/sites/<siteId>/applyDevice

Controlling all devices in a room

Find the room id of the room from site.json, then write a state for the devices in the room, such as

{
  "id": "<roomId>",
  "state": {
    "on": true,
    "bri": 255
  }
}

and pass it as a request body

curl -s -X POST \
  -H 'authorization: Bearer 7b1mX9SrgQy' \
  -H 'content-type: application/json' \
  -d '{ "id": "<roomId>", "state": { "on": true, "bri": 255 } }' \
  https://api.mountkelvin.com/v2/sites/<siteId>/applyRoom

Activating scenes

To list the scenes in site.json, do

curl -s -H 'authorization: Bearer 7b1mX9SrgQy' https://api.mountkelvin.com/v2/sites/<siteId> \
  | jq '.scenes[] | {id, name}'

Pick the scene you want to activate, then

curl -s -X POST \
  -H 'authorization: Bearer 7b1mX9SrgQy' \
  -H 'content-type: application/json' \
  -d '{ "id": "<sceneId>" }' \
  https://api.mountkelvin.com/v2/sites/<siteId>/applyScene

There is also two special scenes available allOn and allOff, they can be activated like normal scenes:

curl -s -X POST \
  -H 'authorization: Bearer 7b1mX9SrgQy' \
  -H 'content-type: application/json' \
  -d '{ "id": "allOff" }' \
  https://api.mountkelvin.com/v2/sites/<siteId>/applyScene

Controlling individual curtains

To list all curtains devices in site.json, do

curl -s -H 'authorization: Bearer 7b1mX9SrgQy' https://api.mountkelvin.com/v2/sites/<siteId> \
  | jq '.devices[] | select(.type == "motor") | {id, name}'

Toggleable open and close commands

Following commands will stop the curtain if it is already moving in same direction. If you want to open the curtain regardless of its current running state, use direct open or close commands described later.

Curtain will always stop after configured max run time.

Pick the device you want to control, then to open the curtain

curl -s -X POST \
  -H 'authorization: Bearer 7b1mX9SrgQy' \
  -H 'content-type: application/json' \
  -d '{ "id": "<deviceId>", "state": { "on": true } }' \
  https://api.mountkelvin.com/v2/sites/<siteId>/applyDevice

To close the curtain

curl -s -X POST \
  -H 'authorization: Bearer 7b1mX9SrgQy' \
  -H 'content-type: application/json' \
  -d '{ "id": "<deviceId>", "state": { "on": false } }' \
  https://api.mountkelvin.com/v2/sites/<siteId>/applyDevice

Direct open, close and stop commands

To open the curtain regardless of its current running state

curl -s -X POST \
  -H 'authorization: Bearer 7b1mX9SrgQy' \
  -H 'content-type: application/json' \
  -d '{ "id": "<deviceId>", "command": "open" }' \
  https://api.mountkelvin.com/v2/sites/<siteId>/applyDevice

close and stop commands work similarly. Curtain will always stop after configured max run time, so it is safe to send multiple open or close commands.