Skip to main content

API Examples

These examples show the supported patterns we expect most teams to need first.

Set a base URL first:

export STATIBEAT_BASE_URL="https://example.statuspage.your-company.com"

Read the current page by URL prefix​

curl "$STATIBEAT_BASE_URL/api/v1/pages/public/acme-status"

Read incidents for a scoped status page​

curl "$STATIBEAT_BASE_URL/api/v1/orgs/1/pages/42/incidents?status=active&limit=10"

Create a Terraform API token​

curl -X POST "$STATIBEAT_BASE_URL/api/v1/orgs/1/pages/42/admin/api-tokens" \
  -H "Authorization: Bearer $STATIBEAT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "terraform-prod",
    "description": "Terraform automation token",
    "permission": "write",
    "role_key": "page_admin",
    "terraform_managed": true
  }'

This page-scoped payload matches the dedicated Terraform workspace guidance: a write-capable API token paired with the page_admin role and terraform_managed: true.

Create an incident​

curl -X POST "$STATIBEAT_BASE_URL/api/v1/orgs/1/pages/42/admin/incidents" \
  -H "Authorization: Bearer $STATIBEAT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Elevated API latency",
    "description": "We are investigating elevated latency in the public API.",
    "status": "degraded",
    "impact": "Some API requests are slower than normal.",
    "affected_items": [{ "id": 7 }, { "id": 9 }]
  }'

Resolve an incident​

curl -X POST "$STATIBEAT_BASE_URL/api/v1/orgs/1/pages/42/admin/incidents/123/resolve" \
  -H "Authorization: Bearer $STATIBEAT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "resolution_message": "Latency has returned to normal levels."
  }'

Schedule a maintenance window​

curl -X POST "$STATIBEAT_BASE_URL/api/v1/orgs/1/pages/42/admin/maintenances" \
  -H "Authorization: Bearer $STATIBEAT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Elastic Cloud maintenance - eu-west-2",
    "description": "Planned infrastructure updates for the primary region.",
    "impact": "Customers may notice brief latency spikes during failover checks.",
    "status": "scheduled",
    "lifecycle_stage_name": "Scheduled",
    "affected_items": [{ "id": 7 }, { "id": 9 }],
    "auto_transition_enabled": true,
    "auto_transition_start_message": "Maintenance has started and work is in progress.",
    "auto_transition_complete_message": "Maintenance has completed successfully.",
    "scheduled_start_time": "2026-03-25T21:00:00Z",
    "scheduled_end_time": "2026-03-25T21:45:00Z"
  }'

Post a maintenance update​

curl -X POST "$STATIBEAT_BASE_URL/api/v1/orgs/1/pages/42/admin/maintenances/88/updates" \
  -H "Authorization: Bearer $STATIBEAT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Maintenance is in progress. Engineers are validating cluster health.",
    "status": "in_progress",
    "lifecycle_stage_name": "In Progress"
  }'

Create a beat​

curl -X POST "$STATIBEAT_BASE_URL/api/v1/orgs/1/pages/42/admin/synthetic-monitors" \
  -H "Authorization: Bearer $STATIBEAT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Checkout API health",
    "description": "Tracks the public checkout health endpoint.",
    "type": "api",
    "enabled": true,
    "interval_seconds": 60,
    "timeout_ms": 5000,
    "regions": ["europe-west2"],
    "target": {
      "url": "https://api.example.com/health",
      "method": "GET",
      "expected_status_codes": [200]
    },
    "component_ids": [7],
    "threshold_policies": {
      "critical_rule": {
        "consecutive_failures": 3
      }
    },
    "action_policies": {
      "critical": {
        "admin_banner": true,
        "public_post": true,
        "public_post_mode": "draft_only",
        "incident_status": "degraded"
      }
    }
  }'

This example creates an API beat that drafts a customer-facing incident after three failed checks in a row, while still surfacing an internal admin signal immediately.

Trigger a beat run now​

curl -X POST "$STATIBEAT_BASE_URL/api/v1/orgs/1/pages/42/admin/synthetic-monitors/55/run" \
  -H "Authorization: Bearer $STATIBEAT_TOKEN"
curl -X POST "$STATIBEAT_BASE_URL/api/v1/orgs/1/pages/42/subscribers/preferences/request-access" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ops@example.com",
    "name": "Ops Team"
  }'

Open management resources with a magic token​

curl "$STATIBEAT_BASE_URL/api/v1/orgs/1/pages/42/manage/resources" \
  -H "X-Magic-Token: $STATIBEAT_MAGIC_TOKEN"

Generate a Terraform export bundle​

curl -X POST "$STATIBEAT_BASE_URL/api/v1/orgs/1/pages/42/admin/terraform-export" \
  -H "Authorization: Bearer $STATIBEAT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "feature_groups": ["hierarchy", "status_definitions", "lifecycle", "maintenance_lifecycle", "settings"],
    "terraform_version": "1.8.5",
    "provider_version": "~> 1.0",
    "include_import_blocks": true,
    "include_import_script": true,
    "lock_plan": {
      "enable_after_import": true,
      "locked_features": ["hierarchy", "status_definitions", "settings"]
    }
  }'

The export response includes download_url and manifest_url, which you can use to fetch the zip archive and inspect the generated manifest before enabling Terraform lockdown.

Notes​

  • Use bearer tokens for automation and admin workflows.
  • Use magic tokens for management-link and delegated-access flows.
  • Scoped /api/v1/orgs/{org_id}/pages/{page_id}/... routes are the canonical API surface.