Skip to content
ChannelWatch

Per-DVR Health

Each configured DVR has a health endpoint that returns a JSON snapshot of its current monitoring state. This is useful for scripting, dashboards, and troubleshooting one DVR without reading the aggregate /api/health response.

Health endpoint

Section titled “Health endpoint”
GET /api/v1/dvrs/{dvr_id}/health

Use a DVR ID from GET /api/v1/dvrs.

Both routes require app authentication when it is configured: a secure-login session or the legacy X-API-Key path. See REST API for request headers and permission boundaries. Avoid publishing a raw response; it includes DVR names and addresses.

Response shape

Section titled “Response shape”

The current backend response model is DvrHealthResponse, with these fields:

Field Type Description
dvr_id string DVR identifier
dvr_name string Configured DVR name
host string DVR host
port number DVR port
connected boolean Whether the backend could reach the DVR during the current health read
version string or null DVR version from /status
version_compatible boolean or null Tested-range compatibility result
version_warning string or null Compatibility warning text when applicable
disk_status string Disk summary from the backend helper (normal, warning, critical, or unknown)
disk_free_gb number or null Free DVR storage in GiB
disk_total_gb number or null Total DVR storage in GiB
last_checked string ISO timestamp for this health response
last_event_at string or null Last observed event timestamp when available
last_freshness_at string or null Timestamp of the latest freshness snapshot
last_freshness_source string or null Freshness source label from the monitoring snapshot
freshness_age_seconds number or null Current freshness age
freshness_status string Freshness state from the monitoring summary
monitoring_status string Overall monitoring state for this DVR
monitoring_ready boolean Whether this DVR is currently considered ready by the monitoring summary
monitoring_reason string or null Reason text when the DVR is degraded or missing
session_state_size number or null Size of the current session-state snapshot
recent_alert_rate number or null Recent alert count derived from the activity database window

Example response:

{
  "dvr_id": "dvr_abc12345",
  "dvr_name": "Living Room",
  "host": "192.168.1.100",
  "port": 8089,
  "connected": true,
  "version": "2025.06.15",
  "version_compatible": true,
  "version_warning": null,
  "disk_status": "normal",
  "disk_free_gb": 1160.0,
  "disk_total_gb": 2000.0,
  "last_checked": "2026-04-21T07:05:00+00:00",
  "last_event_at": "2026-04-21T06:59:45+00:00",
  "last_freshness_at": "2026-04-21T07:05:00+00:00",
  "last_freshness_source": "watchdog",
  "freshness_age_seconds": 15.0,
  "freshness_status": "fresh",
  "monitoring_status": "healthy",
  "monitoring_ready": true,
  "monitoring_reason": null,
  "session_state_size": 3,
  "recent_alert_rate": 4.0
}

Status-code behavior

Section titled “Status-code behavior”

The current route returns 404 when the DVR ID does not exist. For an existing DVR, it returns the DvrHealthResponse JSON shape described above.

Degraded monitoring state is represented in monitoring_status, monitoring_ready, monitoring_reason, and the freshness fields. Read those values even when the request returns HTTP 200.

How this relates to readiness

Section titled “How this relates to readiness”

The endpoint combines two data sources:

  1. live per-request DVR reads such as /status and /dvr
  2. the monitoring summary snapshot exposed in detail by authenticated /api/health and reduced to aggregate status by /healthz/ready

That is why the response includes both immediate fields like connected and snapshot-driven fields like freshness_status, monitoring_status, and monitoring_ready.

Threshold wording

Section titled “Threshold wording”

The current per-DVR health response does not expose a configurable staleness threshold field. The auth-exempt /healthz/ready probe also omits thresholds and per-DVR details; use authenticated diagnostics for operational context.

Section titled “Related pages”