Skip to content

REST API

Same API as the WattWächter Plus

The REST API of the WattWächter Gas is the same as on the WattWächter Plus. The readings, however, carry the unit m³ in their names (e.g. import_total_m3, flow_m3h, consumption_m3 instead of import_total_kWh, power_W), feed-in values are missing, and /api/v1/history/latest additionally contains a gw block with sensor data. Which device answers is shown in /api/v1/system/info under esp.model_id (ww_gw_mf or ww_gw_id, ww_plus on the Plus).

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. The one exception: writing from other web pages. 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

Alternatively, use the header X-Api-Token: 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.

Writing from other web pages (from firmware 1.3)

Even with authentication off, not every web page may write to the device. When a browser sends a request from a page that the device did not serve, the request needs the WRITE token. This keeps a foreign web page that somebody in the same network opens from changing settings or switching devices.

  • Affected: all calls that change something (POST, DELETE). Reading (GET) still works without a token.
  • Not affected: the device's web interface, the app, Home Assistant and your own scripts.

Without the token the device answers:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{"error":"Write access from another web page needs the WRITE token"}

A web page of your own that is meant to write to the device sends the WRITE token:

fetch('http://wattwaechter-XXXXXXXXXXXX.local/api/v1/settings', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_WRITE_TOKEN'
  },
  body: JSON.stringify({ ledEnable: false })
});

The WRITE token is shown during initial setup. If you did not note it down, create new tokens in the web interface under Settings → API security.

Behind a reverse proxy

The device recognises a foreign page by an Origin header that names another host than the Host header. A reverse proxy therefore has to pass the Host header on (nginx: proxy_set_header Host $host;). Otherwise the device also refuses changes from its own web interface.

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) — see Changing settings
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
GET /api/v1/cloud/pair READ Status of pairing and cloud connection
DELETE /api/v1/cloud/pair WRITE Remove cloud pairing; ?data=delete also deletes the cloud history

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

Switching (from firmware 1.3)

Method Endpoint Auth Description
GET /api/v1/switch/status READ State of the switching rules
POST /api/v1/switch/test WRITE Switch a rule's device by hand or check the connection

Turning features on and off and the rules themselves go through POST /api/v1/settings.

Changing settings (POST /api/v1/settings)

Everything you save in the web interface under Settings goes through this one endpoint. You can call it just the same from scripts, Home Assistant (rest_command), Node-RED or ioBroker.

How it works

  • Only what you send changes. You don't need a GET first and never send the whole configuration. {"ledEnable": false} only turns off the LED; everything else stays as it is.
  • Format: JSON with Content-Type: application/json, at most 2 KB per request (from firmware 1.3: 8 KB).
  • One change per second. If the next request comes sooner, the device answers 429 with Retry-After: 1. To change several areas, best do it in one request.
  • Response: {"success": true, "applied": {…}}. applied echoes your request — not the stored state. Passwords are left out from firmware 1.3; older firmware returns them in clear text. Whether a value arrived is shown by a subsequent GET /api/v1/settings.
  • Passwords (Wi-Fi, access point, MQTT, NES meter) are never returned by GET, only whether one is set (password_set, passwordSet). Leave the field out = password stays; empty text "" = password is deleted.
  • Unknown top-level fields are rejected with 400 (Unknown field: …), so a typo shows up. Unknown nested fields (e.g. mqtt.hots), however, are silently ignored; check with GET after saving.
  • Most changes take effect immediately, without a restart: MQTT reconnects, Modbus starts or stops, the access point restarts, the time zone applies at once. Wi-Fi changes trigger a reconnect — see Changing Wi-Fi.
  • With API protection you need the WRITE token, either as Authorization: Bearer YOUR_WRITE_TOKEN or as X-Api-Token: YOUR_WRITE_TOKEN.

In the examples, WW stands for your device's address, e.g.:

WW=http://wattwaechter-XXXXXXXXXXXX.local      # or the IP address, e.g. http://192.168.178.50

If API protection is on, add -H "Authorization: Bearer YOUR_WRITE_TOKEN" to every call.

Reading the current settings

curl -s $WW/api/v1/settings

The response has the same structure you use for writing. It also contains display-only values such as rebootsTotal or password_set, which cannot be written.

Device name

Shown in the web interface, in Home Assistant and in the app. At most 31 characters.

curl -s -X POST $WW/api/v1/settings \
  -H "Content-Type: application/json" \
  -d '{"device_name": "Basement main meter"}'

Turning the status LED off or on

curl -s -X POST $WW/api/v1/settings \
  -H "Content-Type: application/json" \
  -d '{"ledEnable": false}'

Time zone, time server and language

GET /api/v1/system/timezones lists the allowed time zones; an unknown name is rejected with 400 Invalid timezone. The web interface language is de or en.

curl -s -X POST $WW/api/v1/settings \
  -H "Content-Type: application/json" \
  -d '{
        "timezone": "Europe/Berlin",
        "ntp_server": "fritz.box",
        "language": { "active": "en" }
      }'

Changing Wi-Fi

Careful: you can lock yourself out

After a Wi-Fi change the device reconnects. If SSID or password are wrong, it is no longer reachable on the old network. It then falls back to the fallback Wi-Fi or the access point. The response arrives before the switch — it only confirms that the values were stored, not that the connection works.

curl -s -X POST $WW/api/v1/settings \
  -H "Content-Type: application/json" \
  -d '{
        "wifi": {
          "primary": { "ssid": "MyWiFi", "password": "secret-password" }
        }
      }'

The SSID may have at most 32 characters (otherwise 400). If nothing changes in the Wi-Fi fields, the device doesn't reconnect either.

Fixed IP address

curl -s -X POST $WW/api/v1/settings \
  -H "Content-Type: application/json" \
  -d '{
        "wifi": {
          "primary": {
            "static_ip": true,
            "ip": "192.168.178.50",
            "subnet": "255.255.255.0",
            "gateway": "192.168.178.1",
            "dns": "192.168.178.1"
          }
        }
      }'

Back to DHCP: {"wifi": {"primary": {"static_ip": false}}}. Simpler and safer is usually to give the WattWächter a fixed address in your router.

Fallback Wi-Fi

A second network the WattWächter uses when the first one is unreachable (e.g. a repeater in the basement).

curl -s -X POST $WW/api/v1/settings \
  -H "Content-Type: application/json" \
  -d '{
        "wifi": {
          "secondary": { "enable": true, "ssid": "MyWiFi-Basement", "password": "other-password" }
        }
      }'

Access point

The access point is the WattWächter's own Wi-Fi for setup. Turn it off:

curl -s -X POST $WW/api/v1/settings \
  -H "Content-Type: application/json" \
  -d '{"accessPoint": {"enable": false}}'

With your own name and password:

curl -s -X POST $WW/api/v1/settings \
  -H "Content-Type: application/json" \
  -d '{
        "accessPoint": {
          "enable": true,
          "ssid": "WattWaechter-Basement",
          "password_enable": true,
          "password": "atleast8chars"
        }
      }'

Password with at least 8 characters

WPA2 requires 8 to 63 characters. From firmware 1.3 the API rejects a shorter or longer password with 400. Older firmware accepts it, but the access point then starts without a password. An empty password clears the password, an empty ssid restores the automatic name.

MQTT

Set up a connection to your own broker (here Mosquitto in Home Assistant without TLS):

curl -s -X POST $WW/api/v1/settings \
  -H "Content-Type: application/json" \
  -d '{
        "mqtt": {
          "enable": true,
          "host": "homeassistant.local",
          "port": 1883,
          "use_tls": false,
          "user": "wattwaechter",
          "password": "mqtt-password",
          "sendInterval": 10
        }
      }'
  • sendInterval: seconds between two reading messages, at least 1.
  • client_id: the name the device uses to log in to the broker. Empty text "" restores the default (the host name wattwaechter-…).
  • topic_prefix: start of all topics, e.g. "WattWaechter/basement".
  • Upload your own CA certificate for TLS separately via POST /api/v1/mqtt/ca.

Change only the interval — the other MQTT values stay:

curl -s -X POST $WW/api/v1/settings \
  -H "Content-Type: application/json" \
  -d '{"mqtt": {"sendInterval": 60}}'

GET /api/v1/mqtt/status shows whether the connection is up. More under MQTT.

Modbus TCP

curl -s -X POST $WW/api/v1/settings \
  -H "Content-Type: application/json" \
  -d '{"modbus": {"enable": true, "port": 502}}'

The server starts immediately. GET /api/v1/modbus/status shows which registers it serves — see Modbus TCP.

Automatic updates and cloud

# Stop installing updates automatically at night
curl -s -X POST $WW/api/v1/settings \
  -H "Content-Type: application/json" \
  -d '{"autoOta": false}'

# Pause the connection to the WattWächter cloud (the pairing stays)
curl -s -X POST $WW/api/v1/settings \
  -H "Content-Type: application/json" \
  -d '{"awsIotEnabled": false}'

The cloud pairing itself is controlled via POST/DELETE /api/v1/cloud/pair.

Turning on API protection

From then on almost every call needs a token (except e.g. /system/alive). So that you don't lock yourself out, the device only accepts the change if you already send the WRITE token with it — otherwise it answers 403. The tokens are in the web interface under Settings → API security.

curl -s -X POST $WW/api/v1/settings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_WRITE_TOKEN" \
  -d '{"api_auth_required": true}'

Turning it off: {"api_auth_required": false} (also with the WRITE token, since protection is still on at that point).

WattWächter Gas only: meter settings

The device checks all values under gw before saving anything. If one is out of range, the whole request is rejected with 400 and nothing changes.

Entering or correcting the meter reading

initialReading is the reading in m³ you currently see on the meter. The device counts on from this value; the correction does not count as consumption.

curl -s -X POST $WW/api/v1/settings \
  -H "Content-Type: application/json" \
  -d '{"gw": {"initialReading": 1234.567}}'

Each entry increments readingSeq (visible in GET /api/v1/settings under gw). The current reading is shown there as reading.

Medium, volume per revolution and sensitivity

curl -s -X POST $WW/api/v1/settings \
  -H "Content-Type: application/json" \
  -d '{
        "gw": {
          "medium": "gas",
          "pulseVolume": 0.01,
          "hysteresis": 250
        }
      }'
Field Range Meaning
medium "gas" or "water" What is counted
pulseVolume 0.0001–1 m³ Volume per revolution of the counter wheel (gas typically 0.01, water 0.001)
hysteresis magnetic (GW-MF): 10–5000 µT, default 250 · inductive (GW-ID): 5–500 counts, default 15 Sensitivity or minimum swing of the detection

Changing pulseVolume does not make the reading jump; only future revolutions count with the new value. Your variant is shown in GET /api/v1/system/info under esp.model_id (ww_gw_mf / ww_gw_id).

Conversion to kWh (gas only)

Calorific value and Z-number are on your gas bill. The device uses them to convert m³ to kWh (m³ × Z-number × calorific value).

curl -s -X POST $WW/api/v1/settings \
  -H "Content-Type: application/json" \
  -d '{"gw": {"calorificValue": 11.2, "zNumber": 0.9542}}'
Field Range
calorificValue 5–15 kWh/m³
zNumber 0.8–1.2

Switching devices (from firmware 1.3)

Switching rules turn a Shelly or another device with an HTTP interface on or off — by readings, time of day and run time or by the volume that has flowed. Up to 4 rules. In the web interface you find them under Settings → Switching.

The list is always replaced completely

Unlike the other settings, switch.rules is not a partial update: you send all rules that should apply afterwards. A rule missing from the list is deleted. So read the current list first with GET /api/v1/settings (field switch.rules), change it and send it back in full. If one rule is invalid, nothing is saved.

Structure of a rule

Every rule has a target (target) and two sides: on says when to switch on, off when to switch off. Each side has up to 4 conditions (conditions). match sets how they are combined:

  • "all": all conditions must hold (AND). This also applies if match is missing.
  • "any": one condition is enough (OR).

A side may stay empty ("conditions": []). Then the rule never switches in that direction — for example a valve that it only closes, but never opens. At least one side needs a condition.

{
  "name": "Example",
  "enable": true,
  "target": { "type": "shelly", "host": "192.168.178.60", "channel": 0 },
  "on":  { "match": "all", "conditions": [ … ] },
  "off": { "match": "any", "conditions": [ … ] }
}
Field Values Meaning
name at most 31 characters Display name
enable true / false Rule active. If the field is missing, it is active
target.type shelly, tasmota or url Shelly (Gen1 and Gen2+, detected automatically), Tasmota device or your own address for any other device
target.host IP or name, optionally with :port For shelly and tasmota, without http://
target.channel 0–3 (shelly), 0–7 (tasmota) Output, counted from 0: the id on a Shelly; on Tasmota 0 stands for Power1, 1 for Power2 and so on
target.on_url, target.off_url http://…, at most 159 characters Only for url: called with GET. https is not supported. A side with conditions needs its address, the other one may be empty ("")
on, off match: all or any · conditions: up to 4 Switch-on or switch-off side

Conditions

type Fields Met when … Device
value source, op (above or below), value, delay (0–86400 s, default 0) the reading is above or below value — without a break for at least delay seconds all, readings see below
time at ("HH:MM"), days it is exactly this time. Holds for the whole minute all
window from, to ("HH:MM"), days the time is from from and before to. Also works across midnight all
state for (1–604800 s) the device has been in the opposite state for at least for seconds: on the off side on for, on the on side off for all
volume value (m³, greater than 0) at least this much has flowed since the last change — on the off side that means since switching on Gas and Water only

days is a list of weekdays: 1 = Monday to 7 = Sunday. If the field is missing, every day applies. A window across midnight belongs to the day on which it starts: {"type": "window", "from": "22:00", "to": "06:00", "days": [5]} holds from Friday 22:00 to Saturday 06:00.

With state you build run times and pauses. On the off side with "any" it is a maximum run time (off after … at the latest), with "all" a minimum run time (off after … at the earliest). On the on side the same applies to the pause.

Which readings? (source)

A value condition watches one of four readings. Which ones a device knows depends on what it measures:

source Unit Device What is measured
export W WattWächter Plus Surplus = feed-in to the grid. Positive while you feed in, negative while importing
import W WattWächter Plus Grid import. Positive while you draw power, negative while feeding in
flow m³/h WattWächter Gas, WattWächter Water Flow rate at the meter, calculated from the pulses, never negative
draw m³ WattWächter Gas, WattWächter Water Volume without a break: what has flowed since the current flow began. When the flow drops to 0 it starts over

export and import are the same reading (the current power at the meter, OBIS 16.7.0) with opposite signs: "export" with above 1500 means "more than 1500 W feed-in", "import" with above 1500 means "more than 1500 W import". Use whichever makes your threshold read naturally; export below 0 is the same as import above 0.

On this device flow and draw are possible — it measures gas or water, not power. A rule with export or import is rejected with 400 switch.rules[0]: source not available on this device.

draw and the volume condition both count cubic metres, but from a different moment: draw from the start of the flow, no matter what was switched. volume from the last change of the switched device.

In the API, flow and volumes are always in m³/h and m³. Which readings a device knows is listed in GET /api/v1/switch/status under sources.

Examples

A Shelly turns on a warning light when more than 2.5 m³/h of gas flow for 10 minutes, and off again when the flow stays below 0.5 m³/h for a minute.

curl -s -X POST $WW/api/v1/settings \
  -H "Content-Type: application/json" \
  -d '{
        "switch": {
          "rules": [
            {
              "name": "Gas warning light",
              "enable": true,
              "target": { "type": "shelly", "host": "192.168.178.60", "channel": 0 },
              "on":  { "match": "all", "conditions": [
                { "type": "value", "source": "flow", "op": "above", "value": 2.5, "delay": 600 }
              ] },
              "off": { "match": "all", "conditions": [
                { "type": "value", "source": "flow", "op": "below", "value": 0.5, "delay": 60 }
              ] }
            }
          ]
        }
      }'

More examples

Put the following rules into the rules list on their own or together (at most 4 rules per device).

Extractor hood when cooking with gas — minimum run time, name instead of IP, second output. If gas flows for 10 seconds, the extractor hood starts via output 2 of a Shelly Plus 2PM. It goes off once hardly anything flows for 5 minutes and it has run for at least 10 minutes.

{
  "name": "Extractor hood",
  "enable": true,
  "target": { "type": "shelly", "host": "shelly-kitchen.local", "channel": 1 },
  "on":  { "match": "all", "conditions": [
    { "type": "value", "source": "flow", "op": "above", "value": 0.05, "delay": 10 }
  ] },
  "off": { "match": "all", "conditions": [
    { "type": "value", "source": "flow", "op": "below", "value": 0.01, "delay": 300 },
    { "type": "state", "for": 600 }
  ] }
}

A lot of gas without a break. If more than 5 m³ are used without a break, a warning light turns on and goes off again after 30 minutes.

{
  "name": "Gas 5 m³ without a break",
  "enable": true,
  "target": { "type": "shelly", "host": "192.168.178.62", "channel": 0 },
  "on":  { "match": "all", "conditions": [
    { "type": "value", "source": "draw", "op": "above", "value": 5, "delay": 0 }
  ] },
  "off": { "match": "all", "conditions": [
    { "type": "state", "for": 1800 }
  ] }
}

Full load in the middle of the night — window and time of day, Tasmota, prepared. With night setback the heating hardly runs at night. If it draws more than 2 m³/h for 30 minutes between 00:00 and 05:00, a Tasmota plug turns on a warning light. At 07:00 it goes off. The rule is prepared but still switched off ("enable": false).

{
  "name": "Gas at night",
  "enable": false,
  "target": { "type": "tasmota", "host": "192.168.178.62", "channel": 0 },
  "on":  { "match": "all", "conditions": [
    { "type": "window", "from": "00:00", "to": "05:00" },
    { "type": "value", "source": "flow", "op": "above", "value": 2, "delay": 1800 }
  ] },
  "off": { "match": "all", "conditions": [
    { "type": "time", "at": "07:00" }
  ] }
}

Report high consumption — own URL, switch on only. If more than 3 m³/h flow for 15 minutes, a Wi-Fi plug that is neither a Shelly nor Tasmota turns on a warning light via its HTTP address. The off side stays empty: you turn the light off yourself after checking.

{
  "name": "Gas warning lamp",
  "enable": true,
  "target": { "type": "url", "on_url": "http://192.168.178.62/relay?state=on", "off_url": "" },
  "on":  { "match": "all", "conditions": [
    { "type": "value", "source": "flow", "op": "above", "value": 3, "delay": 900 }
  ] },
  "off": { "match": "all", "conditions": [] }
}

Pure timer without a reading. A pump runs for 5 minutes, pauses for 25 minutes, and so on. Both sides only ask how long the device has been in the opposite state. Counting starts the moment the WattWächter knows the Shelly's state. A restart of the WattWächter does not interrupt it.

{
  "name": "Cycle 5/25",
  "enable": true,
  "target": { "type": "shelly", "host": "192.168.178.64", "channel": 0 },
  "on":  { "match": "all", "conditions": [ { "type": "state", "for": 1500 } ] },
  "off": { "match": "all", "conditions": [ { "type": "state", "for": 300 } ] }
}

What the examples show together

Variant Where
Shelly with IP, name (….local) or IP:port host
Second output of a multi-channel Shelly "channel": 1
Tasmota device, first output (Power1) "type": "tasmota", "channel": 0
Own URL, also with an on address only "type": "url", "off_url": ""
Switch on only or off only Leave the other side empty: "conditions": []
Several conditions "match": "all" (AND) or "match": "any" (OR)
Minimum / maximum run time state on the off side, with all or any
Time of day, window, weekdays time, window, days
Switch at once "delay": 0
Prepare a rule without activating it yet "enable": false

Delete all rules:

curl -s -X POST $WW/api/v1/settings \
  -H "Content-Type: application/json" \
  -d '{"switch": {"rules": []}}'

Behaviour

  • A side switches when it is newly met — once while it keeps holding. A time condition holds for one minute and so switches once a day.
  • Switched by hand stays switched. If you switch the device (on the Shelly, in its app or via /switch/test), the rule does not overrule you while its side keeps holding. Only once the side has cleared and is met again does it switch again.
  • If both sides become met at the same moment, switching off wins. The on side only switches again once it has not held for a moment.
  • Time of day and weekday follow the device's time zone. Until the clock is set by the time server (NTP), time and window do not hold. The time the device currently assumes is in /switch/status under time. A missed switch time (time) is caught up for up to 15 minutes: every 30 seconds while the target cannot be reached, once after a gap in Wi-Fi, not after a power failure.
  • state and volume need the device's state. The WattWächter polls a Shelly and a Tasmota device every 30 seconds, so changes by hand count too. With your own URL it only knows the state after it has switched itself — before that these conditions do not hold. So start a timer with your own URL once via /switch/test.
  • State and duration survive a restart. For each rule the WattWächter remembers the state and the time of the last change. After a restart “on for” and “off for” continue from there — for Shelly and Tasmota provided the device is still in the same state. A changed rule starts over.
  • Without a fresh reading a value condition does not hold (sensor reports an error). Its delay starts over afterwards. This also applies to the switch-off side: without a reading a device that is on stays on. To guard against that, give the switch-off side with "any" a maximum running time as well (state). The web interface shows a hint at the rule while the reading is missing. A meter that stands still is not an error: a flow of 0 is a valid reading.
  • If a command fails (device unreachable), the WattWächter tries again after 30 seconds.
  • A missed switching time (time) is caught up for up to 15 minutes. If the device cannot be reached during the switching minute, the WattWächter keeps trying. If it could not evaluate during that minute itself (no WiFi, clock not yet set, start takes longer), it switches at the next opportunity — unless the device has already changed since the switching time. After a power failure nothing is caught up.
  • Password-protected Shellys and Tasmota devices are not supported yet. A Tasmota device with a password can be switched via url: http://<ip>/cm?user=admin&password=<password>&cmnd=Power%20On.

Querying the state and testing by hand

curl -s $WW/api/v1/switch/status

# Switch rule 0's device on by hand (does not count as a switching action of the rule)
curl -s -X POST $WW/api/v1/switch/test \
  -H "Content-Type: application/json" \
  -d '{"rule": 0, "action": "on"}'

# Only check the connection to the Shelly
curl -s -X POST $WW/api/v1/switch/test \
  -H "Content-Type: application/json" \
  -d '{"rule": 0, "action": "check"}'

/switch/test answers 202 at once; the result appears one to three seconds later in /switch/status under manual.

Fields in GET /api/v1/switch/status:

Field Meaning
sources Readings this device knows (flow, draw)
volume true if volume conditions are possible (Gas and Water)
max_rules, max_conds Maximum number of rules (4) and conditions per side (4)
time, weekday Device time ("HH:MM") and weekday (1 = Monday); null while the clock is not set
rules[].commanded Last own command of the rule: on, off or unknown
rules[].actual, actual_s Device state (on, off, unknown) and how many seconds ago it was last read or set
rules[].gen, model Detected Shelly: generation and model (0 and empty for tasmota and url)
rules[].state_s Seconds in the current state
rules[].volume_since m³ since the last change
rules[].on, rules[].off met: side currently met. Per condition in conds: met, wait_s (seconds until it holds; -1 = not foreseeable) and value (current reading for value conditions, otherwise null)
rules[].last_action Last switching action: cmd, auto (true = by the rule) and s (seconds ago)
rules[].error Last error: code (unreachable, auth, not_shelly, not_tasmota, bad_reply) and s
rules[].manual Result of /switch/test: ok and s, or pending

Switching rule error messages

The device rejects an invalid rule with 400, e.g. {"success":false,"error":"switch.rules[1]: at most 4 conditions per side"}. The number in square brackets is the rule's number, counted from 0.

Message Cause
switch.rules: at most 4 rules More than 4 rules
rule needs at least one condition Both sides empty
match must be all or any match is neither all nor any
at most 4 conditions per side More than 4 conditions on one side
condition type must be value, time, window, state or volume Unknown type
source must be export, import, flow or draw Unknown source
source not available on this device export or import on a gas or water device
condition op must be above or below op missing or wrong
threshold must be a number value missing or not a number
delay out of range (0-86400 s) delay negative or longer than 24 hours
time must be HH:MM at, from or to not in the format "HH:MM"
window start and end must differ from and to are equal
days must be a list of weekdays 1-7 days is not a list or contains something other than 1–7
at least one weekday days is empty
duration out of range (1-604800 s) for missing, 0 or longer than 7 days
volume out of range volume with 0 or less
switching on needs target.on_url On side with conditions but empty on_url (likewise switching off needs target.off_url)
target needs on_url or off_url Own URL without addresses
target.host must be an IP address or host name host empty, too long or with http://, a path or spaces
target.channel out of range (0-3) or (0-7) Output outside 0–3 (Shelly) or 0–7 (Tasmota)
name too long (max 31) Name too long

Several areas at once

Everything in one request saves waiting (one change per second) and is atomic: if a value is invalid, nothing is saved.

curl -s -X POST $WW/api/v1/settings \
  -H "Content-Type: application/json" \
  -d '{
        "device_name": "Basement",
        "ledEnable": false,
        "timezone": "Europe/Berlin",
        "mqtt": { "enable": true, "host": "192.168.178.10", "port": 1883, "use_tls": false },
        "modbus": { "enable": true }
      }'

Atomic applies to the checks

The request is rejected before saving for: an unknown top-level field, an SSID that is too long, invalid values under gw, switch and an invalid time zone. Other values (e.g. a port number out of range) are not reported as errors but ignored or clamped.

From Python

import requests

WW = "http://wattwaechter-XXXXXXXXXXXX.local"
HEADERS = {}  # with API protection: {"Authorization": "Bearer YOUR_WRITE_TOKEN"}

r = requests.post(f"{WW}/api/v1/settings",
                  json={"mqtt": {"sendInterval": 30}},
                  headers=HEADERS, timeout=10)
if r.status_code == 429:
    # too fast in a row: wait briefly and send again
    ...
r.raise_for_status()
print(requests.get(f"{WW}/api/v1/settings", headers=HEADERS, timeout=10).json()["mqtt"])

Error messages

Status Response (example) Cause
400 {"error":"Missing JSON body"} No body, or Content-Type is not application/json
400 {"error":"Invalid JSON"} Not valid JSON (e.g. a trailing comma)
400 {"success":false,"error":"Unknown field: ledEnabled"} Typo in a top-level field name
400 {"success":false,"error":"Modifying reboot counters is forbidden"} rebootCounter, rebootsTotal, rebootsAll are read-only
400 {"success":false,"error":"SSID too long (max 32 chars): wifi.primary.ssid"} SSID longer than 32 characters
400 {"error":"Invalid timezone"} Time zone not in /api/v1/system/timezones
400 {"success":false,"error":"gw.pulseVolume out of range (0.0001-1 m³)"} Value out of the allowed range
400 {"success":false,"error":"switch.rules[0]: at most 4 conditions per side"} Invalid switching rule (number in square brackets), see Switching rule error messages
401 API protection on, token missing or wrong
403 {"success":false,"error":"To enable API authentication, you must provide the WRITE token. …"} Turning on API protection without the WRITE token
403 {"error":"Write access from another web page needs the WRITE token"} Browser request from another web page without the WRITE token, see Writing from other web pages
413 {"error":"Request body too large. Max 2KB allowed."} Request too large (from firmware 1.3: 8 KB)
429 {"error":"Too many settings updates. Wait 1 second."} Less than 1 second since the last change (Retry-After: 1)
429 {"error":"Settings update in progress. Try again."} Another change is in progress

Interactive API Documentation

The full API specification in OpenAPI format:

Note

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