¶ Maker API
This API is a simple HTTP GET API that allows you to get the status of your authorized devices and interact with them.
¶ Installing Maker API
-
From the sidebar of your hub, select Apps and press the Add Built-In App button.
-
Choose Maker API from the list of Hubitat Elevation Built-In Apps.
-
You can enable Logging if you want to see detailed information in Logs. Remember to open up logs in another tab.
-
Select the devices you want to authorize for this instance of Maker API. Only the devices you select will be accessible via the endpoints for this Maker API instance.
-
Select Update
-
Next, you will see URLs to get you started. Each endpoint URL is made up of the following segments:
http://[hub_ip_address]/apps/api/[app_id]/[endpoint_path]?access_token=[access_token]for local endpoints, or similar Internet URLs for cloud endpoints. (A Maker API instance can be configured to allow LAN-only access, cloud-only access, or both.)
NOTE: Your access token is an authorization token, similar to a username and password. Anyone with this token can access these endpoints. To reset your access token, use the Create New Access Token option the app (or create a new Maker API instance and then remove this one).
- Select Done
¶ To Get a list of all authorized devices
¶ /devices
This returns the following JSON:
[
{
"id": "1",
"name": "My First Device",
"label": "Living Room Light"
},
{
"id": "2",
"name": "My Second Device",
"label": "Living Room Switch"
}
]
¶ /devices/all
This returns detailed information about each authorized device in JSON:
[
{
"name": "My First Device",
"label": "Living Room Light",
"type": "Virtual Switch",
"id": "1",
"date": "2018-10-16T00:08:18+0000",
"model": null,
"manufacturer": null,
"capabilities": [
"Switch",
"Refresh"
],
"attributes": {
"switch": "off"
},
"commands": [
{
"command": "off"
},
{
"command": "on"
},
{
"command": "refresh"
}
]
},
{
"name": "My Second Device",
"label": "Living Room Switch",
"type": "Virtual Switch",
"id": "2",
"date": "2018-01-03T02:49:57+0000",
"model": null,
"manufacturer": null,
"capabilities": [
"Switch",
"Refresh"
],
"attributes": {
"switch": "on"
},
"commands": [
{
"command": "off"
},
{
"command": "on"
},
{
"command": "refresh"
}
]
}
]
This endpoint contains all the known information about the device, including capabilities, attributes and commands.
NOTE: There is a limited subset of allowed commands, so just because a command shows up in this list does not mean it will work via the API.
¶ /devices/[device id]
This endpoint returns the same details as /devices/all but only for a specific device.
¶ /devices/[device id]/events
Returns a JSON object of recent events for the specified device ID.
[
{
"device_id": "1",
"label": "Living Room Light",
"name": "My First Device",
"value": "off",
"date": "2018-10-16T00:08:18+0000",
"isStateChange": null,
"source": "DEVICE"
}
]
¶ /devices/[device id]/commands
Returns a JSON object of the commands for that [device id]
[
{
"command": "off"
},
{
"command": "on"
},
{
"command": "refresh"
}
]
¶ /devices/[device id]/[command]/[secondary value]
This is the most powerful endpoint, as it can send a command to the authorized device ID, including an optional parameter or multiple parameters separated by commas.
Example: To turn on a light device ID 1
/devices/1/on
Example 2: To set the level that light to 50%
/devices/1/setLevel/50
Example 3: Sets a lock code for at position 3 with code 4321 and name "Guest":
/devices/1321/setCode/3,4321,Guest
You should get back a full-detail response in JSON for that object.
¶ /devices/[device id]/attribute/[attribte name]
Returns the current value of the specified attribute
Example:
- Endpoint:
/devices/123/switch - Might return:
{"id":"123","attribute":"switch","value":"off"}
¶ HTTP POST URL
Instead of polling devices through Maker API to learn of device events, just enter a URL for events to be sent to via an HTTP POST. The body of the POST will contain a JSON object with the device event details:
data = [name: event.name,
value: event.value,
displayName: event.displayName,
deviceId: event.device.id,
descriptionText: event.descriptionText,
unit: event.unit,
data: event.data]
You can enter the URL to use in the Maker API UI, or you can send it to an endpoint. To do via the endpoint, use:
/postURL/[URL]
Replace [URL] with actual URL to send POST to (URL encoded). To clear the URL, which stops the event stream, omit the /[URL], i.e.:
/postURL
Once this URL exists, either from selecting Done after entering it into the UI or setting it via the endpoint, Maker API will start sending every device event for the selected devices. There is an option to select that Location events also be sent by Maker API along with device events. (Location events include events seen in Logs > Location events, including mode changes and HSM changes.)
¶ Modes
If Allow control of modes is selected, the current hub mode (from Settings > Modes, among other ways of viewing or setting the current mode) can be viewed or changed. To view, use the endpoint:
/mode
To change, use the endpoint format:
/mode/<id>
where <id> is the numeric ID of the mode to set.
¶ Integration with Hubitat Safety Monitor
If Allow control of HSM is selected, the current Hubitat Safety Monitor (HSM) status can be viewed or changed. To view, use the endpoint:
/hsm
To change, use the endpoint format:
/hsm/<value>
where <value> is the HSM status to set, for example, /hsm/armAway.
For possible values for each, see: HSM events and their values, specifically the hsmStatus and hsmSetArm sections.
¶ Command Extensions
Maker API has "extended" the standard setColor() command with additions that might make it easier to use in certain cases. The standard use, per capability specification, involves sending HSB data (on the Hubitat side, this is a Groovy map, but Maker API endpoints convert equivalent data to/from JSON as needed):
http://[hub_ip]/apps/api/[app_id]/devices/[device_id]/setColor/{"hue":1,"saturation":100,"level":50}?access_token=[access_token]
NOTE: The
{"hue":1,"saturation":100,"level":50}data must be URL encoded (as must all data you provide — though other portions of the URL you must supply are unlikely to contain affected characters). The service, tool, browser, etc. that you are using on the other end of Maker API may do this for you; if not, you will need to URL-encode parameters that include any reserved characters as part of the URL. For example, instead of{"hue":1,"saturation":100,"level":50}, you would need to write%7B%22hue%22%3A1%2C%22saturation%22%3A100%2C%22level%22%3A50%7D.
Maker API allows you to use a map with a single key, hex, and an RGB color specified in the popular hexadecimal format. Maker API will convert this RGB color to the required HSB format behind the scenes before sending it to the device. So, the above portion:
{"hue":1,"saturation":100,"level":50}
could be re-written as:
{"hex:"FF0400"}
(again, note the URL encoding is required, and you may need to write %7B%22hex%22%3A%22FF0400%22%7D instead).