Welcome to the HEMS (Home Energy Management System) API documentation. Our platform provides a unified interface to connect, monitor, and control residential energy devices, starting with full support for the Shelly ecosystem.
HEMS allows energy retailers, virtual power plants (VPPs), and smart home providers to integrate distributed energy resources into their applications with minimal effort.
Integrating with HEMS follows a simple four-step process designed for security and scalability.
Start by registering your organization to receive your credentials. Then, use these credentials to authenticate and acquire an access token.
To access data from your customers' devices (e.g., Shelly plugs, relays), you must initiate a linking flow:
- Generate a Linking URL via the
POST /users/{userId}/linkendpoint. - Redirect the user to this URL to authorize the vendor (e.g., Shelly).
- Upon success, devices are automatically registered to your organization.
Once devices are linked, you can use the API to:
- List all devices across your organization.
- Fetch real-time status and energy consumption for specific devices.
The HEMS API is designed for high availability and low latency.
- Base URL:
https://api-hems.obeliskapp.com - Standardized Responses: All endpoints return consistent JSON structures for data and error handling.