API Reference

API: Components

Update component statuses programmatically to reflect the current health of your services. All endpoints require a workspace API token. See Authentication for setup.

Update component status

PATCH /api/v1/pages/{pageSlug}/components/{componentId}

Updates the status (and optionally the description) of a specific component on a status page. The change is reflected immediately on the public page and affects the overall status rollup.

Request body

Field	Type	Required	Description
`status`	string	Yes	The new status for the component. See valid values below.
`description`	string	No	Optional description shown beneath the component name on the public page.

Valid status values

Value	Display	Description
`operational`	Operational	The component is functioning normally.
`degraded`	Degraded	Performance is below normal thresholds.
`degraded_performance`	Degraded Performance	Alias for degraded. Accepted for compatibility.
`partial_outage`	Partial Outage	Some users or features are unavailable.
`major_outage`	Major Outage	The component is completely unavailable.
`maintenance`	Under Maintenance	The component is undergoing planned maintenance.
`unknown`	Unknown	Status has not been determined.

Sending an invalid status value will return a 422 Validation Error. The status field is case-sensitive and must exactly match one of the values above.

Example

Request

Set the "API" component to partial_outage:

curl -X PATCH https://usebeacon.pro/api/v1/pages/acme-cloud/components/comp_8a9b0c1d2e3f \
  -H "Authorization: Bearer bkn_live_a1b2c3d4e5f6..." \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "status": "partial_outage",
    "description": "Intermittent 503 errors for some API endpoints"
  }'

Response

Status: 200 OK

{
  "data": {
    "id": "comp_8a9b0c1d2e3f",
    "name": "API",
    "description": "Intermittent 503 errors for some API endpoints",
    "status": "partial_outage",
    "order": 1,
    "created_at": "2026-03-15T10:00:00Z",
    "updated_at": "2026-04-04T15:10:00Z"
  }
}

Restoring to operational

After an incident is resolved, set the component back to operational:

curl -X PATCH https://usebeacon.pro/api/v1/pages/acme-cloud/components/comp_8a9b0c1d2e3f \
  -H "Authorization: Bearer bkn_live_a1b2c3d4e5f6..." \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "status": "operational",
    "description": null
  }'

Setting description to null clears any previously set description text.

Tip: If the component is linked to a monitor, the monitor will automatically restore the component to operational when it detects recovery. You only need to update component status manually if you are not using monitors.

How component status affects page health

The overall page status shown in the banner at the top of the public page is computed from the worst-case component status. The priority order from most severe to least:

major_outage  >  partial_outage  >  degraded  >  maintenance  >  operational

For example, if you have three components -- API (operational), Dashboard (degraded), and Workers (operational) -- the overall page status will be "Some systems degraded." If you then set API to major_outage, the overall status changes to "Major system outage."

This rollup is computed in real time. Updating a component status via the API instantly updates the banner on the public page.

Status codes

Code	Meaning
`200`	Component updated successfully.
`401`	Missing or invalid API token.
`404`	Page or component not found.
`422`	Validation error (e.g. invalid status value).
`429`	Rate limit exceeded.