# HEMS APIs

APIs for Home Energy Management System

Version: 2.0.0

## Servers

```
https://api-hems.obeliskapp.com
```

## Security

### bearerAuth

Type: http
Scheme: bearer
Bearer Format: JWT

### basicAuth

Use your **client_id** as username and **client_secret** as password

Type: http
Scheme: basic

## Download OpenAPI description

[HEMS APIs](https://docs-hems.obeliskapp.com/_bundle/apis/openapi.yaml)

## Authentication

Authentication APIs

### Acquire M2M access token

 - [POST /oauth/token](https://docs-hems.obeliskapp.com/apis/openapi/authentication/paths/~1oauth~1token/post.md): Obtains an access token using the OAuth 2.0 Client Credentials grant.

## Vendors

Vendor management APIs

### List vendors

 - [GET /vendors](https://docs-hems.obeliskapp.com/apis/openapi/vendors/paths/~1vendors/get.md): List all supported device vendors and their integration details

## Users

User management APIs

### Link user device

 - [POST /users/{userId}/link](https://docs-hems.obeliskapp.com/apis/openapi/users/paths/~1users~1%7Buserid%7D~1link/post.md): Link a user device to your organization

### Unlink user

 - [DELETE /users/{userId}/unlink](https://docs-hems.obeliskapp.com/apis/openapi/users/paths/~1users~1%7Buserid%7D~1unlink/delete.md): Unlink a user and delete all their devices

### List users

 - [GET /users](https://docs-hems.obeliskapp.com/apis/openapi/users/paths/~1users/get.md): List users linked under your organization

### Get user

 - [GET /users/{userId}](https://docs-hems.obeliskapp.com/apis/openapi/users/paths/~1users~1%7Buserid%7D/get.md): Get user details by user id

### Get user devices

 - [GET /users/{userId}/devices](https://docs-hems.obeliskapp.com/apis/openapi/users/paths/~1users~1%7Buserid%7D~1devices/get.md): Get user devices by user id

## Devices

Device management APIs

### List devices

 - [GET /devices](https://docs-hems.obeliskapp.com/apis/openapi/devices/paths/~1devices/get.md): List all devices linked under your organization

### Get device

 - [GET /devices/{deviceId}](https://docs-hems.obeliskapp.com/apis/openapi/devices/paths/~1devices~1%7Bdeviceid%7D/get.md): Get device details by ID. Supports field selection via query params.

### Send action to device

 - [POST /devices/{deviceId}/actions](https://docs-hems.obeliskapp.com/apis/openapi/devices/paths/~1devices~1%7Bdeviceid%7D~1actions/post.md): Send a relay command to a device. works only for shelly devices (Gen 1).

### Get device readings

 - [GET /devices/{deviceId}/readings](https://docs-hems.obeliskapp.com/apis/openapi/devices/paths/~1devices~1%7Bdeviceid%7D~1readings/get.md): Returns aggregated time-series readings for a device. 
  
Important Notes:
- Both the from and to query parameters must be provided in UTC (ISO 8601 format).
- The timestamps returned in the series buckets are also strictly in UTC.
- The returned data includes metrics for average power, max/min power, energy consumed, and energy returned over each bucket.

Granularity Constraints:
The allowed granularity dynamically depends on the requested date range length:
- ≤ 2 hours: 1min, 15min
- ≤ 24 hours: 1min, 15min, 1h
- ≤ 7 days: 15min, 1h, 4h
- ≤ 30 days: 1h, 4h, 1d
- > 30 days: 4h, 1d