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).

Authentication

POST /api/v1/auth/register

Create a new account with email and password.

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

Returns 201 with user object and sets session cookie. Returns 409 if email already exists.

POST /api/v1/auth/login

Sign in with email and password.

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

Returns 200 with user object and sets session cookie. Returns 401 on wrong credentials.

GET /api/v1/auth/me

Get the current authenticated user. Requires session cookie.

Returns 200 with user object containing id, email, name fields, or 401 if not authenticated.

POST /api/v1/auth/logout

End the current session. Clears session cookie.

GET /api/v1/auth/oauth/:provider

Redirect to OAuth provider login. Supported providers: google, microsoft, github.

Projects

All project endpoints require authentication (session cookie).

GET /api/v1/projects

List all projects for the authenticated user, ordered by last update.

POST /api/v1/projects

Create a new project.

{"name": "Sensor Node", "data": {"batteries": [...]}}
GET /api/v1/projects/:id

Get a project by ID (returns full data including batteries). Returns 404 if not found or not owned by user.

PUT /api/v1/projects/:id

Update a project. Only provided fields are updated (PATCH semantics).

DELETE /api/v1/projects/:id

Delete a project and all associated data. Returns 204 on success.

Telemetry

POST /api/v1/telemetry

Upload telemetry records. Requires API key as Authorization: Bearer <key> header.

{"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}
]}
GET /api/v1/telemetry/:projectId

Retrieve telemetry records for a project. Requires API key as Authorization: Bearer <key>. Key must be scoped to the requested project.

Formula History

POST /api/v1/formulas/history

Save a formula calculation to history. Requires session cookie.

{"formula_id": "ohms-law", "solve_for": "V", "inputs": {"I": 0.5, "R": 100}, "result": 50}
GET /api/v1/formulas/history?limit=50

Get recent formula calculations. Requires session cookie. Default limit is 50.

API Keys

POST /api/v1/keys

Create an API key for a project. Used by MCUs and scripts to upload telemetry data without a browser session.

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

Returns the key string. Store it securely — it cannot be retrieved again.

Error Responses

All errors return JSON with an error field:

{"error": "Not authenticated"}

Common HTTP status codes: 400 (bad request), 401 (not authenticated), 403 (forbidden), 404 (not found), 409 (conflict).