Skip to content

REST API

The WattWächter REST API is available at http://wattwaechter-XXXXXXXXXXXX.local/api/v1/ and provides full access to device data, settings, and control functions.

Authentication

Disabled by default

API authentication is disabled by default. All endpoints are accessible without a token. Authentication can be enabled via the settings (api_auth_required: true).

When enabled, the API uses Bearer tokens in the Authorization header:

Authorization: Bearer YOUR_TOKEN

There are two token levels:

  • READ Token — Read data (history, status, view settings)
  • WRITE Token — Change settings, start OTA, trigger reboot

Token Renewal

Tokens can be renewed via a two-phase process:

  1. POST /api/v1/auth/tokens/generate — Generates new tokens (not yet active)
  2. POST /api/v1/auth/tokens/confirm — Activates the new tokens (within 60 seconds)

This two-phase approach prevents lockout if the response is lost.

Rate Limits & Error Codes

Because the WattWächter runs on an ESP32 with limited memory, incoming API requests are throttled. Clients should honor the Retry-After header and back off accordingly.

Rate Limit

A maximum of 25 requests per 10 seconds is allowed (device-wide, not per IP — multiple clients share the budget). When the limit is exceeded, the device responds with:

HTTP/1.1 429 Too Many Requests
Retry-After: 10
Content-Type: application/json

{"error":"Too many requests"}

Heap Protection

If the free heap drops below a critical threshold (25 KB), new API requests are temporarily rejected to keep the device stable:

HTTP/1.1 503 Service Unavailable
Retry-After: 5
Content-Type: application/json

{"error":"Service temporary unavailable"}

This typically happens during very large responses (e.g. long history ranges) under concurrent load. Retrying after a few seconds usually succeeds.

Python Client

The Python library handles both 429 and 503 automatically and respects the Retry-After header.

Endpoint Overview

System

Method Endpoint Auth Description
GET /api/v1/system/alive — Health check
GET /api/v1/system/info READ System information
GET /api/v1/system/led READ LED status
GET /api/v1/system/wifi_scan — WiFi scan
GET /api/v1/system/timezones READ Timezone list
POST /api/v1/system/reboot WRITE Reboot

History

Method Endpoint Auth Description
GET /api/v1/history/latest READ Latest reading
GET /api/v1/history/highRes?date=YYYY-MM-DD READ 15-min data for a day
GET /api/v1/history/lowRes?start=YYYY-MM-DD&days=7 READ Daily values

Settings

Method Endpoint Auth Description
GET /api/v1/settings READ Read settings
POST /api/v1/settings WRITE Update settings (partial)
POST /api/v1/auth/tokens/generate WRITE Generate new tokens
POST /api/v1/auth/tokens/confirm WRITE Activate tokens
GET /api/v1/mqtt/ca READ CA certificate status
POST /api/v1/mqtt/ca WRITE Upload CA certificate
DELETE /api/v1/mqtt/ca WRITE Delete CA certificate
POST /api/v1/cloud/pair WRITE Send cloud pairing token
DELETE /api/v1/cloud/pair WRITE Remove cloud pairing

OTA

Method Endpoint Auth Description
GET /api/v1/ota/check READ Check for update
POST /api/v1/ota/start WRITE Start update

Logs

Method Endpoint Auth Description
GET /api/v1/logs/rawdump READ SmartMeter ring buffer (binary)
GET /api/v1/logs/persistent READ Persistent CSV log file
GET /api/v1/logs/ram READ RAM log snapshot (CSV)

Modbus TCP

Method Endpoint Auth Description
GET /api/v1/modbus/status READ Modbus server status and current register map

→ Details & activation: Modbus TCP

Interactive API Documentation

The full API specification in OpenAPI format:

Note

The API documentation is automatically generated from the firmware's OpenAPI specification.