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.

ChannelWatch diagnostics screen showing health summary, multi-DVR status, debug bundle download, log tools, and alert tests
Diagnostics And Debug BundleUse the Diagnostics view alongside the per-DVR health endpoint when you need to compare API output with visible DVR status. Captured from ChannelWatch v0.9.15 with safe demo data.

Health endpoint

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

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

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.

This page does not assume a special per-DVR 503 stale contract. Degraded monitoring state is represented in the JSON fields such as monitoring_status, monitoring_ready, monitoring_reason, and the freshness fields.

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 used by /api/health and /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 per-DVR configurable staleness threshold field. If you need the aggregate threshold value used by the readiness summary, inspect /healthz/ready, which includes stale_threshold_seconds at the aggregate level.

Section titled “Related pages”