API: REST resources

Conventions

• Authenticate with a workspace token (see Authentication). GET needs the read scope; everything else needs write.
• Resources live under the status page slug. A slug or id from another workspace is always 404.
• Single objects come back as {"data": {…}}. Lists add links and meta.
• PATCH accepts any subset of fields; omitted fields keep their values. Deletes return 204.
• Errors are JSON with a stable code. Plan limits return 402 plan_limit_reached. See Errors & Rate Limits.
• The older ingest endpoints (POST pages/{slug}/incidents, PATCH incidents/{id}, …) still work unchanged and keep their flat response shape.

Cursor pagination

Lists return up to per_page items (default 25, max 100). Pass meta.next_cursor back as cursor until it is null.

curl "https://usebeacon.pro/api/v1/status-pages/acme/incidents?per_page=50&state=open" \
  -H "Authorization: Bearer bchk_..."

{
  "data": [ { "id": 42, "title": "Elevated errors", "state": "investigating", "updates": [ … ], … } ],
  "links": { "next": "…?cursor=eyJpZCI6NDIsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0" , … },
  "meta": { "per_page": 50, "next_cursor": "eyJpZCI6NDIsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0", "prev_cursor": null, … }
}

Status pages

Components

Monitors

Incidents

Scheduled maintenances

Subscribers

Webhooks

Statuspage imports

Subscriber consent

A subscriber added over the API is unconfirmed and receives the same confirmation email as the public subscribe form; they get incident emails only after clicking it. This needs a public page (otherwise 422 page_not_public).

If you already hold consent (for example, migrating an existing list), send "confirmed": true with a token that has the subscribers:confirm scope. No email is sent. Without that scope the request is rejected with 403 insufficient_scope.

Importing from Atlassian Statuspage

Owners can also start an import from Settings → Import from Statuspage. Components are imported flat (a group’s name is kept in each component’s description) with their current status, plus incidents with every update and original timestamps, and scheduled maintenance. Imported history notifies no one.

• API key + page id reads everything through the Statuspage Manage API, and is the only way to bring subscribers. The key is passed encrypted to the import job and discarded afterwards; it is never stored.
• A public page URL (https) reads /api/v2/summary.json, incidents.json and scheduled-maintenances.json: components, the most recent incidents and maintenance. No key needed.
• Imported subscribers are unconfirmed and get a confirmation email, unless subscribers_consent is true (needs the subscribers:confirm scope via the API, or the owner’s explicit confirmation in Settings).
• Re-running is safe: rows are matched by their Statuspage id and updated, not duplicated. When a plan limit is hit the import stops with state stopped and a message; upgrade and run it again to continue.

Webhook secrets

Secrets are write-only. Send your own (16+ characters) or omit it on create and Beacon generates one, returned once as a top-level "secret" field in the 201 response. Rotate it with PATCH; it is never shown again.

{
  "data": { "id": 7, "url": "https://hooks.example.com/beacon", "enabled": true, "status_component_id": null, … },
  "secret": "q3V…32 chars"
}