Skip to content
Last updated

Introduction to HEMS API

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.

The Integration Flow

Integrating with HEMS follows a simple four-step process designed for security and scalability.

1. Register & Authenticate

Start by registering your organization to receive your credentials. Then, use these credentials to authenticate and acquire an access token.

To connect your customers' devices (e.g., Shelly meters) to HEMS, initiate a linking flow:

  1. Call the POST /users/{userId}/link endpoint to generate a Connection URL.
  2. Share the connectionUrl with your user and instruct them to enter it in their device's settings.
  3. Once configured, the device connects directly to HEMS and is registered to your organization.

3. Manage & Monitor

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.

Global Infrastructure

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.
 
Next page