Difference between revisions of "Maker API"
(Added link to Hubitat® Safety Monitor Interface developer documentation) (Tag: Visual edit) |
(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. | + | {{Top}} |
+ | |||
+ | <big>This API is a simple HTTP GET API that allows you to get the status of your authorized devices and interact with them.</big> | ||
==='''Installing Maker API'''=== | ==='''Installing Maker API'''=== | ||
− | #From the | + | #<big>From the sidebar of your hub, select '''Apps''' and press the '''Add Built-In App''' button.</big>[[File:Install Built-In App 2.0.png|none|thumb|600x600px]] |
− | #Choose Maker API from the list of Hubitat Elevation | + | #<big>Choose '''Maker API''' from the list of Hubitat Elevation Built-In Apps.</big>[[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]] | + | #<big>You can enable Logging if you want to see detailed information in the [[logs]]. Remember to open up logs in another tab.</big>[[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]] | + | #<big>Select the devices you want to authorize for this API.</big> |
− | #Select '''Update''' | + | #*<big>'''NOTE''': Only the devices you select will be accessible via the endpoints.</big>[[File:Maker API Select Devices.png|none|thumb|600x600px]] |
− | #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] | + | #<big>Select '''Update'''</big> |
− | #*'''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]] | + | #<big>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]</big> |
− | #Press '''Done''' | + | #*<big>'''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.</big>[[File:Maker API endpoints.png|none|thumb|686x686px]] |
+ | #<big>Press '''Done'''</big> | ||
− | ===To Get a list of all authorized devices=== | + | ===<big>To Get a list of all authorized devices</big>=== |
− | '''/devices''' | + | '''<big>/devices</big>''' |
− | This returns the following JSON:<pre>[ | + | <big>This returns the following JSON:</big><pre>[ |
{ | { | ||
"id": "1", | "id": "1", | ||
Line 28: | Line 31: | ||
]</pre> | ]</pre> | ||
− | '''/devices/all''' | + | '''<big>/devices/all</big>''' |
− | This returns detailed information about each authorized device in JSON:<pre>[ | + | <big>This returns detailed information about each authorized device in JSON:</big><pre>[ |
{ | { | ||
"name": "My First Device", | "name": "My First Device", | ||
Line 85: | Line 88: | ||
] | ] | ||
} | } | ||
− | ]</pre>This endpoint contains all the known information about the device, including capabilities, attributes and commands. | + | ]</pre><big>This endpoint contains all the known information about the device, including capabilities, attributes and commands.</big> |
− | *'''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. | + | *<big>'''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.</big> |
− | '''/devices/[device id]''' | + | '''<big>/devices/[device id]</big>''' |
− | This endpoint returns back the same details as /devices/all but only for a specific device. | + | <big>This endpoint returns back the same details as /devices/all but only for a specific device.</big> |
− | '''/devices/[device id]/events''' | + | '''<big>/devices/[device id]/events</big>''' |
− | Returns a JSON object of recent events for that [device id]<pre>[ | + | <big>Returns a JSON object of recent events for that [device id]</big><pre>[ |
{ | { | ||
"device_id": "1", | "device_id": "1", | ||
Line 107: | Line 110: | ||
]</pre> | ]</pre> | ||
− | '''/devices/[device id]/commands''' | + | '''<big>/devices/[device id]/commands</big>''' |
− | Returns a JSON object of the commands for that [device id]<pre> | + | <big>Returns a JSON object of the commands for that [device id]</big><pre> |
[ | [ | ||
{ | { | ||
Line 123: | Line 126: | ||
</pre> | </pre> | ||
− | '''/devices/[device id]/[command]/[secondary value]''' | + | '''<big>/devices/[device id]/[command]/[secondary value]</big>''' |
− | This is the most powerful endpoint, as it can send a command to the authorized [device id] including an optional [secondary value] | + | <big>This is the most powerful endpoint, as it can send a command to the authorized [device id] including an optional [secondary value]</big> |
− | ''Example'': To turn on a light '''device 1''' | + | <big>''Example'': To turn on a light '''device 1'''</big> |
− | '''/devices/1/on''' | + | '''<big>/devices/1/on</big>''' |
− | ''Example 2'': To set the level of a light to 50% | + | <big>''Example 2'': To set the level of a light to 50%</big> |
− | '''/devices/1/setLevel/50''' | + | '''<big>/devices/1/setLevel/50</big>''' |
− | You should get back a full detail response in JSON for that object. | + | <big>You should get back a full detail response in JSON for that object.</big> |
− | === Integration with Hubitat | + | ===<big>Integration with Hubitat Safety Monitor</big>=== |
− | [ | + | [[Hubitat® Safety Monitor Interface|<big>HSM events and their values</big>]] |
Revision as of 06:13, 22 March 2021
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 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.