> For the complete documentation index, see [llms.txt](https://docs.kyvvu.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kyvvu.com/platform/incidents.md).

# Incident Management

**What you'll learn:** How incidents are created, the incident lifecycle, and how to triage and resolve them.

***

## What is an incident?

An **incident** is a policy violation record. When the engine evaluates a step and a policy returns `warn` or `block`, an incident is created and sent to the configured incident sink (by default, the same destination as the behavioral trace — see [Configuring the incident sink](#configuring-the-incident-sink)).

Incidents provide the audit trail — they record what was violated, when, by which agent, and in which task.

## Incident lifecycle

```
open  →  active  →  resolved
                 →  ignored
```

| Status       | Meaning                                                                                  |
| ------------ | ---------------------------------------------------------------------------------------- |
| **open**     | Newly created. No human has reviewed it.                                                 |
| **active**   | Acknowledged by a team member. Under investigation or remediation.                       |
| **resolved** | The violation has been addressed — code fixed, policy adjusted, or root cause mitigated. |
| **ignored**  | Reviewed and determined to be a false positive or acceptable risk.                       |

## Incident data

Each incident includes:

| Field        | Description                                                     |
| ------------ | --------------------------------------------------------------- |
| `agent_id`   | The agent that triggered the violation.                         |
| `scope`      | `step_execution` or `agent_registration`.                       |
| `task_id`    | The task in which the violation occurred (for step violations). |
| `step_name`  | The step that was evaluated.                                    |
| `step_type`  | The behaviour type.                                             |
| `action`     | `warn` or `block`.                                              |
| `risk_score` | The aggregate risk score (0.0 to 1.0).                          |
| `violations` | List of violated policies with name, severity, and details.     |
| `timestamp`  | When the violation occurred.                                    |

## Dashboard workflow

1. Navigate to **Incidents** in the sidebar.
2. Filter by status, agent, severity, or time range.
3. Click an incident to see full details.
4. Use the action buttons:
   * **Resolve** — mark as addressed.
   * **Ignore** — mark as false positive.
   * **Reactivate** — reopen a resolved or ignored incident.

## API endpoints

| Method | Path                                | Description                  |
| ------ | ----------------------------------- | ---------------------------- |
| `GET`  | `/api/v1/incidents`                 | List incidents (filterable). |
| `GET`  | `/api/v1/incidents/{id}`            | Get incident details.        |
| `PUT`  | `/api/v1/incidents/{id}/resolve`    | Resolve incident.            |
| `PUT`  | `/api/v1/incidents/{id}/ignore`     | Ignore incident.             |
| `PUT`  | `/api/v1/incidents/{id}/reactivate` | Reactivate incident.         |

Incidents are never deleted — they form part of the immutable audit trail.

## Configuring the incident sink

Incidents follow the same **location + format** sink model as behavioral traces. By default the incident sink **inherits the trace sink** (`KV_LOG_LOCATION` / `KV_LOG_FORMAT`), substituting the `…/api/v1/incidents` path for the Kyvvu `kv` format. So if traces already flow to the platform, incidents do too — no extra configuration needed.

To route incidents to a **different** destination, set `KV_INCIDENT_LOCATION` (and optionally `KV_INCIDENT_FORMAT`):

```bash
# Send incidents to the platform explicitly (kv format → …/api/v1/incidents)
export KV_INCIDENT_LOCATION=https://platform.kyvvu.com
export KV_INCIDENT_FORMAT=kv
```

`KV_INCIDENT_LOCATION` accepts the same values as `KV_LOG_LOCATION` — an HTTP URL, a file path (JSONL), `stdout`, or `none`/empty to disable:

```bash
# Local debugging — print incident JSON to stdout
export KV_INCIDENT_LOCATION=stdout
```

```bash
# Emit a standalone kyvvu.incident OpenTelemetry span
export KV_INCIDENT_LOCATION=http://collector:4318
export KV_INCIDENT_FORMAT=otlp
```

***

## Next steps

* [Dashboard Guide](/platform/dashboard.md) — navigate the dashboard
* [Reports](/platform/reports.md) — generate audit reports from incident data
* [Policies and Rules](/core-concepts/policies.md) — understand how violations are determined


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.kyvvu.com/platform/incidents.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.