Skip to main content

API Conventions

This page covers the conventions customers should expect from the supported /api/v1 API surface.

Error envelope​

StatiBeat uses a standard JSON error envelope:

{
  "error": "invalid ID parameter"
}

The backend standardizes this shape in handlers.ErrorResponse.

Unknown JSON fields​

Request payloads reject unknown JSON fields. That is intentional, and it helps integrations fail fast when payloads drift from the supported contract.

Shell-friendly examples​

The docs quote example URLs when they include query parameters, for example:

curl "$STATIBEAT_BASE_URL/api/v1/incidents?view=full"

Keep those quotes when you paste into shells like zsh, otherwise characters such as ? can be treated as wildcards before curl sees the URL.

Compact list views​

Several list endpoints return a compact summary by default so simple reads are easier to scan.

Current examples include:

  • /api/v1/incidents
  • /api/v1/maintenances
  • /api/v1/admin/beats
  • /api/v1/admin/feeds
  • /api/v1/admin/subscribers

When you want the full nested document instead, append ?view=full to the quoted URL.

Rate limiting​

Default rate limits in the open-source backend are deployment-configurable, but the current defaults in code are:

  • public read traffic: 100 requests per minute
  • internal-service read traffic: 600 requests per minute
  • authenticated admin write traffic: 120 write requests per minute
  • subscriber and request-access creation flows: 10 requests per minute
  • magic-token management flows: 30 requests per minute

Production deployments may override those defaults, so clients should still handle 429 responses with retry and backoff.

The Redis-backed rate limiters include Retry-After, X-RateLimit-Tier, X-RateLimit-Limit, and X-RateLimit-Window-Seconds headers. The authenticated admin write limiter is scoped per authenticated principal and route.

Retry guidance​

  • Safe GET requests can usually be retried with exponential backoff.
  • Mutating requests should only be retried when the caller can prove they are safe to repeat.
  • Treat 400 responses as request-shape or validation problems.
  • Treat 401 and 403 as auth or permission failures.
  • Treat 429 as a signal to back off.
  • Treat 5xx responses as transient service-side failures unless support guidance says otherwise.

API surfaces​

Every supported operation declares x-statibeat-surface as one of:

  • public
  • page-admin
  • organization-admin

The combined customer contract contains all three surfaces. Separate contracts are available for focused reference browsing and code generation.

The internal engineering contract additionally uses internal. Operations marked with x-statibeat-compatibility: true are supported runtime aliases but are omitted from customer contracts so generated clients use the preferred current-host routes.