Monitors API

The monitors API lets you manage monitors as code. It's a small, declarative surface keyed by a slug you choose: you describe the monitor you want at a slug, and CronWarden creates it or updates it to match. Running the same request twice is safe.

All requests need an API key as a Bearer token.

Upsert a monitor

curl -X PUT https://cronwarden.com/api/v1/monitors/nightly-backup \
  -H "Authorization: Bearer cw_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Nightly database backup",
    "scheduleType": "cron",
    "cronExpression": "0 3 * * *",
    "timezone": "America/New_York",
    "gracePeriodMinutes": 30,
    "minDurationSeconds": 10,
    "assertions": { "valueMin": 1 },
    "tags": ["production", "backups"],
    "integrations": ["Ops Slack", "PagerDuty"]
  }'

A new slug returns 201 Created; an existing one returns 200 OK with the updated monitor. The response body is the monitor's full current configuration.

Body fields

Field	Notes
`name`	Display name.
`scheduleType`	`"cron"` or `"interval"`.
`cronExpression`	Required when `scheduleType` is `"cron"`.
`intervalSeconds`	Required when `scheduleType` is `"interval"`.
`timezone`	IANA name; defaults to `"UTC"`.
`gracePeriodMinutes`	How long a check-in may be late before the monitor goes down and pages. While it runs the monitor shows "late" without notifying. Omit to let CronWarden pick.
`notifyOnLate`	Also notify the moment the monitor first goes late (early warning). Default `false`.
`newMonitorPolicy`	`wait_for_first_ping` (default) keeps a never-pinged monitor silent; `alert_on_first_miss` arms the schedule at creation. Inert once the monitor has pinged.
`minDurationSeconds`	Flag successful runs faster than this.
`durationDriftPct`	Flag runs that drift past this percent from their average.
`assertions`	`{ "valueMin", "valueMax", "deltaPct" }` — any subset; each is optional.
`tags`	Array of tag names. Tags that don't exist yet are created for you.
`integrations`	Array of integration names. These must already exist — connect them in the dashboard first.

Escalation and channel-routing settings are configured in the dashboard, not through this API.

Fetch a monitor

curl -H "Authorization: Bearer cw_..." \
  https://cronwarden.com/api/v1/monitors/nightly-backup

Returns the monitor's configuration, or 404 if the slug doesn't exist in your team.

Delete a monitor

curl -X DELETE -H "Authorization: Bearer cw_..." \
  https://cronwarden.com/api/v1/monitors/nightly-backup

Limits and errors

The upsert respects your plan: it's rejected if it would exceed your monitor count, or if the schedule checks in more often than your tier allows. See Plan limits.
A malformed body or an invalid schedule returns 400 with a message explaining what's wrong.
A missing or bad token returns 401.

See the API reference for the full endpoint and status-code list.