Guides

Use the Management API when software needs to provision and manage checks programmatically.

The Management API is for control planes, internal dashboards, bootstrapping scripts, and any automation that needs lifecycle control over checks and channels.

Back to Guides Open Classic Docs Open AI API Guide

Management API

Authenticated API for creating, updating, pausing, resuming, and inspecting checks.

When to use

  • Use this page when code needs to create or update checks automatically.
  • Use this page for internal admin panels, onboarding flows, or auto-provisioning systems.
  • Use this page when a user asks for programmatic lifecycle management instead of manual UI setup.

Inputs

  • An API key from the account.
  • A target project or account context.
  • The check specification, such as name, slug, timeout, schedule, and channels.

Outputs

  • Created or updated checks.
  • Lifecycle actions such as pause and resume.
  • Structured access to check status, channels, and ping history.

Failure cases

  • Requests are unauthorized because X-Api-Key is missing or invalid.
  • Provisioning scripts create duplicates because they do not reconcile existing checks.
  • The integration chooses the Management API when a simpler ping-only flow would have been enough.

Copy-paste example

Create a check with curl

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
  }'

Authentication model

  • Send the API key in the X-Api-Key request header.
  • Prefer the /api/v3/ base path for new integrations.
  • Store the API key in a secret manager or environment variable instead of source code.

Most useful resources

  • GET /api/v3/checks/ lists checks.
  • POST /api/v3/checks/ creates a check.
  • GET /api/v3/checks/<code> retrieves details for a single check.
  • POST /api/v3/checks/<code>/pause or /resume controls the check lifecycle.
  • GET /api/v3/channels/ lists notification channels.

AI guidance

  • Use the Management API when the user asks to create checks from code.
  • Keep recommending the ping API for already-existing checks that only need signaling.
  • Suggest client-side idempotency patterns if repeated provisioning runs may create duplicates.