¶ Maker API
Maker API is a simple HTTP API that allows you to retrieve the status of your authorized devices and send commands to them. This API can be useful for integrating Hubitat into other systems or applications that do not offer direct integration.
¶ Installing Maker API
-
From the sidebar of your hub, select Apps and then select Add App (or Add Built-In App).
-
Choose Maker API from the list of Hubitat Elevation built-in apps.
-
You can enable debug logging if you want to see detailed information in Logs, including when Maker API endpoints are called.
-
Select the devices and variables you want to authorize for this instance of Maker API. Only the items 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-accessible 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). Doing so will require reconfiguration (by replacing the old access token with the new one) on the external system/application/etc.
- 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 - Example return value:
{"id":"123","attribute":"switch","value":"off"}
¶ /hubvariables
Returns a list of information about all authorized hub variables
Example
- Endpoint:
/hubvariables - Example return value:
[{"name":"myStringVariable","value":"Example value","type":"string"}]
¶ /hubvariables/[variable name]
Returns information about the specified hub variable.
Example:
- Endpoint:
/hubvariables/myStringVariable - Example return value:
{"name":"myStringVariable","value":"Example value","type":"string"}
¶ /hubvariables/[variable name]/[value]
Sets the value of the specified hub variable. (Variable must be authorized for use in this instance of Maker API. Note that values are case-sensitive, and if your variable name or value contains spaces or special characters, be aware of whether URL encoding is required on your external system.) Returns object similar to the above with current (new) value.
Example:
Returns information about the specified hub variable.
- Endpoint:
/hubvariables/myStringVariable/testing123 - Returns:
{"name":"myStringVariable","value":"testing123","type":"string"}
¶ HTTP POST URL
Instead of polling devices through Maker API to learn of device events, you can 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 set it via an endpoint. To set 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 is specified, 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 also 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, HSM status changes, and hub variable value 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:
/modes
To change, use the endpoint format:
/modes/<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.
¶ Hub Variables
Maker API allows retrieving information (current value and type) about and setting the value of variables selected under Allow endpoint to control these hub variables. Endpoints for hub variables are specified above. If you are using HTTP POST for real-time updates (as opposed to polling) on your external system or application, note that hub variable events are included in location events; thus, you may also want to enable the option for HTTP POST of location events.
¶ 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).