Incidents API

The Incidents API gives you programmatic, read-only access to the incidents recorded for your monitors and servers. Use it to pull the current incident state into dashboards, alerting pipelines, or audit tooling.

Incidents are created and managed three ways:

• Automatically when a monitor goes down or the anomaly detector flags a server.
• Manually from Dashboard → Incidents.

The REST API exposes list and get operations only. Creating, updating, acknowledging, and resolving incidents are performed in the dashboard (see Managing incidents below).

Base URL and version

All endpoints live under the /v1 prefix on the API host:

https://api.statusradar.dev/v1

https://statusradar.dev/v1 is an accepted alias.

Authentication

The Incidents API is part of the User API and authenticates with a user API token sent as a Bearer token:

Authorization: Bearer YOUR_API_TOKEN

Generate a token at Dashboard → Settings → API. Tokens are scoped to the resources your account and team own — you only ever see incidents for entities you have access to. Clients that cannot set the Authorization header may use the X-API-Token: YOUR_API_TOKEN header instead.

See API Authentication for full details.

Rate limiting

User API requests are limited to 60 requests per minute per token. When you exceed the limit the API responds with HTTP 429 and a Retry-After: 60 header. Back off and retry.

Endpoints

List incidents

GET /v1/incidents

Returns the incidents visible to your token, most recent first.

Query parameters

Example request

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  "https://api.statusradar.dev/v1/incidents?status=active&severity=critical"

Example response

{
  "success": true,
  "data": [
    {
      "id": 482,
      "entity_type": "monitor",
      "entity_id": 117,
      "entity_name": "API Gateway",
      "entity_target": "https://api.example.com/health",
      "title": "API Gateway is down",
      "description": "Health check returned 503 from all probe locations.",
      "severity": "critical",
      "status": "investigating",
      "detection_source": "monitor",
      "started_at": "2026-06-23T09:14:02Z",
      "resolved_at": null,
      "duration_minutes": 27
    }
  ],
  "page": 1,
  "total": 1,
  "total_pages": 1
}

Get an incident

GET /v1/incidents/{id}

Returns a single incident, including its chronological updates. For monitor incidents the response also includes the check results recorded during the incident window. Returns 404 if the incident does not exist or is not visible to your token.

Example request

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  https://api.statusradar.dev/v1/incidents/482

Example response

{
  "success": true,
  "data": {
    "id": 482,
    "entity_type": "monitor",
    "entity_id": 117,
    "entity_name": "API Gateway",
    "entity_target": "https://api.example.com/health",
    "title": "API Gateway is down",
    "description": "Health check returned 503 from all probe locations.",
    "severity": "critical",
    "status": "monitoring",
    "detection_source": "monitor",
    "started_at": "2026-06-23T09:14:02Z",
    "resolved_at": null,
    "duration_minutes": 41,
    "updates": [
      {
        "id": 1204,
        "status": "monitoring",
        "message": "Rolled back the bad deploy; error rate is dropping.",
        "user_name": "Jane Ops",
        "created_at": "2026-06-23T09:48:00Z"
      },
      {
        "id": 1201,
        "status": "investigating",
        "message": "Confirmed 503s across all locations, investigating.",
        "user_name": "Jane Ops",
        "created_at": "2026-06-23T09:16:00Z"
      }
    ]
  }
}

Incident fields

Update object

Severity

Manually created incidents accept minor, major, and critical. warning and info are used by automatic and anomaly-detected incidents.

Status

Incidents follow this lifecycle:

A status filter of active matches every incident whose status is not resolved.

Managing incidents

The REST API is read-only. To create, update, acknowledge, or resolve incidents, use the dashboard at Dashboard → Incidents (/dashboard/incidents):

• Create — open an incident manually against one of your monitors with a title, description, severity, and initial status.
• Update — post a status update with a message; setting the status to resolved closes the incident.
• Acknowledge — mark an active incident as being handled.
• Resolve — close the incident and restore the entity to a healthy state.

When a monitor recovers, its open incident is resolved automatically.

Error responses

Errors return a non-2xx status with a JSON body:

{
  "success": false,
  "error": "Invalid token",
  "message": "The provided API token is invalid or has been revoked"
}

Next Steps

• API Authentication — token types and how to send them
• API Overview — the full API surface
• Alerts overview — turn incidents into notifications
• Anomaly detection — how server incidents are detected