API Reference

Base URL

https://api.vbatpower.com

All endpoints are prefixed with /api/v1. Authentication is via session cookies (for browser clients) or API keys (for MCU/server clients). The API is free with no usage limits beyond the abuse-protection rate limits described below.

Authentication

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

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

Projects

All project endpoints require authentication (session cookie). Project bodies may be up to 2 MB.

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

Project data schema

The data field holds the project model: an object with a batteries array. Each battery has a numeric id (its depth-1 hierarchical index) and a components array; each component has an id and a states array; each state has an id plus its operating-mode fields. The id values map directly onto the dot-notation telemetry IDs (battery 0 → component 0.0 → state 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"}
            ]
          }
        ]
      }
    ]
  }
}

Common state fields: name, alwaysOn (boolean), current + currentUnit, interval + intervalUnit, execTime + execTimeUnit, and runOnce (boolean). The data object is stored as-is, so any fields produced by the app are round-tripped.

Telemetry

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

Formula History

All formula-history endpoints require authentication (session cookie).

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

API Keys

All API-key management endpoints require authentication (session cookie). Keys are used by MCUs and scripts to upload telemetry without a browser session.

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

Rate Limits

VBatPower is free with no usage quotas. The only limits are abuse-protection rate limits, enforced per IP (auth) or per project (telemetry) in production:

• POST /api/v1/auth/register — 5 requests per 15 minutes per IP
• POST /api/v1/auth/login — 10 requests per 15 minutes per IP
• POST /api/v1/telemetry — 60 requests per minute per project

Exceeding a limit returns 429 with body {"error": "Too many requests"}. Request bodies are also capped: 64 KB for auth, keys, and formula-history routes; 2 MB for projects and telemetry. Oversized bodies return 413 with {"error": "Payload too large"}.

Error Responses

All errors return JSON with an error field describing the problem:

{"error": "Not authenticated"}

HTTP status codes used by the API:

• 400 — bad request (invalid JSON, missing or malformed field)
• 401 — not authenticated (missing/expired session or invalid API key)
• 403 — forbidden (API key not scoped to the requested project)
• 404 — not found (or not owned by the authenticated user)
• 409 — conflict (email already registered)
• 413 — payload too large
• 429 — too many requests (rate limit exceeded)
• 500 — internal error

End-to-End MCU Walkthrough

This ties the endpoints together for the typical hardware flow: generate a key, create a project, push telemetry, and read it back. All requests use the base URL https://api.vbatpower.com.

1. Create a project (browser session)

Sign in to the app, or call the API with your session cookie:

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. Generate an API key for that project

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. POST telemetry from the device (Bearer key)

No session or cookie needed — the key authenticates the device and selects the project. See MCU Integration for Arduino/ESP32/STM32 code that produces this request.

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. Verify the data landed

Read it back with the same key, or open the project's Graphs page in the app:

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.