title: "API reference" description: "Overview of the BoxWatch REST API — base URL, authentication, request and response formats, rate limits." last_updated: "2026-05-24"

API reference

The BoxWatch API lets you manage servers, cron checks, processes, uptime checks, alerts, and status pages programmatically. Everything you can do in the dashboard, you can do over HTTP.

Base URL

https://api.boxwatch.app

The API is hosted at a separate subdomain from the dashboard. All endpoints are HTTPS-only — HTTP requests are redirected.

Authentication

Most endpoints require a bearer token. Generate API keys from Dashboard → Account → API keys.

curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://api.boxwatch.app/servers

There are three key types, each with different scopes:

• Full keys — read/write access to everything in your account
• Endpoint keys — bound to a single custom API endpoint
• TV keys — bound to a single TV dashboard

The auth middleware accepts the token via the Authorization: Bearer ... header. Cookies are used for the dashboard's own session and don't apply to API calls.

Detailed authentication docs are coming soon.

Request format

Request bodies use JSON. Set Content-Type: application/json on every POST, PUT, and PATCH.

curl -X POST https://api.boxwatch.app/cron-checks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Nightly backup","interval_seconds":86400,"grace_seconds":300}'

Field names are snake_case. Booleans accept true/false or 1/0.

Response format

Responses are JSON. Successful responses use the resource's natural shape — sometimes a single object, sometimes wrapped in a key like { "checks": [...] } when paging or limit metadata is included.

Errors return a 4xx or 5xx status with a JSON body:

{
  "error": "validation_failed",
  "issues": [
    { "field": "interval_seconds", "reason": "integer 60..7776000" }
  ]
}

Common error codes:

Rate limiting

Two kinds of rate limits:

• Auth endpoints (/auth/login, /auth/register, /auth/forgot-password) — 5 requests per 15 minutes per IP.
• Ping endpoints (/ping/:slug) — 60 pings per minute per slug. Excess requests get a 200 OK but aren't recorded.
• Admin endpoints — 30 requests per minute.

A 429 response includes a Retry-After header (in seconds). Back off and retry.

Versioning

The API is currently unversioned. Breaking changes will be announced by email to accounts with active API usage, with at least 30 days of notice. Additive changes (new fields, new endpoints) happen continuously and don't require a notice.

If you want maximum stability, pin to the specific fields you read and ignore unknown keys.

Endpoint groups

Detailed reference pages for each group are coming soon. The groups, mounted under https://api.boxwatch.app/, are:

• Authentication (/auth/*) — login, signup, 2FA, password reset
• Servers (/servers/*) — list, fetch, update, delete monitored servers
• Cron Checks (/cron-checks/*) — manage cron heartbeat checks; see Cron heartbeat monitoring for ping URL semantics
• Processes (/servers/:id/processes/*) — watched processes per server
• Uptime Checks (/uptime-checks/*) — synthetic HTTP/TCP/TLS probes
• Webhooks (/webhooks/*) — generic webhook endpoints with custom headers
• Status Pages (/status-pages/*) — public status page configuration
• Alerts (/alerts/*) — alert rules and history
• Public Routes — unauthenticated endpoints: /ping/:slug (cron heartbeats), /status/:slug (public status pages), /badge/:serverId (uptime badges)