> For clean Markdown of this page, append .md to its URL. For the complete documentation index, see https://www.superagent.sh/llms.txt.


List infrastructure incidents, retrieve evidence, and update review status through the REST API and MCP.

# Incidents

Use an organization API key with [Bearer authentication](https://www.superagent.sh/docs/api) to handle
[Infrastructure](https://www.superagent.sh/docs/infrastructure-log-sources) incidents in your own workflows.
Every operation is restricted to the key's organization. Incidents represent
security-one threat assessments meeting the configured confidence threshold
(default 0.8). Routine and inconclusive analysis results are excluded.
A high-confidence threat with unknown impact can appear for review without
sending a webhook. Later inconclusive results do not overwrite its detection evidence.

## List incidents

`GET /api/v1/incidents` returns summaries ordered by latest activity, then ID,
both descending. The response contains `data` and `pagination` with `limit`,
`offset`, `total`, and `has_more`.

| Query parameter | Values |
| --- | --- |
| `limit` | Integer from 1 to 100; default 25 |
| `offset` | Integer from 0 to 1,000,000; default 0 |
| `triage_status` | `new`, `triaging`, `in_review`, `resolved` |
| `triage_resolution` | `fixed`, `accepted_risk`, `false_positive`, `wont_fix` |
| `severity` | `unknown`, `low`, `medium`, `high`, `critical` |
| `source_id` | Source UUID |
| `application_group` | Exact application group, up to 100 characters |
| `environment` | Exact environment, up to 50 characters |
| `q` | Literal search text, up to 1,000 characters |

Unknown or repeated query parameters return `400`. Without filters, the list
includes all review states, including resolved incidents.

```bash
curl "$SUPERAGENT_URL/api/v1/incidents?triage_status=new&severity=high" \
  -H "Authorization: Bearer $SUPERAGENT_API_KEY"
```

Each summary includes the incident UUID, title, source ID and name, application
group, environment, behavior, severity, assessment `status` and `revision`,
`triage_status`, `triage_resolution`, `triage_version`, first/last seen timestamps,
and a relative `dashboard_url` opening its detail panel.

## Get an incident

`GET /api/v1/incidents/{incident_id}` returns `{ "data": { ... } }` with the
summary fields plus the security-one `assessment`, sanitized log `evidence`, and:

| Field | Contents |
| --- | --- |
| `triage` | Review status, resolution, version, update timestamp, and actor (`user` or `api_key`, with ID), or a null actor before review |
| `revisions` | Latest 50 assessment revisions, newest first |
| `review_history` | Latest 100 review changes, newest version first; includes actor type/ID, previous and new states, comment, and time |
| `webhook_deliveries` | Latest 50 webhook events, each with delivery status, attempt count, response status, and error |
| `history_limits` | The limits applied to those three collections |

Keys, webhook credentials, and private replay object paths are excluded. The
collections are recent context, not an export of the complete audit history.

## Update incident review

`PATCH /api/v1/incidents/{incident_id}` changes manual review state and returns
the full incident under `data`. Fetch the incident first and send its current
`triage_version` to protect against concurrent reviewers.

```bash
curl -X PATCH "$SUPERAGENT_URL/api/v1/incidents/$INCIDENT_ID" \
  -H "Authorization: Bearer $SUPERAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"triage_status":"resolved","triage_resolution":"false_positive","triage_version":1,"comment":"Expected activity from our deployment."}'
```

| Field | Requirement |
| --- | --- |
| `triage_status` | Required: `new`, `in_review`, or `resolved` |
| `triage_resolution` | Required for `resolved`: `fixed`, `accepted_risk`, `false_positive`, or `wont_fix`. Omit or use null for other states. |
| `triage_version` | Required positive integer from the latest list or detail response |
| `comment` | Optional audit comment, up to 2,000 characters |

`triaging` is an automated state and cannot be set manually. Resolving an
incident suppresses further webhook escalation for it until reopened. Review
updates preserve the security-one assessment, evidence, severity, and assessment
status. Each state change increments `triage_version` and records the validated
API key ID in immutable review history. The ID remains after key revocation.
Submitting the current state at the current version is a no-op; it does not
append a comment or audit record.

A stale version returns `409` with error code `conflict`; fetch the latest
incident, review the intervening changes, and retry with that version. Invalid
input returns `400`, missing or revoked credentials return `401`, and unknown
or other-organization IDs both return `404`. Errors use the standard
`{ "error": { "code": "...", "message": "..." } }` envelope.

## MCP tools

The [MCP server](https://www.superagent.sh/docs/mcp) exposes the same operations as `list_incidents`,
`get_incident`, and `update_incident_triage`. Use `incident_id` for the latter
two and the same filters and review fields as the REST API. For an update,
read the current version with `get_incident` before calling
`update_incident_triage`. Authentication supplies the organization and actor.

---
Source: https://www.superagent.sh/docs/api/incidents
Index: https://www.superagent.sh/llms.txt