API reference

CronWarden has three HTTP surfaces: check-in endpoints your jobs call, the monitors API for managing monitors as code, and read-only metrics and badge endpoints.

Check-in endpoints

No API key — authentication is the unguessable ping key in the URL. Both GET and POST work.

Method	Endpoint	Purpose
GET/POST	`/ping/<key>`	Successful finish.
GET/POST	`/ping/<key>/start`	Run started.
GET/POST	`/ping/<key>/fail`	Run failed.

Report a value on the success check-in as ?value=<number>, or as { "value": <number> } in a JSON POST body. A non-numeric value is treated as absent. See Reporting a value.

Monitors API

Requires an Authorization: Bearer cw_... API key. Bodies and responses are JSON.

Method	Endpoint	Purpose
GET	`/api/v1/monitors/<slug>`	Fetch a monitor.
PUT	`/api/v1/monitors/<slug>`	Create or update (upsert) a monitor.
DELETE	`/api/v1/monitors/<slug>`	Delete a monitor.

See Monitors API for the request body and field reference.

Metrics

Method	Endpoint	Purpose
GET	`/api/metrics`	Prometheus-format gauges for the team, Bearer key required.

See Crontab import & Prometheus metrics.

Badges

No authentication — the badge key is a separate, read-only identifier.

Method	Endpoint	Purpose
GET	`/badge/<key>.svg` \| `.json`	Single monitor status.
GET	`/badge/tag/<key>.svg` \| `.json`	Worst status across a tag.

Status codes

Code	Meaning
`200`	Success (fetch or update).
`201`	Monitor created.
`400`	Invalid request body or schedule.
`401`	Missing, malformed, unknown, or revoked API key.
`404`	No monitor at that slug in your team.