Skip to main content

API Reference

StatiBeat ships a generated OpenAPI contract for the scoped /api/v1 API.

For most customer integrations, the preferred route shapes are:

  • anonymous public page reads on your page or custom domain: /api/v1/settings, /api/v1/incidents, /api/v1/maintenances
  • current automation context on your page or custom domain: /api/v1/context
  • page or custom domain admin routes: /api/v1/admin/...
  • org routes derived from the current page: /api/v1/org/...

If you need anonymous page metadata instead of an authenticated automation context, use /api/v1/pages/public/current-host.

Two naming notes are worth knowing up front:

  • /api/v1/admin/page-settings is the page identity and access surface: name, slugs, visibility, domains, and viewer access.
  • /api/v1/admin/site-settings is the public site customization surface: branding, homepage sections, embeds, notifications, and locale defaults.
  • /api/v1/admin/beats is the main Beats API surface for checks, runs, events, and reviewable actions.
  • /api/v1/admin/analytics/summary is the bounded page analytics surface for traffic, subscriber, activity, and delivery summaries.
  • /api/v1/admin/terraform/..., /api/v1/admin/slack/..., and the authz route families expose page-governance configuration for customers who automate setup.

The customer-facing contract is available in two docs-site-friendly forms:

The API Examples page is intentionally minimal. Use this reference when you want the full payload surface, optional fields, and generated schemas.

Each operation in the generated reference starts with an authentication label:

  • Authentication: none. means you can call it without an API token.
  • Authentication: bearer token required. means you need a bearer API token.

In practice, most customers only need two API modes:

  • anonymous public page reads on their page or custom domain
  • bearer-token admin automation on that same page or custom domain

List endpoints for incidents, maintenance windows, Beats, feeds, and subscribers default to a compact summary payload so simple reads stay easy to scan. Append ?view=full to the quoted URL when you want the full nested document, for example curl "$STATIBEAT_BASE_URL/api/v1/incidents?view=full", curl "$STATIBEAT_BASE_URL/api/v1/maintenances?view=full", curl "$STATIBEAT_BASE_URL/api/v1/admin/beats?view=full" -H "Authorization: Bearer $STATIBEAT_TOKEN", curl "$STATIBEAT_BASE_URL/api/v1/admin/feeds?view=full" -H "Authorization: Bearer $STATIBEAT_TOKEN", or curl "$STATIBEAT_BASE_URL/api/v1/admin/subscribers?view=full" -H "Authorization: Bearer $STATIBEAT_TOKEN".

Which APIs are documented publicly​

The public API reference includes two supported audiences:

  • public: anonymous or magic-link flows used by status-page visitors, subscribers, feed/view managers, and management links
  • customer: authenticated customer-admin APIs used to manage pages, incidents, maintenance, API tokens, SSO, domains, and related configuration

Some endpoints are intentionally not part of the public contract even though they exist in the backend. We keep operational and security-sensitive routes out of the public docs surface on purpose.

Examples of intentionally non-public routes include:

  • Slack shared-install and route-sync operations
  • Slack reminder claim operations
  • notification-event and attempt inspection routes
  • repair or migration utilities used for operational recovery
  • internal managed-service routes

Contract artifacts​

There are two generated OpenAPI artifacts in the backend repo:

  • application/backend/docs/openapi_public.json
  • application/backend/docs/openapi.json

Use the public artifact for customer docs and integrations. Treat the full artifact as an engineering and internal-support reference.

Notes​

  • The OpenAPI contract is generated from the registered route tree, so path and method coverage stay aligned with the server implementation.
  • The docs site intentionally points at the public contract rather than the full internal/admin surface.