Difference between revisions of "Maker API"
(Refined instructions to match other docs and added images) (Tag: Visual edit) |
(Added link to Hubitat® Safety Monitor Interface developer documentation) (Tag: Visual edit) |
||
Line 1: | Line 1: | ||
This API is a simple HTTP GET API that allows you to get the status of your authorized devices and interact with them. | 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''' === | + | ==='''Installing Maker API'''=== |
− | # From the Hubitat Web Interface select '''Apps'''[[File:Install Built-In App 2.0.png|none|thumb|600x600px]] | + | #From the Hubitat Web Interface select '''Apps'''[[File:Install Built-In App 2.0.png|none|thumb|600x600px]] |
− | # Choose Maker API from the list of Hubitat Elevation<sup>®</sup> Built-In Apps.[[File:Install Maker API.png|none|thumb|600x600px]] | + | #Choose Maker API from the list of Hubitat Elevation<sup>®</sup> Built-In Apps.[[File:Install Maker API.png|none|thumb|600x600px]] |
− | # You can enable Logging if you want to see detailed information in the [[logs]]. Remember to open up logs in another tab.[[File:Enable Logging Maker API.png|none|thumb|600x600px]] | + | #You can enable Logging if you want to see detailed information in the [[logs]]. Remember to open up logs in another tab.[[File:Enable Logging Maker API.png|none|thumb|600x600px]] |
− | # Select the devices you want to authorize for this API. '''NOTE''': Only the devices you select will be accessible via the endpoints.[[File:Maker API Select Devices.png|none|thumb|600x600px]] | + | #Select the devices you want to authorize for this API. '''NOTE''': Only the devices you select will be accessible via the endpoints.[[File:Maker API Select Devices.png|none|thumb|600x600px]] |
− | # Select '''Update''' | + | #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] | + | #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] |
− | #* '''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, you will need to remove and re-add the Maker API app.[[File:Maker API endpoints.png|none|thumb|686x686px]] | + | #*'''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, you will need to remove and re-add the Maker API app.[[File:Maker API endpoints.png|none|thumb|686x686px]] |
− | # Press '''Done''' | + | #Press '''Done''' |
− | === To Get a list of all authorized devices === | + | ===To Get a list of all authorized devices=== |
'''/devices''' | '''/devices''' | ||
Line 87: | Line 87: | ||
]</pre>This endpoint contains all the known information about the device, including capabilities, attributes and commands. | ]</pre>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. | + | *'''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]''' | '''/devices/[device id]''' | ||
Line 136: | Line 136: | ||
You should get back a full detail response in JSON for that object. | You should get back a full detail response in JSON for that object. | ||
+ | |||
+ | === Integration with Hubitat<sup>®</sup> Safety Monitor === | ||
+ | [https://docs.hubitat.com/index.php?title=Hubitat%C2%AE_Safety_Monitor_Interface HSM events and their values] |
Revision as of 22:21, 5 August 2020
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 Hubitat Web Interface select Apps
- Choose Maker API from the list of Hubitat Elevation® Built-In Apps.
- You can enable Logging if you want to see detailed information in the logs. Remember to open up logs in another tab.
- Select the devices you want to authorize for this API. NOTE: Only the devices you select will be accessible via the endpoints.
- 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]
- 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, you will need to remove and re-add the Maker API app.
- Press 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 back the same details as /devices/all but only for a specific device.
/devices/[device id]/events
Returns a JSON object of recent events for that [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 [secondary value]
Example: To turn on a light device 1
/devices/1/on
Example 2: To set the level of a light to 50%
/devices/1/setLevel/50
You should get back a full detail response in JSON for that object.