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

- [View Registration Process](/pages/registration)
- [View Authentication Guide](/pages/authentication)


### 2. Link User Devices

To access data from your customers' devices (e.g., Shelly plugs, relays), you must initiate a linking flow:

1. Generate a **Linking URL** via the `POST /users/{userId}/link` endpoint.
2. Redirect the user to this URL to authorize the vendor (e.g., Shelly).
3. Upon success, devices are automatically 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.