CheckBeacon API reference

Introduction

The CheckBeacon API lets you create and manage checks, read results, organize checks into groups, and pull dashboard stats — everything available in the web app.

The base URL for all requests is:

https://api.checkbeacon.com/api/v1

All requests and responses use application/json. Authenticated requests must include an Authorization: Bearer <token> header (see Authentication).

Authentication

Log in with your email and password to receive a session token. Include that token as a Bearer token on every subsequent request. Sessions last 8 hours; after that, log in again to get a new token.

Log in

POST /auth/login request body:

{
  "email": "you@example.com",
  "password": "••••••••"
}

Response:

{
  "token": "a1b2c3d4e5f6...",
  "expires_at": "2026-06-10T18:30:00Z",
  "user": {
    "id": "usr_123",
    "email": "you@example.com",
    "role": "admin"
  }
}

Use the returned token as a Bearer token on every other request:

Authorization: Bearer a1b2c3d4e5f6...

curl

# Log in and capture the token
curl -X POST https://api.checkbeacon.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "your-password"}'

# Use the token on a subsequent request
curl https://api.checkbeacon.com/api/v1/auth/me \
  -H "Authorization: Bearer a1b2c3d4e5f6..."

JavaScript (fetch)

const res = await fetch("https://api.checkbeacon.com/api/v1/auth/login", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ email: "you@example.com", password: "your-password" })
});
const { token } = await res.json();

// Use the token on a subsequent request
const me = await fetch("https://api.checkbeacon.com/api/v1/auth/me", {
  headers: { "Authorization": `Bearer ${token}` }
});

Python (requests)

import requests

base = "https://api.checkbeacon.com/api/v1"

resp = requests.post(f"{base}/auth/login", json={
    "email": "you@example.com",
    "password": "your-password",
})
token = resp.json()["token"]

headers = {"Authorization": f"Bearer {token}"}
me = requests.get(f"{base}/auth/me", headers=headers)

Checks

Checks are the core resource — each one represents a scheduled API or UI check.

Example: create a new API check.

curl -X POST https://api.checkbeacon.com/api/v1/checks \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production API health",
    "url": "https://api.example.com/health",
    "method": "GET",
    "expected_status_codes": [200],
    "check_interval_minutes": 5
  }'

The full payload also accepts optional fields: headers, auth (none / Basic / Bearer / API key header), a request body and content_type, body assertions, regions, and alert_after_consecutive_failures.

Sample response:

{
  "id": "chk_8f2a1c",
  "name": "Production API health",
  "url": "https://api.example.com/health",
  "method": "GET",
  "expected_status_codes": [200],
  "check_interval_minutes": 5,
  "alert_after_consecutive_failures": 3,
  "regions": ["us-east"],
  "status": "healthy",
  "created_at": "2026-06-10T12:00:00Z"
}

Results

Results are the recorded outcomes of each check run — status, response time, and timestamp.

Example: list the most recent unhealthy results for a check.

curl "https://api.checkbeacon.com/api/v1/checks/chk_8f2a1c/results?status=unhealthy&limit=20&offset=0" \
  -H "Authorization: Bearer <token>"

Results endpoints return a paginated envelope:

{
  "total": 134,
  "limit": 20,
  "offset": 0,
  "items": [
    {
      "id": "res_91a3",
      "check_id": "chk_8f2a1c",
      "status": "unhealthy",
      "response_time_ms": 842,
      "status_code": 503,
      "region": "us-east",
      "created_at": "2026-06-10T11:55:00Z"
    }
  ]
}

Use /results/summary?from=...&to=... to get time-bucketed response-time and status aggregates for charts.

Groups

Groups organize related checks — for example, all checks for a single service.

Stats & Health

Errors

The API uses standard HTTP status codes to indicate success or failure.

Rate limits

API requests are rate-limited per account to keep the service responsive for everyone. If you exceed the limit, you'll receive a 429 Too Many Requests response — wait and retry with backoff. If your integration needs a higher limit, contact support@checkbeacon.com.