BoxWatch API

The public API for BoxWatch, simple, flat-priced server monitoring. This repo holds the OpenAPI 3.1 specification (openapi.yaml) for the /v1 API so you can explore it, generate clients, and build your own tools on top of BoxWatch.

Base URL: https://api.boxwatch.app/v1

Authenticating

Every /v1 request is authenticated. You can use either:

1. An API key (recommended for scripts and tools). Generate a full-access key in your BoxWatch dashboard under Settings, then send it as a bearer token:

   curl -H "Authorization: Bearer bw_your_key_here" https://api.boxwatch.app/v1/servers

   An X-API-Key: bw_your_key_here header works too.

2. A JWT from POST /auth/login, sent the same way (Authorization: Bearer <jwt>). This is what the web app and the mobile app use.

A note on key scope

A full-access API key can do everything your account can, including creating and deleting servers, checks, and status pages. Treat it like a password:

• Store it somewhere secret (an environment variable, a secrets manager, the iOS Keychain).
• Revoke it from Settings the moment a key is exposed. Each key tracks a last-used time so you can spot stale ones.

Quickstart

KEY="bw_your_key_here"

# List your servers
curl -H "Authorization: Bearer $KEY" https://api.boxwatch.app/v1/servers

# A single server with current metrics
curl -H "Authorization: Bearer $KEY" https://api.boxwatch.app/v1/servers/123

# Recent alert history
curl -H "Authorization: Bearer $KEY" https://api.boxwatch.app/v1/alerts/history

# Register a device for push notifications (used by the mobile app)
curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"token":"ExponentPushToken[...]","platform":"ios"}' \
  https://api.boxwatch.app/v1/devices

What you can reach

The /v1 surface mirrors what you manage in the dashboard: servers and their metrics, alerts, cron heartbeat checks, synthetic uptime checks, processes, status pages, server groups, maintenance windows, webhooks, custom endpoints, dashboards, reports, and push-notification devices. The full list of paths, parameters, request bodies, and response shapes is in openapi.yaml.

Conventions

• All responses are JSON.
• Errors return { "error": { "code": "...", "message": "..." } } with an appropriate HTTP status (401 unauthorized, 404 not found, 422 validation, 429 rate limited). Some older endpoints may still return { "error": "message string" }.
• Rate limit: 60 requests per minute per credential. Exceeding it returns 429.
• The API is versioned. /v1 is stable; any breaking change will ship under a new version prefix.

Using the spec

openapi.yaml is a standard OpenAPI 3.1 document. You can:

• Render it in Swagger Editor or Redocly.
• Generate a client in your language with openapi-generator or swagger-codegen.

Feedback

Found something wrong or missing in the spec? Email watcher@boxwatch.app or open an issue.

License

The specification in this repository is released under the MIT License.