Health Check Monitors

Health check monitors parse JSON responses that report on multiple sub-checks within your application. This allows you to monitor database connections, disk space, queue health, and other application components from a single endpoint.

Endpoints

Method	Path	Description
GET	/health_check_monitors	List all health check monitors
GET	/health_check_monitors/:id	Get a specific monitor
POST	/health_check_monitors	Create a monitor
PUT	/health_check_monitors/:id	Update a monitor
DELETE	/health_check_monitors/:id	Delete a monitor

Health Check Monitor Object

{
  "id": "xyz789",
  "title": "App Health",
  "url": "https://example.com/health",
  "alert_group_id": "abc123",
  "status": "up",
  "staleness_threshold_minutes": 10,
  "checks_total": 5,
  "checks_passing": 5,
  "checked_at": "2024-01-15T10:35:00Z",
  "finished_at": "2024-01-15T10:34:55Z",
  "external_id": "main-app-health",
  "inserted_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

Fields

Field	Type	Description
title	string	Name of the monitor (required)
url	string	Health check endpoint URL (required)
alert_group_id	string	Alert group to notify (required)
staleness_threshold_minutes	integer	Alert if finishedAt is older than this (default: 10)
status	string	Current status: up, down, degraded, stale, or pending
checks_total	integer	Total number of sub-checks in the response
checks_passing	integer	Number of sub-checks with status ok
finished_at	datetime	Timestamp from the health check response
external_id	string	Your identifier for idempotent operations

Status Values

Status	Description
up	All checks passing
down	One or more checks have failed or crashed status
degraded	One or more checks have warning status (no incident created)
stale	The finishedAt timestamp is older than the staleness threshold
pending	Monitor has not been checked yet

Expected Response Format

Your health check endpoint must return JSON in the following format:

{
  "finishedAt": "1638879833",
  "checkResults": [
    {
      "name": "UsedDiskSpace",
      "label": "Used Disk Space",
      "status": "ok",
      "notificationMessage": "",
      "shortSummary": "45%",
      "meta": {"disk_space_used_percentage": 45}
    },
    {
      "name": "Database",
      "label": "Database Connection",
      "status": "ok",
      "notificationMessage": "",
      "shortSummary": "connected",
      "meta": {}
    }
  ]
}

Check Result Fields

Field	Type	Description
name	string	Unique identifier for the check (required)
label	string	Human-readable name
status	string	ok, warning, failed, crashed, or skipped
notificationMessage	string	Detailed message shown in incidents
shortSummary	string	Brief status shown in dashboard
meta	object	Additional metadata

The finishedAt field should be a Unix timestamp (seconds since epoch) indicating when the checks were last run.

Create a Health Check Monitor

curl -X POST https://beepr.io/api/v1/health_check_monitors \
  -H "Authorization: Bearer bpr_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "alert_group_id": "abc123",
    "title": "App Health",
    "url": "https://example.com/health",
    "staleness_threshold_minutes": 15,
    "external_id": "main-app-health"
  }'

Filtering by Alert Group

List monitors for a specific alert group:

curl "https://beepr.io/api/v1/health_check_monitors?alert_group_id=abc123" \
  -H "Authorization: Bearer bpr_your_key"

Idempotent Creation

If you provide an external_id and a monitor with that ID already exists, the API will update the existing monitor instead of creating a duplicate.

For the complete schema, see the OpenAPI specification.