Release candidate: this page describes 410fbfb, which is separate from main. See version and availability.

HTTP API and dashboard

The default server is http://localhost:8060. The dashboard and API inspect state; they do not create monitors, change configuration, or trigger recovery commands.

Authentication

When a token is configured, use HTTP Bearer authentication for API requests. Browser login uses username cpra and the token as the password. The authentication middleware also protects health, readiness, and metrics endpoints.

For remote requests, use an HTTPS reverse proxy and cpractl --token-file where possible. A non-loopback listener requires a token. See deployment.

Endpoints

Method	Path	Result
GET	/api/v1/healthz	Process liveness.
GET	/api/v1/readyz	Controller admission and storage readiness; projection freshness reported separately.
GET	/api/v1/overview	Fleet counts, status breakdown, and index-cap indicator.
GET	/api/v1/monitors	Filtered, paginated active-monitor details.
GET	/api/v1/monitors/{id}	One monitor by numeric ID, with additive stable monitor_id.
GET	/api/v1/incidents	Current incident information.
GET	/api/v1/systems	Controller-system telemetry.
GET	/api/v1/queues	Current queue telemetry.
GET	/api/v1/queues/history	In-memory queue history.
GET	/api/v1/pools	Worker-pool capacity, observations, and sizing state.
GET	/api/v1/pools/history	In-memory pool history.
GET	/api/v1/config	Public runtime settings.
GET	/metrics	Prometheus text exposition.

Monitor filtering

curl 'http://localhost:8060/api/v1/monitors?status=down&page=1&size=50'
curl 'http://localhost:8060/api/v1/monitors?type=http&q=example'

These examples assume the default local listener without token authentication.

Parameter	Meaning
page	One-based page number; defaults to 1.
size	Page size; defaults to 50 and is capped at 500.
status	Match the monitor status.
type	Match the pulse type.
code	Match the pending notification color.
q	Case-insensitive substring of the monitor name.

Readiness and unavailable data

Liveness returns process health, not target health. Readiness requires initialized admission, controller progress within 30 seconds and available storage. An explicitly empty configuration can be ready. The response reports dashboard projection_fresh separately; a stale projection or unhealthy target does not itself fail process readiness.

The durable runtime maintains an incremental monitor index. Monitor and incident responses are paginated and capped at 500 rows; filtering runs on the HTTP goroutine. This does not constitute a million-monitor performance claim.

A fresh process may also lack a snapshot. Treat unavailable responses as unavailable data, not as an empty healthy fleet.

Dashboard semantics

The dashboard offers Overview, Monitors, Alerts, System, Settings, and monitor detail views. Views refresh periodically from the incremental index.

The healthy-sample percentage uses committed cumulative check counters. It is not an external SLA measurement. Incident, recovery and notification events are retained for 30 days; raw check records are not retained. Pool and queue histories are separate, bounded, in-memory series.

CLI reference · Response types in source

Durable state, history and SLOs

Method	Route	Contract
GET	/api/v1/state	Redacted storage health, process and storage usage. Optional monitor_id returns its revision and action states.
GET	/api/v1/history?monitor_id=ID&limit=100&cursor=TOKEN	Stable monitor event ordering, 100 default and 500 maximum events, 30-day retention and opaque next cursor.
GET	/api/v1/slo	Five-minute p50/p95/p99, exact threshold attainment, timeouts, missed/pending/overdue checks and recovery coverage.

These routes use the existing bearer/Basic authentication and reject mutations. Unavailable history returns 503. Numeric monitor routes remain compatible; monitor_id is the stable identity used by history and recovery state. History cursors preserve the initial upper committed position during pagination. See durability and SLO definitions.

The SDK guide documents the draft v2 client contract. Neither this candidate nor current main implements those write routes.