REST API (/api/v1/)

ChannelWatch v1.0 ships a versioned REST API at /api/v1/. All new integrations should target this path. The original /api/ routes remain as legacy aliases through the v1.x lifecycle and emit a deprecation header on every response.

Versioning policy

ChannelWatch follows Semantic Versioning. The /api/v1/ prefix is stable for the entire v1.x series: no breaking changes, only additive fields. A v2.0 release may introduce a /api/v2/ prefix with breaking changes, but v1.x will continue to receive the legacy aliases until a documented deprecation window closes.

Authentication

When RBAC is disabled (the default), all API endpoints are accessible without credentials. When RBAC is enabled, requests must include an API key in the Authorization header:

Authorization: Bearer <your-api-key>

API keys are created in Settings > Security > API Keys. Each key can be scoped to a role (admin, operator, or viewer). See the API Keys page for setup details.

DVR endpoints

These endpoints return data scoped to a specific DVR server. Replace <id> with the DVR’s canonical identifier, which you can find in Settings > DVR Servers or from GET /api/v1/dvrs.

List all DVRs

GET /api/v1/dvrs

Returns an array of all configured DVR servers with their connection status.

Example response:

[
  {
    "id": "dvr_abc123",
    "display_name": "Living Room",
    "host": "192.168.1.100",
    "port": 8089,
    "enabled": true,
    "status": "connected"
  }
]

DVR details

GET /api/v1/dvrs/<id>

Returns full details for a single DVR, including connection metadata and the last-seen timestamp.

Per-DVR stream details

GET /api/v1/dvrs/<id>/streams

Returns the active streams on a specific DVR. Each stream object includes the channel, device, and session identifiers scoped to that DVR.

Per-DVR system info

GET /api/v1/dvrs/<id>/system-info

Returns system-level information from the Channels DVR server: version, storage paths, and disk usage. This replaces the aggregate /api/system-info endpoint for multi-DVR setups.

Per-DVR activity history

GET /api/v1/dvrs/<id>/activity-history

Returns the recent alert and event history for a specific DVR. Useful for auditing which events triggered notifications on a given server.

Per-DVR upcoming recordings

GET /api/v1/dvrs/<id>/recordings/upcoming

Returns the scheduled recordings queue for a specific DVR.

Per-DVR health

GET /api/v1/dvrs/<id>/health

Returns a health summary for a specific DVR. This endpoint is designed for K8s readiness probes and ops dashboards.

Example response:

{
  "dvr_id": "dvr_abc123",
  "connectivity": "ok",
  "last_event_at": "2026-04-19T14:32:00Z",
  "session_state_size": 3,
  "disk_status": "ok",
  "recent_alert_rate": 0.4
}

Discovery endpoint

POST /api/v1/discovery/scan

Triggers a 3-second mDNS scan for Channels DVR servers on the local network. Returns any discovered servers with their host and port. Only works when ChannelWatch is running in host network mode; bridge mode returns an empty result with a bridge_mode flag.

Auth endpoints (RBAC only)

These endpoints are only active when RBAC is enabled (CW_RBAC_ENABLED=true).

POST /api/v1/auth/login
POST /api/v1/auth/logout
GET  /api/v1/auth/whoami

/api/v1/auth/whoami returns the current session’s role and username. Useful for confirming which credentials are active in an automated script.

Legacy aliases

The original /api/ routes from v0.7 are preserved as aliases through the v1.x lifecycle. Every response from a legacy route includes:

X-Deprecated-API: Use /api/v1/

Legacy routes return equivalent data to their v1 counterparts. They will be removed in a future major version. Migrate integrations to /api/v1/ at your earliest convenience.

Legacy route	v1 equivalent
`/api/streams/details`	`/api/v1/dvrs/<id>/streams`
`/api/system-info`	`/api/v1/dvrs/<id>/system-info`

Security modes — enable RBAC and restrict API access
API Keys — create and manage API keys
Per-DVR health — health endpoint details for ops and K8s
Prometheus metrics — per-DVR labeled metrics