Maker API

By ultrasmart.pl

A Comprehensive Guide to Hubitat's Maker API

The Maker API is one of the most versatile built-in apps offered by Hubitat Elevation. It provides a simple, RESTful HTTP interface that allows users to interact with their smart home devices programmatically. By enabling seamless integration with external systems and applications, Maker API empowers users to customize their home automation experience beyond the built-in capabilities of Hubitat.

What is Maker API?

Maker API is a lightweight HTTP GET/POST interface that allows you to:

Monitor Devices: Retrieve the status and attributes of authorized devices in real time.
Control Devices: Send commands to devices (e.g., turn lights on/off, adjust brightness, or lock/unlock doors).
Stream Events: Receive device and location events via HTTP POST to a specified URL.
Integrate External Systems: Connect Hubitat with third-party platforms, apps, or custom dashboards.

Setting Up Maker API

To get started with Maker API, follow these steps:

Install the App:
- From the Hubitat admin interface, go to Apps, click Add Built-In App, and select Maker API.
Authorize Devices:
- Choose the devices you want to expose through the API. Only these devices will be accessible via Maker API endpoints, ensuring security and control.
Enable Logging (Optional):
- Turn on logging to monitor detailed interactions with the API in real time.
Generate Endpoint URLs:
- Once configured, Maker API generates unique endpoint URLs for local (LAN) and cloud access. These URLs include your hub's IP address, app ID, and an access token for authentication.
Example URL format:
text
http://[hub_ip_address]/apps/api/[app_id]/[endpoint_path]?access_token=[access_token]

Key Features and Capabilities

1. Device Control

You can control authorized devices using simple HTTP requests. For example:

Turn on a light: /devices/1/on
Set brightness to 50%: /devices/1/setLevel/50
Lock a door: /devices/2/lock

Each command returns a JSON response detailing the updated device state.

2. Retrieve Device Information

Maker API provides detailed information about each device, including:

Device name, label, type
Attributes (e.g., "switch": "on")
Supported commands (e.g., "on", "off", "refresh")

Example JSON response for a device:


json
{
  "id": "1",
  "name": "Living Room Light",
  "type": "Virtual Switch",
  "attributes": {
    "switch": "off"
  },
  "commands": ["on", "off", "refresh"]
}

3. Event Streaming

Instead of polling for updates, you can configure Maker API to send real-time events via HTTP POST to a specified URL. Event data includes details such as:

Device name and ID
Event type (e.g., switch state change)
Timestamp

Example event payload:


json
{
  "deviceId": "1",
  "name": "switch",
  "value": "on",
  "date": "2025-01-30T15:00:00+0000"
}

4. Hub Mode and HSM Control

Maker API can manage hub modes and Hubitat Safety Monitor (HSM) settings:

View current mode: /mode
Change mode: /mode/<id>
View HSM status: /hsm
Arm/disarm HSM: /hsm/<value> (e.g., /hsm/armAway)

5. Advanced Commands

Maker API supports advanced commands like setting colors using either HSB or hex values:

Set color using HSB: /devices/1/setColor/{"hue":10,"saturation":100,"level":50}
Set color using hex: /devices/1/setColor/{"hex":"FF0400"}

(Note: All JSON data must be URL encoded.)

Security Considerations

Security is critical when using Maker API because the access token included in endpoint URLs acts as an authentication key. To ensure safety:

Only authorize trusted devices.
Reset your access token if it becomes compromised.
Limit access to LAN-only endpoints unless cloud access is explicitly required.

Practical Use Cases

Here are some common ways users leverage Maker API:

Custom Dashboards:
- Build personalized dashboards using platforms like Node-RED or custom web apps to display device statuses and control them remotely.
Third-party Integrations:
- Connect Hubitat with external services like IFTTT, Home Assistant, or even custom IoT projects.
Real-time Notifications:
- Use event streaming to trigger notifications or actions in response to specific events (e.g., motion detected or door unlocked).
Mobile Apps:
- Develop mobile applications that interact directly with your Hubitat hub via Maker API endpoints.

Conclusion

Hubitat's Maker API is an indispensable tool for tech-savvy users who want full control over their smart home ecosystem. Its simplicity and flexibility make it ideal for integrating Hubitat with third-party systems, creating custom automations, or building personalized dashboards. With its robust feature set and real-time capabilities, Maker API bridges the gap between Hubitat's automation platform and external applications, unlocking endless possibilities for home automation enthusiasts.

About the author

ultrasmart.pl