Internet Watchdog — REST API Reference

PF-WATCHDOG-001 product endpoints.
All paths are relative to http://<device-ip>/api/v1.

For platform base endpoints (device info, relay, power, telemetry, config, OTA), see the Platform REST API Reference.

Overview

The Internet Watchdog exposes 7 product-specific REST endpoints under the /watchdog/ namespace. The platform prepends /api/v1 automatically, so the product declares paths like /watchdog/status and they become accessible at /api/v1/watchdog/status.

Base URL

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

The device runs an HTTP server on port 80. No authentication. LAN-only.

Endpoints at a Glance

GET /watchdog/status

Returns the full current state of the watchdog — state machine state, connectivity, cumulative stats, and timestamps.

Response 200 OK

{
  "state": "monitoring",
  "internet_up": true,
  "enabled": true,
  "relay": true,
  "reboot_count": 0,
  "total_reboots": 3,
  "total_outages": 3,
  "uptime_percent": 99.7,
  "consecutive_fails": 0,
  "fail_threshold": 3,
  "scheduled_reboot": null,
  "last_check": "2026-02-11T15:30:00Z",
  "last_outage": "2026-02-10T08:15:00Z",
  "last_reboot": "2026-02-10T08:17:30Z"
}

Fields

State values

Notes

• Timestamps use ISO 8601 format: "2026-02-11T15:30:00Z". A null value means the event hasn't occurred since boot (or the system clock hasn't synced — epoch before 2025-01-01).
• uptime_percent reflects cumulative monitoring time, not just the current session.

GET /watchdog/config

Returns all current configuration parameters with their active values.

Response 200 OK

{
  "enabled": true,
  "ping_interval_s": 60,
  "fail_threshold": 3,
  "grace_before_reboot_s": 120,
  "power_off_duration_s": 30,
  "post_reboot_grace_s": 300,
  "max_retries": 3,
  "retry_cooldown_min": 30,
  "scheduled_reboot": null,
  "ping_targets": ["8.8.8.8", "1.1.1.1", "208.67.222.222"]
}

Fields

POST /watchdog/config

Update configuration. Accepts a partial JSON body — only fields present in the request are changed. Updated values are persisted to NVS immediately and take effect on the next monitoring cycle.

Returns the full updated config on success (same format as GET /watchdog/config).

Request body

JSON object with any subset of the config fields. Maximum body size: 512 bytes.

Example — change ping interval and add a scheduled reboot:

{
  "ping_interval_s": 120,
  "scheduled_reboot": "04:00"
}

Example — update ping targets:

{
  "ping_targets": ["8.8.8.8", "1.1.1.1"]
}

Example — reset ping targets to defaults:

{
  "ping_targets": null
}

Example — disable scheduled reboot:

{
  "scheduled_reboot": null
}

Validation rules

Response 200 OK

Full config object (same as GET /watchdog/config).

Error responses

Side effects

• Changing enabled to true: pushes enabled event to history, enters monitoring state, resets consecutive_fails and reboot_count.
• Changing enabled to false: pushes disabled event to history, enters disabled state, turns relay on (ensures router stays powered).
• All changes: publishes updated state via MQTT.

POST /watchdog/reboot

Trigger a manual router power-cycle. The watchdog opens the relay (power off), waits power_off_duration_s, closes the relay (power on), then enters post_reboot_grace state.

Request body

None (ignored if present).

Response 200 OK

{
  "status": "rebooting"
}

Error responses

Side effects

• Pushes manual_reboot event to history.
• Sets last_reboot timestamp.
• Relay opens immediately (router loses power).

GET /watchdog/history

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

Response 200 OK

[
  {
    "event": "device_online",
    "timestamp_ms": 1500,
    "reboot_count": 0
  },
  {
    "event": "outage_detected",
    "timestamp_ms": 185000,
    "reboot_count": 0
  },
  {
    "event": "reboot_started",
    "timestamp_ms": 305000,
    "reboot_count": 1
  }
]

Fields (per event)

Event types

Notes

• The ring buffer holds a maximum of 16 events. When full, the oldest event is overwritten.
• timestamp_ms is relative to device boot, not wall-clock time. Use last_check/last_outage/last_reboot in /watchdog/status for absolute timestamps.
• Events are not persisted across reboots. The buffer starts empty with a device_online event at each boot.

GET /watchdog/ping

Force an immediate connectivity check against all configured ping targets. Returns per-target results.

Response 200 OK

{
  "internet_up": true,
  "targets": [
    { "ip": "8.8.8.8", "success": true, "rtt_ms": 12 },
    { "ip": "1.1.1.1", "success": true, "rtt_ms": 8 },
    { "ip": "208.67.222.222", "success": false, "rtt_ms": 0 }
  ]
}

Fields

Side effects

• Updates internet_up state.
• Updates last_check timestamp.
• Does not affect consecutive_fails or trigger state transitions — this is a diagnostic check, not a monitoring cycle.

POST /watchdog/stats/reset

Reset all cumulative statistics to zero. This clears lifetime counters and timestamps.

Request body

None (ignored if present).

Response 200 OK

{
  "status": "stats_reset"
}

What gets reset

Side effects

• Persists zeroed stats to NVS.
• Publishes updated state via MQTT.

Common Notes

Content types

• All responses are application/json.
• POST request bodies must be application/json (or no Content-Type for empty-body endpoints like /watchdog/reboot and /watchdog/stats/reset).
• Error responses from validation are text/plain.

Error format

Validation errors return HTTP 400 with a plain-text body describing the problem. There is no structured error JSON — the body is the error message string.

Concurrency

The device is single-threaded for HTTP request handling. Requests are processed sequentially. Long-running operations (like /watchdog/ping, which performs ICMP pings) block the HTTP server until complete.

Timestamps

The device obtains wall-clock time via SNTP after WiFi connects. Timestamp fields return null if the system clock hasn't been set yet (epoch before 2025-01-01).