Référence de l'API

URL de base

https://api.vbatpower.com

Tous les points de terminaison sont préfixés par /api/v1. L'authentification se fait par cookies de session (pour les clients navigateur) ou par clés d'API (pour les clients MCU/serveur). L'API est gratuite, sans limites d'utilisation au-delà des limites de débit anti-abus décrites ci-dessous.

Authentification

{"email": "user@example.com", "password": "securePassword123"}

{"email": "user@example.com", "password": "securePassword123"}

Projets

Tous les points de terminaison de projet nécessitent une authentification (cookie de session). Les corps de projet peuvent atteindre 2 MB.

{"name": "Sensor Node", "data": {"batteries": [...]}}

Schéma data du projet

Le champ data contient le modèle du projet : un objet avec un tableau batteries. Chaque batterie possède un id numérique (son index hiérarchique de profondeur 1) et un tableau components ; chaque composant possède un id et un tableau states ; chaque état possède un id ainsi que ses champs de mode de fonctionnement. Les valeurs d'id correspondent directement aux ID de télémétrie en notation par points (batterie 0 → composant 0.0 → état 0.0.0).

{
  "name": "Sensor Node",
  "description": "ESP32 + INA219",
  "tags": ["esp32", "lipo"],
  "data": {
    "batteries": [
      {
        "id": 0,
        "name": "18650 cell",
        "voltageMin": 3.0,
        "voltageMax": 4.2,
        "current": 2.5,
        "currentUnit": "Ah",
        "components": [
          {
            "id": 0,
            "name": "ESP32",
            "states": [
              {"id": 0, "name": "Deep Sleep", "alwaysOn": true, "current": 10, "currentUnit": "u"},
              {"id": 1, "name": "Active", "current": 80, "currentUnit": "m", "interval": 60, "intervalUnit": "s", "execTime": 5, "execTimeUnit": "s"}
            ]
          }
        ]
      }
    ]
  }
}

Champs d'état courants : name, alwaysOn (booléen), current + currentUnit, interval + intervalUnit, execTime + execTimeUnit, et runOnce (booléen). L'objet data est stocké tel quel, de sorte que tout champ produit par l'application fait l'aller-retour intégralement.

Télémétrie

{"records": [
  {"id": "0", "type": "v", "value": 3.28, "unit": "V", "nonce": 1, "runid": 1},
  {"id": "0.0.0", "type": "t", "value": 1523, "unit": "ms", "nonce": 1, "runid": 1},
  {"id": "0.0.0", "type": "v", "value": 12.5, "unit": "mA", "nonce": 1, "runid": 1}
]}

{
  "project_id": 1,
  "records": [
    {"id": 42, "record_id": "0", "record_type": "v", "value": 3.28, "unit": "V", "nonce": 1, "runid": 1, "received_at": "2026-01-01T12:00:00.000Z"}
  ],
  "next_cursor": 42
}

Historique de formules

Tous les points de terminaison d'historique de formules nécessitent une authentification (cookie de session).

{"formula_id": "ohms-law", "solve_for": "V", "inputs": {"I": 0.5, "R": 100}, "result": 50}

Clés d'API

Tous les points de terminaison de gestion des clés d'API nécessitent une authentification (cookie de session). Les clés sont utilisées par les MCU et les scripts pour téléverser de la télémétrie sans session de navigateur.

{"project_id": 1, "name": "ESP32 Sensor"}

Limites de débit

VBatPower est gratuit, sans quotas d'utilisation. Les seules limites sont des limites de débit anti-abus, appliquées par IP (authentification) ou par projet (télémétrie) en production :

• POST /api/v1/auth/register — 5 requêtes par 15 minutes par IP
• POST /api/v1/auth/login — 10 requêtes par 15 minutes par IP
• POST /api/v1/telemetry — 60 requêtes par minute par projet

Le dépassement d'une limite renvoie 429 avec le corps {"error": "Too many requests"}. Les corps de requête sont également plafonnés : 64 KB pour les routes d'authentification, de clés et d'historique de formules ; 2 MB pour les projets et la télémétrie. Les corps surdimensionnés renvoient 413 avec {"error": "Payload too large"}.

Réponses d'erreur

Toutes les erreurs renvoient du JSON avec un champ error décrivant le problème :

{"error": "Not authenticated"}

Codes de statut HTTP utilisés par l'API :

• 400 — requête incorrecte (JSON invalide, champ manquant ou mal formé)
• 401 — non authentifié (session manquante/expirée ou clé d'API invalide)
• 403 — interdit (clé d'API non limitée au projet demandé)
• 404 — introuvable (ou n'appartenant pas à l'utilisateur authentifié)
• 409 — conflit (e-mail déjà enregistré)
• 413 — charge utile trop volumineuse
• 429 — trop de requêtes (limite de débit dépassée)
• 500 — erreur interne

Procédure MCU de bout en bout

Ceci relie les points de terminaison entre eux pour le flux matériel typique : générer une clé, créer un projet, pousser de la télémétrie, et la relire. Toutes les requêtes utilisent l'URL de base https://api.vbatpower.com.

1. Créer un projet (session de navigateur)

Connectez-vous à l'application, ou appelez l'API avec votre cookie de session :

curl -X POST https://api.vbatpower.com/api/v1/projects \
  -H "Content-Type: application/json" \
  --cookie "session=YOUR_SESSION" \
  -d '{"name":"Sensor Node","data":{"batteries":[{"id":0,"components":[{"id":0,"states":[{"id":0}]}]}]}}'
# -> 201 {"project": {"id": 1, ...}}

2. Générer une clé d'API pour ce projet

curl -X POST https://api.vbatpower.com/api/v1/keys \
  -H "Content-Type: application/json" \
  --cookie "session=YOUR_SESSION" \
  -d '{"project_id":1,"name":"ESP32 Sensor"}'
# -> 201 {"key": "vbat_xxxxxxxx...", "project_id": 1}
# Copy the key now — it is shown only once.

3. POSTer la télémétrie depuis l'appareil (clé Bearer)

Aucune session ni cookie nécessaire — la clé authentifie l'appareil et sélectionne le projet. Voir Intégration MCU pour du code Arduino/ESP32/STM32 qui produit cette requête.

curl -X POST https://api.vbatpower.com/api/v1/telemetry \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer vbat_xxxxxxxx..." \
  -d '{"records":[
    {"id":"0","type":"v","value":3.28,"unit":"V","nonce":1,"runid":1},
    {"id":"0.0.0","type":"t","value":1523,"unit":"ms","nonce":1,"runid":1},
    {"id":"0.0.0","type":"v","value":12.5,"unit":"mA","nonce":1,"runid":1},
    {"id":"0.0.0","type":"n","value":0,"unit":"ms","nonce":1,"runid":1}
  ]}'
# -> 201 {"status": "ok", "inserted": 4}

4. Vérifier que les données sont bien arrivées

Relisez-les avec la même clé, ou ouvrez la page Graphiques du projet dans l'application :

curl https://api.vbatpower.com/api/v1/telemetry/1?limit=1000 \
  -H "Authorization: Bearer vbat_xxxxxxxx..."
# -> 200 {"project_id": 1, "records": [...], "next_cursor": 42}
# Page through more rows by passing ?cursor=42 on the next call.