REST API Reference

PF-SUMP-001 product endpoints  |  v1.1  |  Updated: 2026-02-27

All paths are relative to http://<device-ip>/api/v1. LAN-only. No authentication.

GET /sump/status

Returns the full current state of the sump pump monitor — run state, active alerts, protection mode, lockout info, learning progress, and cumulative stats.

Response 200 OK

{
  "pump_running": false,
  "current_run_s": 0,
  "current_power_w": 0.0,
  "alerts": [],
  "protection_mode": "active",
  "protection_auto_disabled": false,
  "lockout_active": false,
  "lockout_remaining_s": 0,
  "lockout_retries_used": 0,
  "lockout_alert": null,
  "run_count_total": 87,
  "runs_last_24h": 7,
  "total_runtime_s": 2958,
  "last_outage_s": 0,
  "last_run_end_ms": 1708300000000,
  "last_run_dur_s": 34,
  "last_run_avg_w": 762.4,
  "last_run_peak_w": 812.0,
  "idle_w": 0.0,
  "active_w": 780.0,
  "on_threshold_w": 234.0,
  "inter_run_gap_mean": 21600.0,
  "alert_enable_mask": 7,
  "relay_cut_mask": 1,
  "inactivity_alert_min": 7200,
  "anomaly_lockout_min": 10,
  "lockout_max_retries": 3,
  "rhythm_hex": "000000010001000200010000...",
  "rhythm_head": 142,
  "rhythm_last_bin_ms": 1708300200000
}

Fields

Protection mode values

Alert key values

GET /sump/last-run

Returns detailed stats and power waveform for the last completed pump cycle.

Response 200 OK

{
  "start_ms": 1708299965000,
  "end_ms": 1708300000000,
  "dur_s": 34,
  "avg_w": 762.4,
  "peak_w": 812.0,
  "std_w": 18.7,
  "sample_count": 34,
  "samples": [210.5, 810.2, 795.0, 780.1, 770.3, 762.8, ...]
}

Fields

samples[] captures the first 60 seconds. For shorter runs, this is the complete waveform. Data is NVS-persisted — survives reboot, overwritten by the next completed cycle.

GET /sump/config

Returns all current configuration parameters.

Response 200 OK

{
  "inactivity_alert_min": 7200,
  "anomaly_lockout_min": 10,
  "lockout_max_retries": 3,
  "alert_enable_mask": 7,
  "relay_cut_mask": 1
}

Fields

POST /sump/config

Update configuration. Accepts a partial JSON body — only fields present are changed. Persisted to NVS immediately.

Request examples

// Change lockout timing
{ "anomaly_lockout_min": 15, "lockout_max_retries": 5 }

// Enable high-power relay cut (bits 0+1)
{ "relay_cut_mask": 3 }

// Enable frequent cycling alert (bits 0–3)
{ "alert_enable_mask": 15 }

// Set inactivity alert to 3 days
{ "inactivity_alert_min": 4320 }

Validation rules

Response 200 OK

Full config object (same as GET).

Error responses

GET /sump/history

Returns the alert event ring buffer — up to 32 most recent events, ordered oldest first.

Response 200 OK

[
  {
    "event": "alert_fired",
    "alert": "power_anomaly_low",
    "timestamp_ms": 1738886400000,
    "run_dur_s": 12,
    "power_w": 520.0,
    "relay_cut": true
  },
  {
    "event": "alert_cleared",
    "alert": "power_anomaly_low",
    "timestamp_ms": 1738886420000,
    "duration_s": 20
  },
  {
    "event": "power_outage",
    "timestamp_ms": 1738800000000,
    "outage_s": 3600
  },
  {
    "event": "mode_change",
    "timestamp_ms": 1739145600000,
    "from": "learning",
    "to": "active"
  },
  {
    "event": "device_boot",
    "timestamp_ms": 1739318400000,
    "reason": "power_on"
  }
]

Event types

Normal pump runs do NOT appear in this ring. Pump activity is captured by the rhythm ring in /sump/status.

POST /sump/lockout/reset

Clear any active lockout, re-enable any system-disabled protection flags, and reset the retry counter.

Response 200 OK

{ "status": "lockout_reset" }

What gets reset

POST /sump/stats/reset

Reset all cumulative statistics, clear alert history, clear rhythm ring, and reset all learned baselines. Device re-enters learning mode.

Response 200 OK

{ "status": "stats_reset" }

What gets reset

GET /sump/learn

Returns learning / baseline convergence data: Welford CV values, per-metric readiness flags, inter-run gap stats, and the bimodal power baselines.

Response 200 OK

{
  "mode": "learning",
  "cycle_count": 9,
  "wattage_mean": 762.4,
  "wattage_cv": 8.2,
  "wattage_ready": true,
  "runtime_mean": 34.0,
  "runtime_cv": 46.1,
  "runtime_ready": false,
  "cycle_rate_mean": 7.2,
  "cycle_rate_cv": 45.0,
  "cycle_rate_ready": false,
  "inter_run_gap_mean": 420.0,
  "inter_run_gap_cv": 32.5,
  "inter_run_gap_ready": true,
  "idle_w": 0.0,
  "active_w": 780.0
}

Fields

Readiness thresholds

Transitions learning → active when both wattage_ready and runtime_ready are true and ≥ 5 cycles recorded.

Common Notes

• All responses are application/json.
• POST request bodies must be application/json.
• Error responses from validation are text/plain.
• The device is single-threaded for HTTP — requests are processed sequentially.
• timestamp_ms fields are wall-clock UTC epoch milliseconds. The device obtains time via SNTP after WiFi connects.