> ## Documentation Index
> Fetch the complete documentation index at: https://docs.meshai.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Incident Reporting

> EU AI Act Article 73 serious incident reporting with deadline tracking

EU AI Act Article 73 requires providers and deployers to report serious incidents involving high-risk AI systems to the relevant market surveillance authority. MeshAI provides structured incident creation, deadline tracking, and authority notification support.

## What Is a Serious Incident?

Article 3(49) defines a serious incident as an event that directly or indirectly leads to or could have led to:

* Death or serious damage to health
* Serious and irreversible disruption of critical infrastructure management
* Breach of fundamental rights obligations

## Severity

Incidents are recorded with one of four severity levels:

| Severity   | Use for                                                   |
| ---------- | --------------------------------------------------------- |
| `low`      | Minor issue, limited impact                               |
| `medium`   | Moderate impact, contained                                |
| `high`     | Significant impact requiring prompt attention             |
| `critical` | Severe impact - potential Article 73 reporting obligation |

## Reporting Deadlines

| Deadline    | Condition                            | Timeframe                  |
| ----------- | ------------------------------------ | -------------------------- |
| **2 days**  | `is_widespread` is `true`            | Within 2 days of creation  |
| **15 days** | `is_widespread` is `false` (default) | Within 15 days of creation |

MeshAI automatically calculates `notification_deadline` when the incident is created, based on `is_widespread`.

## Create an Incident

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.meshai.dev/api/v1/incidents \
    -H "Authorization: Bearer msh_YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "agent_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
      "title": "Discriminatory output in hiring agent",
      "description": "The HR screening agent systematically ranked female candidates lower than male candidates with equivalent qualifications over a 2-week period.",
      "severity": "high",
      "affected_persons": "Approximately 120 job applicants",
      "reported_by": "user@company.com",
      "is_widespread": false
    }'
  ```

  ```python SDK theme={null}
  from meshai import MeshAI

  client = MeshAI(api_key="msh_...")

  incident = client.create_incident(
      agent_id="01ARZ3NDEKTSV4RRFFQ69G5FAV",
      title="Discriminatory output in hiring agent",
      description="The HR screening agent systematically ranked female candidates lower...",
      severity="high",
      affected_persons="Approximately 120 job applicants",
      reported_by="user@company.com",
      is_widespread=False,
  )
  ```
</CodeGroup>

`reported_by` is required and is bound to the authenticated API key. `anomaly_event_id` is an optional integer linking the incident to an ML-detected anomaly. `root_cause` and `corrective_actions` are not create-time fields - they're set later via the update endpoint below.

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "id": 12,
      "agent_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
      "title": "Discriminatory output in hiring agent",
      "description": "The HR screening agent systematically ranked female candidates lower...",
      "severity": "high",
      "status": "reported",
      "affected_persons": "Approximately 120 job applicants",
      "root_cause": null,
      "corrective_actions": null,
      "anomaly_event_id": null,
      "authority_notified": false,
      "authority_notified_at": null,
      "notification_deadline": "2026-04-01T10:00:00Z",
      "reported_by": "user@company.com (key:a1b2c3d4)",
      "reported_at": "2026-03-17T10:00:00Z",
      "resolved_at": null
    }
  }
  ```
</ResponseExample>

## Incident Statuses

| Status          | Description                                          |
| --------------- | ---------------------------------------------------- |
| `reported`      | Incident created, not yet under active investigation |
| `investigating` | Root cause analysis in progress                      |
| `resolved`      | Investigation complete, incident resolved            |
| `notified`      | Authority has been notified                          |

## Track an Incident

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.meshai.dev/api/v1/incidents/12 \
    -H "Authorization: Bearer msh_YOUR_API_KEY"
  ```

  ```python SDK theme={null}
  incident = client.get_incident(12)
  ```
</CodeGroup>

## Update an Incident

Use the update endpoint to record investigation progress, root cause, corrective actions, and authority notification:

<CodeGroup>
  ```bash curl theme={null}
  curl -X PATCH https://api.meshai.dev/api/v1/incidents/12 \
    -H "Authorization: Bearer msh_YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "status": "resolved",
      "root_cause": "Training data contained historical hiring bias that was not sufficiently mitigated.",
      "corrective_actions": "All 120 affected applications have been manually re-reviewed. 8 candidates were re-ranked and contacted."
    }'
  ```

  ```python SDK theme={null}
  client.update_incident(
      12,
      status="resolved",
      root_cause="Training data contained historical hiring bias.",
      corrective_actions="All 120 affected applications manually re-reviewed.",
  )
  ```
</CodeGroup>

Setting `status: "resolved"` records `resolved_at` automatically.

## Notify the Authority

There is no dedicated "notify authority" endpoint. Recording that you've notified the relevant market surveillance authority is the same update endpoint, setting `authority_notified: true`:

<CodeGroup>
  ```bash curl theme={null}
  curl -X PATCH https://api.meshai.dev/api/v1/incidents/12 \
    -H "Authorization: Bearer msh_YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "status": "notified",
      "authority_notified": true
    }'
  ```

  ```python SDK theme={null}
  client.update_incident(12, status="notified", authority_notified=True)
  ```
</CodeGroup>

Setting `authority_notified: true` records `authority_notified_at` automatically. `IncidentUpdate` accepts `status`, `root_cause`, `corrective_actions`, and `authority_notified` - track the authority name, contact details, and any filing notes in your own systems, since MeshAI does not have dedicated fields for them.

## Export an Evidence Pack

One call assembles the incident report plus the telemetry evidence recorded around it into a single document shaped for an Article 73 filing:

```bash theme={null}
curl "https://api.meshai.dev/api/v1/incidents/12/evidence-pack?window_hours=24" \
  -H "Authorization: Bearer msh_YOUR_API_KEY"
```

The pack contains:

| Section                       | Contents                                                                                      |
| ----------------------------- | --------------------------------------------------------------------------------------------- |
| `incident`                    | The full incident report                                                                      |
| `agent`                       | Identity snapshot including risk classification; preserved even if the agent is later deleted |
| `evidence.policy_evaluations` | Policy checks in the window, with policy names and fail count                                 |
| `evidence.approvals`          | Approval requests with the human decisions inlined (who decided, when, why)                   |
| `evidence.anomalies`          | Anomaly events in the window, including acknowledgement timestamps                            |
| `evidence.usage`              | Token and cost totals plus a by-model breakdown                                               |
| `evidence.audit_events`       | Agent-scoped audit trail, plus operator actions on the incident's anomalies                   |
| `linked_anomaly`              | The ML detection that triggered the incident, if linked                                       |
| `article_73`                  | Deadline status: days remaining, overdue flag, and whether notification was late              |

Window semantics that matter for evidence:

* The telemetry window (`window_hours`, default 24, max 168) is anchored at the incident's `reported_at` and looks backward: the lead-up to the incident.
* The audit trail additionally runs through generation time, because the human response to an incident happens after it is reported. Acknowledgements, kill switches, and reclassifications are part of the record.
* `deadline_days_remaining` uses a ceiling, so 47 hours remaining reads as 2 days and a 1-hour lapse reads as 0 days with `overdue: true`.
* Record lists are capped at 200 entries per category with uncapped totals, so truncation is always detectable (`total` exceeds the record count).

<Note>
  Evidence pack export requires the Professional plan or above, matching the audit trail export entitlement. Starter and free tenants receive a 402 with an upgrade path.
</Note>

## Dashboard Alerts

The MeshAI dashboard shows:

* **Active incidents** with countdown timers to reporting deadlines
* **Overdue incidents** highlighted in red
* **Deadline approaching** warnings 48 hours before the deadline