Beacon

API Reference

API: Incidents

Create, update, and manage incidents programmatically. All endpoints require a workspace API token. See Authentication for setup.

Create an incident

POST /api/v1/pages/{pageSlug}/incidents

Creates a new incident on the specified status page. If a message is provided, it becomes the first timeline update.

Request body

Field Type Required Description
title string Yes Short summary of the incident. Max 255 characters.
impact string No One of: none, minor, major, critical. Defaults to none.
state string No One of: investigating, identified, monitoring, resolved. Defaults to investigating.
message string No Initial update message. If provided, creates the first timeline entry.

Example request

curl -X POST https://usebeacon.pro/api/v1/pages/acme-cloud/incidents \
  -H "Authorization: Bearer bkn_live_a1b2c3d4e5f6..." \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "title": "Elevated API latency in US-East",
    "impact": "minor",
    "state": "investigating",
    "message": "We are observing p99 latency above 2s for API requests routed through US-East. Investigating the root cause."
  }'

Example response

Status: 201 Created

{
  "data": {
    "id": "9f1a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
    "title": "Elevated API latency in US-East",
    "impact": "minor",
    "state": "investigating",
    "resolved": false,
    "resolved_at": null,
    "created_at": "2026-04-04T14:32:00Z",
    "updated_at": "2026-04-04T14:32:00Z",
    "updates": [
      {
        "id": "upd_7e8f9a0b1c2d",
        "message": "We are observing p99 latency above 2s for API requests routed through US-East. Investigating the root cause.",
        "created_at": "2026-04-04T14:32:00Z"
      }
    ]
  }
}

Update an incident

PATCH /api/v1/incidents/{incidentId}

Updates the properties of an existing incident. Only the fields you include in the request body are changed; omitted fields remain unchanged.

Updatable fields

Field Type Description
title string Update the incident title.
impact string Change the impact level.
state string Transition to a new state.
resolved boolean Set to true to mark the incident as resolved and set the resolved_at timestamp.

Example request

curl -X PATCH https://usebeacon.pro/api/v1/incidents/9f1a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c \
  -H "Authorization: Bearer bkn_live_a1b2c3d4e5f6..." \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "state": "identified",
    "impact": "major"
  }'

Example response

Status: 200 OK

{
  "data": {
    "id": "9f1a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
    "title": "Elevated API latency in US-East",
    "impact": "major",
    "state": "identified",
    "resolved": false,
    "resolved_at": null,
    "created_at": "2026-04-04T14:32:00Z",
    "updated_at": "2026-04-04T14:48:00Z"
  }
}

Resolving an incident

To resolve an incident in a single call, set both state and resolved:

curl -X PATCH https://usebeacon.pro/api/v1/incidents/9f1a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c \
  -H "Authorization: Bearer bkn_live_a1b2c3d4e5f6..." \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "state": "resolved",
    "resolved": true
  }'

This sets resolved_at to the current timestamp and moves the incident to history on the public page.

Add an incident update

POST /api/v1/incidents/{incidentId}/updates

Adds a new timeline entry to an existing incident. This triggers subscriber notifications.

Request body

Field Type Required Description
message string Yes The update text. Displayed in the incident timeline.

Example request

curl -X POST https://usebeacon.pro/api/v1/incidents/9f1a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c/updates \
  -H "Authorization: Bearer bkn_live_a1b2c3d4e5f6..." \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "message": "We identified a misconfigured routing rule in the US-East load balancer. A corrected configuration is being deployed now. ETA: 10 minutes."
  }'

Example response

Status: 201 Created

{
  "data": {
    "id": "upd_3c4d5e6f7a8b",
    "incident_id": "9f1a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
    "message": "We identified a misconfigured routing rule in the US-East load balancer. A corrected configuration is being deployed now. ETA: 10 minutes.",
    "created_at": "2026-04-04T14:52:00Z"
  }
}

Status codes

Code Meaning
201 Incident or update created successfully.
200 Incident updated successfully.
401 Missing or invalid API token.
404 Page or incident not found.
422 Validation error (e.g. missing title, invalid impact value).
429 Rate limit exceeded.

See Errors & Rate Limits for details on error response format and handling.