Maker API

From Hubitat Documentation
Revision as of 23:59, 2 July 2022 by RobertM (talk | contribs) (Add ALT text)
Jump to: navigation, search
Go to the top of the page

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

  1. From the sidebar of your hub, select Apps and press the Add Built-In App button.
    Install Built-In App 2.0.png
  2. Choose Maker API from the list of Hubitat Elevation Built-In Apps.
    Screenshot of "Maker API" in Hubitat built-in apps list
  3. You can enable Logging if you want to see detailed information in the logs. Remember to open up logs in another tab.
    Screenshot of "Enable logging for debugging" option in Maker API app
  4. Select the devices you want to authorize for this API.
    • NOTE: Only the devices you select will be accessible via the endpoints.
      Screenshot of "Select Devices" input to authorize devices for Maker API
  5. Select Update
  6. 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.
      Screenshot: Example URLs for Maker API instance
  7. 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.

Integration with Hubitat Safety Monitor

HSM events and their values