Skip to main content

API Quickstart

This is the main-path setup for most StatiBeat API automation.

1. Set your page-host base URL​

Use your page or custom domain, not an internal numeric-ID route.

export STATIBEAT_BASE_URL="https://status.example.com"

2. Add a bearer token​

Create a page-scoped API token with the narrowest API scope and page role that fit the job.

export STATIBEAT_TOKEN="..."

3. Confirm the current page context​

curl "$STATIBEAT_BASE_URL/api/v1/context" \
  -H "Authorization: Bearer $STATIBEAT_TOKEN"

This confirms which org and page the current host resolves to.

4. Create an incident with stable identifiers​

curl -X POST "$STATIBEAT_BASE_URL/api/v1/admin/incidents" \
  -H "Authorization: Bearer $STATIBEAT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "incident-api-latency-2026-03-22",
    "title": "Elevated API latency",
    "description": "We are investigating elevated latency in the public API.",
    "status": "degraded",
    "affected_items": [{ "external_id": "api-gateway" }]
  }'

This page uses external_id on purpose because it is the cleanest automation pattern. If you just want the smallest working payloads, see API Examples.

5. Follow up without looking up numeric IDs​

curl -X POST "$STATIBEAT_BASE_URL/api/v1/admin/incidents/external/incident-api-latency-2026-03-22/resolve" \
  -H "Authorization: Bearer $STATIBEAT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "resolution_message": "Latency has returned to normal levels."
  }'

Main-path rules​

  • Use your page or custom domain as the base URL.
  • Start with /api/v1/context if you want to confirm scope.
  • Prefer external_id and slug over numeric IDs in automation payloads.
  • Prefer /api/v1/admin/... and /api/v1/org/... route families for customer automation.
  • Public incident and maintenance lists default to compact summaries. Append ?view=full to the quoted URL only when you need the full nested document.

Next steps​

  • See API Examples for maintenance, Beats, Terraform, and org flows.
  • See API Tokens for token scope guidance.
  • Open the full API Reference when you want the generated contract.