Skip to main content

Homsai Backend v2

This documentation describes the REST APIs of the Homsai Backend v2, a platform for monitoring and optimizing residential and industrial energy systems.
The backend is built with Spring Boot 3.1.1 (Java 17) using a Domain‑Driven Design architecture, and provides management of plants, devices, sensors, sensor/device types, load signatures, vendors, and advanced energy metrics (consumption, production, forecasts, and plant health).

Introduction​

Homsai exposes a set of REST APIs designed to be integrated into third‑party applications (web portals, mobile apps, supervision systems) to read and manage real‑time and historical energy data.
API access is protected with JSON Web Tokens (JWT), and permissions are scoped per resource (plants, devices, sensors, metrics, forecasts), following standard web API security best practices.

A typical deployment provides at least two environments:

  • a test/sandbox environment for development and integration testing;
  • a production environment for real plant data.

Getting Started​

This section walks you step‑by‑step through your first integration with the Homsai APIs: obtaining a JWT token and making your first call to the backend.

Prerequisites​

To get started you need:

  • A Homsai account enabled for API usage (user credentials).
  • The base URL of the APIs (for example: https://v2.api.homsai.app for production, plus an optional sandbox endpoint).
  • A tool to perform HTTP requests: cURL from the terminal, Postman, or an HTTP client in your preferred language (Python, JS, Java, etc.).

Getting a JWT token​

Authentication is performed via a credentials → JWT token exchange:

  1. Send a POST /auth/login request with email and password in the JSON body.
  2. In the response, the backend returns at least:
    • accessToken: short‑lived token to be used in the Authorization header;
    • refreshToken: longer‑lived token to obtain a new access token when it expires.

Every protected call must include the header:

Authorization: Bearer <accessToken>

When the accessToken expires, you can use GET /auth/token with the refreshToken (according to the implementation details: header or other documented channel) to obtain a new access token without repeating the login flow.

First “Hello World” call​

Once you have a valid accessToken, you can quickly verify that your integration works by performing a very simple request.

1. Login and get the token​

cURL example:

curl -X POST https://api.homsai.app/auth/login -H "Content-Type: application/json" -d '{
"email": "utente@example.com",
"password": "PasswordSicura123"
}'

From the JSON response, copy the value of the accessToken field.

2. Protected “Hello World” call​

Use a simple endpoint, for example:

  • GET /version to read the backend version, or
  • GET /protected as a test endpoint that only checks the presence of a valid JWT.

cURL example with GET /version:

curl -X GET https://api.homsai.app/version -H "Authorization: Bearer <accessToken>"

If the configuration is correct, you will receive:

  • an HTTP 200 OK status;
  • a JSON payload with version information (/version) or a minimal test payload (/protected).

This first request proves that:

  • the credentials are correct;
  • the login → token → authenticated call flow works end‑to‑end;
  • there are no network, CORS, or certificate issues towards the API endpoint.