PumpFuse Platform — REST API Reference

Platform-level REST endpoints available on every PumpFuse product.
These cover device identity, configuration, relay control, power monitoring, telemetry, and OTA firmware updates.

For product-specific REST endpoints, see the product's own REST API Reference (e.g., Watchdog REST API).

Base URL

http://<device-ip>/api/v1

All endpoints accept and return application/json unless otherwise noted. No authentication.

Endpoints

GET /api/v1/info

Returns device identity. Available in both normal and recovery modes.

Response

{
  "product": "pf-watchdog",
  "firmware": "1.0.0",
  "mac": "AA:BB:CC:DD:EE:FF",
  "ip": "192.168.40.114",
  "uptime": 3600
}

GET /api/v1/status

Returns a full runtime snapshot including connectivity, relay, power, and telemetry state.

Response

{
  "product": "pf-watchdog",
  "firmware": "1.0.0",
  "uptime": 3600,
  "ip": "192.168.40.114",
  "wifi_connected": true,
  "mqtt_connected": true,
  "relay": true,
  "power_w_last": 12.345,
  "power_sample_ts_ms": 1739260200000,
  "telemetry_active": true,
  "telemetry_interval_s": 5
}

GET /api/v1/config

Returns current device configuration.

Response

{
  "device_name": "test-board",
  "wifi_ssid": "MyNetwork",
  "mqtt_broker": "192.168.40.164",
  "mqtt_port": 1883,
  "mqtt_topic": "pumpfuse/test-board",
  "mqtt_user": "mqtt",
  "mqtt_pass": "secret123"
}

POST /api/v1/config

Update device configuration. All fields are optional — include only the fields you want to change. Changes are persisted to NVS immediately.

Request

{
  "device_name": "living-room",
  "mqtt_broker": "10.0.0.5",
  "mqtt_port": 1883,
  "mqtt_topic": "pumpfuse/living-room",
  "mqtt_user": "mqtt",
  "mqtt_pass": "newpass"
}

Response: Updated config JSON (same schema as GET).

Errors

Side effects:

• Config is persisted to NVS. Device uses new MQTT settings on next reconnect or reboot.
• If MQTT save fails after device_name was updated, device_name is rolled back.

GET /api/v1/relay

Returns current relay state.

Response

{
  "relay": true
}

POST /api/v1/relay

Set relay state.

Request

{
  "relay": false
}

Response: Same schema as GET.

Errors

Side effects:

• Physically toggles the relay.
• Updates runtime state (reflected in /api/v1/status, MQTT relay/state, etc.).

GET /api/v1/power

Returns the most recent power reading.

Response

{
  "power_w": 12.345,
  "ts_ms": 1739260200000
}

GET /api/v1/telemetry

Returns current telemetry settings.

Response

{
  "active": true,
  "interval_s": 5
}

POST /api/v1/telemetry

Update telemetry settings. Both fields are optional.

Request

{
  "active": true,
  "interval_s": 10
}

Response: Updated telemetry JSON (same schema as GET).

Errors

Side effects:

• Telemetry state persisted to runtime state.
• Immediately reflected in MQTT telemetry/state and status topics.

POST /api/v1/ota

Push a firmware binary for over-the-air update.

Request

• Content-Type: application/octet-stream
• Body: raw firmware binary

curl -s http://192.168.40.114/api/v1/ota \
  -X POST \
  -H "Content-Type: application/octet-stream" \
  --data-binary @build/pf-watchdog_1.0.0.bin

Response: "OK" (plain text), then the device reboots.

Side effects:

• Firmware is written to the inactive OTA partition.
• Device reboots into the new firmware immediately after the write completes.
• If the binary is invalid or too large, the OTA write fails and the device continues running current firmware.

Recovery Mode

When the device enters recovery mode (failed boot or forced recovery), it starts a WiFi access point and exposes a minimal set of endpoints.

Access Point: SSID ppp (hidden), IP 192.168.4.1, open authentication.

Recovery mode is designed for the ota-flash tool to discover and reflash unresponsive devices.

Notes

Content-Type

All JSON endpoints respond with Content-Type: application/json. The OTA endpoint expects application/octet-stream.

Error format

Error responses use plain text bodies (not JSON). The HTTP status code indicates the error class (400 for client errors, 500 for server errors), and the body contains a brief machine-readable error identifier.

Rate limiting

No rate limiting. The device processes requests serially on the HTTP server thread.

WiFi SSID

The wifi_ssid field in config is read-only via REST. WiFi credentials can only be set via BLE provisioning.