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.

Installing Maker API

1. From the sidebar of your hub, select Apps and press the Add Built-In App button.
   
2. Choose Maker API from the list of Hubitat Elevation Built-In Apps.
   
3. You can enable Logging if you want to see detailed information in the logs. Remember to open up logs in another tab.
   
4. Select the devices you want to authorize for this API.
   • NOTE: Only the devices you select will be accessible via the endpoints.
     
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.
     
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 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.

HTTP POST URL

Instead of polling devices through Maker API to learn of device events, just 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 send it to an endpoint. To do via the endpoint, use:

/postURL/[URL]

Replace [URL] with actual URL to send POST to (URL encoded). Once this URL exists, either from selecting Done after entering it into the UI, or once the URL is sent to the endpoint, Maker API will start sending every device event for the selected devices. There is an option to select that Location events also be sent by Maker API along with device events.

To clear the URL, which stops the event stream, omit the /[URL], i.e.:

/postURL

Integration with Hubitat Safety Monitor

See: HSM events and their values