Referencia de la API

URL base

https://api.vbatpower.com

Todos los endpoints llevan el prefijo /api/v1. La autenticación se realiza mediante cookies de sesión (para clientes de navegador) o claves de API (para clientes MCU/servidor). La API es gratuita y sin límites de uso más allá de los límites de tasa de protección contra abuso descritos a continuación.

Autenticación

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

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

Proyectos

Todos los endpoints de proyectos requieren autenticación (cookie de sesión). Los cuerpos de proyecto pueden ser de hasta 2 MB.

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

Esquema de data del proyecto

El campo data contiene el modelo del proyecto: un objeto con un array de batteries. Cada batería tiene un id numérico (su índice jerárquico de nivel 1) y un array de components; cada componente tiene un id y un array de states; cada estado tiene un id más sus campos de modo de funcionamiento. Los valores de id se corresponden directamente con los ID de telemetría en notación de punto (batería 0 → componente 0.0 → estado 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"}
            ]
          }
        ]
      }
    ]
  }
}

Campos comunes de estado: name, alwaysOn (booleano), current + currentUnit, interval + intervalUnit, execTime + execTimeUnit y runOnce (booleano). El objeto data se almacena tal cual, por lo que cualquier campo producido por la aplicación se conserva en el ciclo de ida y vuelta.

Telemetría

{"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
}

Historial de fórmulas

Todos los endpoints del historial de fórmulas requieren autenticación (cookie de sesión).

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

Claves de API

Todos los endpoints de gestión de claves de API requieren autenticación (cookie de sesión). Las claves las usan los MCU y los scripts para subir telemetría sin una sesión de navegador.

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

Límites de tasa

VBatPower es gratuito y sin cuotas de uso. Los únicos límites son los límites de tasa de protección contra abuso, aplicados por IP (autenticación) o por proyecto (telemetría) en producción:

• POST /api/v1/auth/register — 5 peticiones cada 15 minutos por IP
• POST /api/v1/auth/login — 10 peticiones cada 15 minutos por IP
• POST /api/v1/telemetry — 60 peticiones por minuto por proyecto

Superar un límite devuelve 429 con el cuerpo {"error": "Too many requests"}. Los cuerpos de las peticiones también tienen un tope: 64 KB para las rutas de autenticación, claves e historial de fórmulas; 2 MB para proyectos y telemetría. Los cuerpos de tamaño excesivo devuelven 413 con {"error": "Payload too large"}.

Respuestas de error

Todos los errores devuelven JSON con un campo error que describe el problema:

{"error": "Not authenticated"}

Códigos de estado HTTP usados por la API:

• 400 — petición incorrecta (JSON no válido, campo ausente o mal formado)
• 401 — no autenticado (sesión ausente/expirada o clave de API no válida)
• 403 — prohibido (clave de API no acotada al proyecto solicitado)
• 404 — no encontrado (o no perteneciente al usuario autenticado)
• 409 — conflicto (correo electrónico ya registrado)
• 413 — carga útil demasiado grande
• 429 — demasiadas peticiones (límite de tasa superado)
• 500 — error interno

Recorrido de extremo a extremo con MCU

Esto enlaza los endpoints para el flujo de hardware típico: generar una clave, crear un proyecto, enviar telemetría y leerla de vuelta. Todas las peticiones usan la URL base https://api.vbatpower.com.

1. Crea un proyecto (sesión de navegador)

Inicia sesión en la aplicación o llama a la API con tu cookie de sesión:

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. Genera una clave de API para ese proyecto

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. Envía telemetría por POST desde el dispositivo (clave Bearer)

No se necesita sesión ni cookie: la clave autentica el dispositivo y selecciona el proyecto. Consulta Integración con MCU para ver código de Arduino/ESP32/STM32 que produce esta petición.

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. Verifica que los datos llegaron

Léelos de vuelta con la misma clave, o abre la página de Gráficos del proyecto en la aplicación:

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.