Skip to content
ChannelWatch

Health & Readiness Probes

ChannelWatch exposes four HTTP health endpoints. Three are probe-oriented endpoints under /healthz/*, and one is a broader service summary at /api/health.

Health endpoints

Section titled “Health endpoints”
EndpointPurposeHealthy status
/api/healthGeneral monitoring summary200 OK
/healthz/liveProcess is alive and responding200 OK
/healthz/readyMonitoring readiness summary for enabled DVRs200 OK
/healthz/startupStartup completion gate200 OK

All four endpoints return JSON payloads. They are auth-exempt in the backend and do not require the shared API key.

General health check (/api/health)

Section titled “General health check (/api/health)”

GET /api/health returns a JSON summary built from the monitoring-health snapshot:

{
  "status": "ok",
  "ready": true,
  "dvrs": [
    {
      "id": "dvr_abc12345",
      "name": "Living Room",
      "monitoring_status": "healthy",
      "reason": null
    }
  ]
}

If the aggregate monitoring state is degraded, the same payload shape is returned with status: "degraded" and HTTP 503.

Kubernetes probe endpoints

Section titled “Kubernetes probe endpoints”

Liveness probe (/healthz/live)

Section titled “Liveness probe (/healthz/live)”

The liveness probe checks whether the web process can respond at all. The current implementation always returns a simple JSON success body while the process is alive:

{
  "status": "ok"
}

Use this probe to let Kubernetes restart a wedged process. It does not evaluate DVR connectivity or freshness.

Readiness probe (/healthz/ready)

Section titled “Readiness probe (/healthz/ready)”

The readiness probe returns a JSON monitoring summary. On success it returns 200 with a payload like:

{
  "status": "ready",
  "ready": true,
  "dvrs": [
    {
      "id": "dvr_abc12345",
      "name": "Living Room",
      "monitoring_status": "healthy",
      "freshness_status": "fresh",
      "connected": true,
      "reason": null,
      "last_freshness_at": "2026-04-21T07:00:00+00:00",
      "freshness_age_seconds": 15.0
    }
  ],
  "stale_threshold_seconds": 300,
  "tested_version_range": {
    "min": "2024.01.01",
    "max": "2027.01.01"
  }
}

If the aggregate monitoring summary is not ready, the same JSON shape is returned with status: "degraded" and HTTP 503.

The important distinction is that readiness is based on the watchdog-style monitoring summary, not just raw process liveness.

Startup probe (/healthz/startup)

Section titled “Startup probe (/healthz/startup)”

The startup probe reports whether the backend has completed startup initialization:

Healthy:

{
  "status": "ready"
}

Not ready yet:

{
  "status": "not_ready"
}

The backend returns HTTP 503 until startup completes.

What drives readiness

Section titled “What drives readiness”

The /api/health and /healthz/ready payloads are both built from the monitoring health summary used by the backend watchdog snapshot. In practice that means readiness reflects the current per-DVR monitoring state, including connection and freshness information surfaced through fields such as:

  • monitoring_status
  • freshness_status
  • connected
  • reason
  • last_freshness_at
  • freshness_age_seconds

This is broader than a single last_event_at check. The backend exposes both event timing and freshness/watchdog summary fields, and the readiness endpoint is the aggregate view.

Example Kubernetes config

Section titled “Example Kubernetes config”
livenessProbe:
  httpGet:
    path: /healthz/live
    port: 8501
  initialDelaySeconds: 0
  periodSeconds: 30
  timeoutSeconds: 3
  failureThreshold: 3


readinessProbe:
  httpGet:
    path: /healthz/ready
    port: 8501
  initialDelaySeconds: 0
  periodSeconds: 10
  timeoutSeconds: 3
  failureThreshold: 3


startupProbe:
  httpGet:
    path: /healthz/startup
    port: 8501
  initialDelaySeconds: 0
  periodSeconds: 5
  timeoutSeconds: 3
  failureThreshold: 30
Section titled “Related pages”