Hubitat™ Maker API

From Hubitat Documentation
Revision as of 23:14, 17 October 2018 by Patrick (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Hubitat 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.

Installation:

Go to Apps, click Load New App

Select Hubitat Maker API

Click Done.

The App is now installed and you are back at the list of installed apps.

Click on Hubitat Maker API in the list of 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. Only the devices you select will be accessible via the endpoints.

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 Hubitat Maker API

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

Another Example, 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.