Skip to main content

SDKs & Code Examples

This section provides practical examples of how to use the Homsai APIs in different contexts, using cURL and common HTTP clients. The examples reuse the most important endpoints described in the other sections.

Overview​

The examples show how to:

  • authenticate and obtain an accessToken;
  • add the Authorization header to your requests;
  • call some key endpoints (plants, metrics, etc.).

You can use them as a starting point to build SDKs or wrappers in your own applications.

Note: always replace https://v2.api.homsai.app with the correct environment URL (sandbox or production), and use real credentials/tokens.

cURL examples​

Login (obtain accessToken)​

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

From the JSON response, extract the accessToken field.

List plants​

curl -X GET "https://v2.api.homsai.app/plants?page=0&size=10"
-H "Authorization: Bearer <accessToken>"

Get daily power consumptions​

curl -X GET "https://v2.api.homsai.app/plants/<plantUuid>/daily-power-consumptions?date=2025-01-15"
-H "Authorization: Bearer <accessToken>"

JavaScript (fetch)​

These examples show how to implement the basic flow in JavaScript:

  • perform login with POST /auth/login;
  • store the accessToken;
  • use the token to call a protected endpoint (e.g. plant list).

Login and store token​

async function login() {
  const response = await fetch("https://v2.api.homsai.app/auth/login", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      email: "user@example.com",
      password: "SecurePassword123",
    }),
  });

  if (!response.ok) {
    throw new Error("Login failed");
  }

  const data = await response.json();
  return data.accessToken;
}

This block performs the login, checks that the response is ok, and returns the accessToken obtained from the backend.

Call a protected endpoint​

async function listPlants(accessToken) {
const response = await fetch("https://v2.api.homsai.app/plants?page=0&size=10", {
headers: {
Authorization: Bearer ${accessToken},
},
});

if (!response.ok) {
throw new Error(Error listing plants: ${response.status});
}

return response.json();
}

This block shows how to use the accessToken in the Authorization: Bearer <token> header to call a protected endpoint (GET /plants) and handle basic client‑side errors.

Python (requests)​

These examples show how to implement the same flow in Python:

  • a login function that returns the accessToken;
  • a function that uses the token to call a metrics endpoint (PV health).

Login​

import requests

BASE_URL = "https://v2.api.homsai.app"

def login(email, password):
url = f"{BASE_URL}/auth/login"
payload = {"email": email, "password": password}
resp = requests.post(url, json=payload)
resp.raise_for_status()
data = resp.json()
return data["accessToken"]

This function calls POST /auth/login, raises exceptions on HTTP errors (raise_for_status), and returns the accessToken extracted from the JSON response.

Get PV health​

def get_pv_health(access_token, plant_uuid):
url = f"{BASE_URL}/plants/{plant_uuid}/pv-health"
headers = {"Authorization": f"Bearer {access_token}"}
resp = requests.get(url, headers=headers)
resp.raise_for_status()
return resp.json()

This function uses the accessToken in the Authorization header to call the GET /plants/{plantUuid}/pv-health endpoint and returns the JSON payload with the plant health indicators.

These snippets are intentionally minimal: in a real‑world context you should add structured error handling (401/403/5xx), logging, and automatic token refresh.