REST API v1

List every status page this API key's organization owns.

curl -sS "$BEACON_URL/api/v1/pages" \
  -H "Authorization: Bearer $BEACON_API_KEY"

Fetch one status page and its settings.

curl -sS "$BEACON_URL/api/v1/pages/$PAGE_ID" \
  -H "Authorization: Bearer $BEACON_API_KEY"

Update a page's settings. branding and subscriptionOptions are merged key-by-key, so you can set one without restating the rest. Slug, custom domain and visibility are deliberately not writable here.

Body: name, description, timeZone, hiddenFromSearch, subscriptionOptions, branding — at least one

curl -sS "$BEACON_URL/api/v1/pages/$PAGE_ID" \
  -H "Authorization: Bearer $BEACON_API_KEY" -H "Content-Type: application/json" \
  -X PATCH -d '{"timeZone":"Europe/Berlin","branding":{"accent":"#0f766e"}}'

List a page's components, in display order.

curl -sS "$BEACON_URL/api/v1/pages/$PAGE_ID/components" \
  -H "Authorization: Bearer $BEACON_API_KEY"

Create a component on a page.

Body: name (required), description, parentId, position

curl -sS "$BEACON_URL/api/v1/pages/$PAGE_ID/components" \
  -H "Authorization: Bearer $BEACON_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"API"}'

Update a component, including its status.

Body: name, description, parentId, position, status, showUptime — at least one

curl -sS "$BEACON_URL/api/v1/components/$COMPONENT_ID" \
  -H "Authorization: Bearer $BEACON_API_KEY" -H "Content-Type: application/json" \
  -X PATCH -d '{"status":"degraded"}'

Delete a component. Its children (if any) are promoted to its own parent.

curl -sS "$BEACON_URL/api/v1/components/$COMPONENT_ID" \
  -H "Authorization: Bearer $BEACON_API_KEY" -X DELETE

Daily uptime series for a component, aggregated across its monitors, plus a summary (overall % and worst day) over the window.

Query: days (1-365, default 90), or start & end (YYYY-MM-DD, capped at 365 days)

curl -sS "$BEACON_URL/api/v1/components/$COMPONENT_ID/uptime?start=2026-06-01&end=2026-06-30" \
  -H "Authorization: Bearer $BEACON_API_KEY"

List a page's incidents and maintenances, newest first. q searches the title, every update body and the published postmortem.

Query: q, status, kind (each comma-separated), include_drafts (default false), limit (1-500, default 50)

curl -sS "$BEACON_URL/api/v1/pages/$PAGE_ID/incidents?kind=incident&status=investigating,identified" \
  -H "Authorization: Bearer $BEACON_API_KEY"

Incidents that are still open — kind incident, any status but resolved.

Query: limit (1-500, default 50)

curl -sS "$BEACON_URL/api/v1/pages/$PAGE_ID/incidents/unresolved" \
  -H "Authorization: Bearer $BEACON_API_KEY"

Maintenance windows announced but not started (status scheduled), soonest first.

Query: limit (1-500, default 50)

curl -sS "$BEACON_URL/api/v1/pages/$PAGE_ID/incidents/scheduled" \
  -H "Authorization: Bearer $BEACON_API_KEY"

Scheduled maintenance whose window has not begun yet, soonest first.

Query: limit (1-500, default 50)

curl -sS "$BEACON_URL/api/v1/pages/$PAGE_ID/incidents/upcoming" \
  -H "Authorization: Bearer $BEACON_API_KEY"

Maintenance windows happening right now (status in_progress).

Query: limit (1-500, default 50)

curl -sS "$BEACON_URL/api/v1/pages/$PAGE_ID/incidents/active_maintenance" \
  -H "Authorization: Bearer $BEACON_API_KEY"

Open an incident or maintenance. Supports "Idempotency-Key" — see below.

Body: title, body (required); kind, status, severity, componentIds, componentImpact, scheduledStart, scheduledEnd, metadata, publish

curl -sS "$BEACON_URL/api/v1/pages/$PAGE_ID/incidents" \
  -H "Authorization: Bearer $BEACON_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f2a9c9e-2b41-4c9a-9c2e-1b1e6a2b9d10" \
  -d '{
        "title": "Elevated API error rates",
        "body": "We are investigating elevated 500s on the API.",
        "severity": "major",
        "componentIds": ["'"$COMPONENT_ID"'"]
      }'

Fetch one incident (or maintenance) with its full update timeline.

curl -sS "$BEACON_URL/api/v1/incidents/$INCIDENT_ID" \
  -H "Authorization: Bearer $BEACON_API_KEY"

Correct an incident's title, severity or metadata. A correction, not a lifecycle step: it writes no timeline entry and notifies nobody. metadata merges; a key set to null is removed.

Body: title, severity (null clears it), metadata — at least one

curl -sS "$BEACON_URL/api/v1/incidents/$INCIDENT_ID" \
  -H "Authorization: Bearer $BEACON_API_KEY" -H "Content-Type: application/json" \
  -X PATCH -d '{"severity":"critical","metadata":{"jiraKey":"OPS-4412"}}'

Delete an incident and its updates. Permanent, and it disappears from the public history — prefer resolving anything customers already saw.

curl -sS "$BEACON_URL/api/v1/incidents/$INCIDENT_ID" \
  -H "Authorization: Bearer $BEACON_API_KEY" -X DELETE

Post a follow-up update and move the incident to a new status.

Body: status, body (required); componentStatuses, publish

curl -sS "$BEACON_URL/api/v1/incidents/$INCIDENT_ID/updates" \
  -H "Authorization: Bearer $BEACON_API_KEY" -H "Content-Type: application/json" \
  -d '{"status":"monitoring","body":"A fix has been deployed; we are watching error rates."}'

Close an incident (or complete a maintenance) with a final update. Shorthand for posting the terminal status.

Body: body (required)

curl -sS "$BEACON_URL/api/v1/incidents/$INCIDENT_ID/resolve" \
  -H "Authorization: Bearer $BEACON_API_KEY" -H "Content-Type: application/json" \
  -d '{"body":"The fix has been verified in production; error rates are back to baseline."}'

Correct one already-posted update. Re-renders the page and re-runs translation, but never re-notifies subscribers — a typo fix must not mail everyone twice.

Body: body, displayAt (null clears the backdating override) — at least one

curl -sS "$BEACON_URL/api/v1/incidents/$INCIDENT_ID/updates/$UPDATE_ID" \
  -H "Authorization: Bearer $BEACON_API_KEY" -H "Content-Type: application/json" \
  -X PATCH -d '{"body":"A fix has been deployed; error rates are back to baseline."}'

List a page's subscribers, newest first, 50 per page. Targets come back in full (the dashboard table masks them).

Query: q, channel (email | slack | teams | discord | sms), page (1-based)

curl -sS "$BEACON_URL/api/v1/pages/$PAGE_ID/subscribers?channel=email" \
  -H "Authorization: Bearer $BEACON_API_KEY"

Add a subscriber by hand. email starts unverified and triggers the same double opt-in mail the public form sends; webhook channels and sms are verified immediately.

Body: channel, target (both required)

curl -sS "$BEACON_URL/api/v1/pages/$PAGE_ID/subscribers" \
  -H "Authorization: Bearer $BEACON_API_KEY" -H "Content-Type: application/json" \
  -d '{"channel":"email","target":"ops@example.com"}'

Remove one subscriber. This is the operator-side removal — a recipient's own unsubscribe is the signed link in their notifications and needs no key.

curl -sS "$BEACON_URL/api/v1/subscribers/$SUBSCRIBER_ID" \
  -H "Authorization: Bearer $BEACON_API_KEY" -X DELETE

List a page's system metrics in display order, each with its latest value, when that value landed, and how many points arrived in the last 24 hours.

curl -sS "$BEACON_URL/api/v1/pages/$PAGE_ID/metrics" \
  -H "Authorization: Bearer $BEACON_API_KEY"

Define a metric — the chart itself, not its data. Published metrics appear on the public status page; data arrives separately at the endpoints below. Capped by your plan's metric limit.

Body: name (required); suffix, decimals (0-6), published, position

curl -sS "$BEACON_URL/api/v1/pages/$PAGE_ID/metrics" \
  -H "Authorization: Bearer $BEACON_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"API response time","suffix":"ms","decimals":0,"published":true}'

Rename a metric, change its formatting, reorder it, or publish/unpublish it.

Body: name, suffix, decimals, published, position — at least one

curl -sS "$BEACON_URL/api/v1/metrics/$METRIC_ID" \
  -H "Authorization: Bearer $BEACON_API_KEY" -H "Content-Type: application/json" \
  -X PATCH -d '{"published":true}'

Delete a metric and every data point it holds. Permanent.

curl -sS "$BEACON_URL/api/v1/metrics/$METRIC_ID" \
  -H "Authorization: Bearer $BEACON_API_KEY" -X DELETE

Submit points for one metric. ts accepts epoch seconds, epoch milliseconds or ISO-8601, and defaults to the server clock. Points are bucketed to 30s (same bucket = last value wins); anything older than the retention window or more than a minute in the future is refused individually and counted in skipped.

Body: { value, ts? } for one sample, or { points: [{ ts?, value }, …] } for up to 3000

curl -sS "$BEACON_URL/api/v1/metrics/$METRIC_ID/data" \
  -H "Authorization: Bearer $BEACON_API_KEY" -H "Content-Type: application/json" \
  -d '{"value":141}'

Submit points for several metrics at once, keyed by metric id. Every id is checked against the page before anything is written and the whole body is one transaction — so a request naming one unknown metric writes nothing and 404s, which makes retrying the same body safe. The 3000-point cap counts across the whole body.

Body: { "<metricId>": [{ ts?, value }, …] } — a single object may stand in for a one-element array

curl -sS "$BEACON_URL/api/v1/pages/$PAGE_ID/metrics/data" \
  -H "Authorization: Bearer $BEACON_API_KEY" -H "Content-Type: application/json" \
  -d '{"'"$METRIC_ID"'":[{"value":141},{"value":139}]}'

List a page's incident templates, by name.

curl -sS "$BEACON_URL/api/v1/pages/$PAGE_ID/templates" \
  -H "Authorization: Bearer $BEACON_API_KEY"

Create a template. Inert data — creating one opens nothing and notifies nobody.

Body: name, title, body (required); kind, severity, componentIds, componentImpact

curl -sS "$BEACON_URL/api/v1/pages/$PAGE_ID/templates" \
  -H "Authorization: Bearer $BEACON_API_KEY" -H "Content-Type: application/json" \
  -d '{
        "name": "Payments degraded",
        "title": "Payment processing is degraded",
        "body": "We are investigating elevated failures at our payment provider.",
        "severity": "major"
      }'

Fetch one template.

curl -sS "$BEACON_URL/api/v1/templates/$TEMPLATE_ID" \
  -H "Authorization: Bearer $BEACON_API_KEY"

Update a template. The whole record is re-normalized against the resulting kind, so switching to maintenance drops a severity that no longer applies instead of erroring.

Body: name, kind, title, body, severity, componentIds, componentImpact — at least one

curl -sS "$BEACON_URL/api/v1/templates/$TEMPLATE_ID" \
  -H "Authorization: Bearer $BEACON_API_KEY" -H "Content-Type: application/json" \
  -X PATCH -d '{"severity":"critical"}'

Delete a template. Incidents already opened from it are untouched.

curl -sS "$BEACON_URL/api/v1/templates/$TEMPLATE_ID" \
  -H "Authorization: Bearer $BEACON_API_KEY" -X DELETE