API Guide

Use ping URLs for simple jobs, and the Management API when automation needs control.

The public API has two layers. The Ping API handles status signals from jobs and scripts. The Management API handles check creation, updates, pause/resume flows, channels, and ping history.

OpenAPI JSON Classic Docs

Ping API

  • `GET /ping/<uuid>` records a successful heartbeat.
  • `GET /ping/<uuid>/start` records job start time.
  • `GET /ping/<uuid>/fail` records an explicit failure.
  • `GET /ping/<uuid>/<exitstatus>` maps non-zero exit codes to failures.
  • Slug URLs are available for human-friendly integrations.

Use this layer when the external job already exists and only needs a heartbeat target.

Management API

  • Base paths: `/api/v1/`, `/api/v2/`, `/api/v3/`.
  • Authentication: `X-Api-Key` request header.
  • Main resources: checks, channels, pings, flips, badges, metrics, status.
  • Best for internal tooling, control planes, and auto-provisioning workflows.

Use this layer when an integration needs to create checks on behalf of a user.

Typical request patterns

Heartbeat after a cron job finishes

The simplest integration. Exit successfully, then hit the ping URL.

0 * * * * /path/to/backup.sh && curl -fsS -m 10 --retry 3 https://hc.bestboy.work/ping/your-uuid-here

Record a job start and final status

Useful when you want runtime measurements and explicit failure signals.

curl -fsS -m 10 --retry 3 "https://hc.bestboy.work/ping/your-uuid-here/start"
run_the_job
status=$?
curl -fsS -m 10 --retry 3 "https://hc.bestboy.work/ping/your-uuid-here/$status"
exit $status

Create a check over the Management API

Provision checks from your backend or automation scripts.

curl -X POST https://hc.bestboy.work/api/v3/checks/ \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Nightly backup",
    "slug": "nightly-backup",
    "tags": "ops backup",
    "timeout": 900,
    "grace": 300
  }'

Ping from Python

A tiny requests-based example for internal tools.

import requests

url = "https://hc.bestboy.work/ping/your-uuid-here"
response = requests.get(url, timeout=10)
response.raise_for_status()