API Reference

Full REST API for managing monitors, alerts, and API keys programmatically.

Authentication

All API endpoints (except ping URLs) require an API key passed as a Bearer token in the Authorization header.

Authorization: Bearer crnd_YOUR_API_KEY

Generate API keys in your dashboard under Settings → API Keys.

Base URL

https://crond.io/api/v1

Ping endpoints

GET/ping/{uuid}

Record a successful job run.

POST/ping/{uuid}

Record a successful run with optional metadata.

{ "message": "optional note", "duration_ms": 1234 }

POST/ping/{uuid}/fail

Record an explicit failure and trigger alerts immediately.

{ "message": "error description" }

POST/ping/{uuid}/start

Signal that a job has started (enables run duration tracking).

Monitors

GET/monitors

List all monitors.

POST/monitors

Create a new monitor.

{
  "name": "Nightly backup",
  "schedule": "0 2 * * *",
  "grace_seconds": 300
}

GET/monitors/{id}

Get a single monitor.

PATCH/monitors/{id}

Update a monitor.

DELETE/monitors/{id}

Delete a monitor.

Ping history

GET/monitors/{id}/pings

Retrieve ping history for a monitor. Supports ?limit and ?before query params.

Alert rules (per monitor)

GET/monitors/{id}/alerts

List alert rules attached to a monitor.

POST/monitors/{id}/alerts

Attach an alert rule. Provide EITHER channel_id (named channel) OR channel_type + channel_config (inline, legacy).

{
  "channel_id": "uuid-of-named-channel",
  "enabled": true
}

PUT/alerts/{id}

Update an alert rule (toggle enabled or switch channel).

DELETE/alerts/{id}

Detach an alert rule.

Alert channels (named, reusable)

GET/alert-channels

List named channels owned by the caller. URL-bearing config fields are masked in this view.

POST/alert-channels

Create a named channel. Pass generate_secret_token=true to receive an HMAC signing secret in the response (only shown once).

{
  "name": "On-call Slack",
  "type": "webhook",
  "config": { "url": "https://hooks.slack.com/services/..." },
  "generate_secret_token": true
}

GET/alert-channels/{id}

Detail view with unmasked config (no secret_token).

PUT/alert-channels/{id}

Update name/config or rotate the signing secret in place.

{
  "rotate_secret": true
}

DELETE/alert-channels/{id}

Delete a channel. Returns 409 if any monitors still reference it.

POST/alert-channels/dedupe?dry_run=true

Analyze duplicate inline alert configs and (when dry_run=false) collapse them into named channels with full transactional safety + backup.

Status page

GET/status-page

Combined view: slug, slug_editable (Pro gate), public_url, branding fields, and monitor visibility summary.

PUT/status-page

Update title, description, slug (Pro+), and visibility toggles. Slug edits return 409 on collision, 400 on reserved name.

{
  "title": "Acme Status",
  "description": "Real-time status",
  "show_uptime": true,
  "show_last_ping": false
}

PUT/monitors/show-on-status

Bulk-toggle which monitors are publicly visible on the status page.

{
  "monitor_ids": ["uuid-a", "uuid-b"],
  "show": true
}

Response format

All responses return JSON. Errors follow this shape:

{
  "error": "monitor_not_found",
  "message": "No monitor with that UUID exists"
}