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

# Incidents API — full lifecycle management for incidents

> Create, resolve, and analyse incident tickets. Access AI five-whys, remediation suggestions, and stakeholder updates from one API.

The Incidents API is the operational core of Scrubbe. Use it to open a ticket the moment an alert fires, progress it through investigation and mitigation, attach comments and messages as responders collaborate, and finally resolve it — optionally generating a customer knowledge-base article in the same call. Once an incident is recorded, the AI endpoints surface root cause analyses, remediation steps, and pre-drafted stakeholder communications without leaving the API.

<Note>
  All endpoints require `Authorization: Bearer <token>`. Tokens are workspace-scoped and can be rotated from **Settings → API Keys**.
</Note>

**Base path:** `https://your-api-domain.com/api/v1/incident-ticket`

***

## Generate an incident ID

Fetch a unique, pre-formatted incident ID before creating the ticket. Use this when you need the identifier in an external system ahead of the actual record creation.

`GET /generate-id`

```http theme={null}
GET /api/v1/incident-ticket/generate-id
Authorization: Bearer <token>
```

**Response**

```json theme={null}
{
  "success": true,
  "message": "ID generated",
  "data": { "id": "INC-20260522-0041" }
}
```

<ResponseField name="id" type="string" required>
  Unique incident identifier in the format `INC-YYYYMMDD-XXXX`.
</ResponseField>

***

## Create an incident

Open a new incident ticket. `summary` and `priority` are required; all other fields are optional.

`POST /`

<ParamField body="summary" type="string" required>
  Short, human-readable title for the incident (e.g. `"Payment service down"`).
</ParamField>

<ParamField body="priority" type="string" required>
  Severity level. One of `LOW`, `MEDIUM`, `HIGH`, or `CRITICAL`.
</ParamField>

<ParamField body="status" type="string" default="OPEN">
  Initial lifecycle status. One of `OPEN`, `ACKNOWLEDGED`, `INVESTIGATION`, `MITIGATED`, `RESOLVED`, or `CLOSED`.
</ParamField>

<ParamField body="source" type="string">
  Origin of the incident (e.g. `"MONITORING"`, `"CUSTOMER"`, `"INTERNAL"`).
</ParamField>

<ParamField body="serviceArea" type="string">
  The product or service area affected (e.g. `"payments"`).
</ParamField>

<ParamField body="environment" type="string">
  Target environment (e.g. `"production"`, `"staging"`).
</ParamField>

<ParamField body="region" type="string">
  Cloud or geographic region (e.g. `"us-east-1"`).
</ParamField>

<ParamField body="assignedToEmail" type="string">
  Email address of the on-call engineer to assign this ticket to.
</ParamField>

<ParamField body="description" type="string">
  Customer-facing description of the incident.
</ParamField>

<ParamField body="techDescription" type="string">
  Internal technical description for the engineering team.
</ParamField>

<ParamField body="impactSummary" type="string">
  Brief summary of user or business impact.
</ParamField>

<ParamField body="blastRadius" type="string">
  Estimated scope of impact (e.g. `"100% of users"`, `"EU region only"`).
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://your-api-domain.com/api/v1/incident-ticket \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    -d '{
      "summary": "Payment service down",
      "priority": "CRITICAL",
      "status": "OPEN",
      "source": "MONITORING",
      "serviceArea": "payments",
      "environment": "production",
      "region": "us-east-1",
      "assignedToEmail": "oncall@example.com",
      "description": "Customers cannot complete checkout.",
      "techDescription": "stripe-service pod crash-looping in k8s cluster.",
      "impactSummary": "100% of checkout requests failing since 14:32 UTC.",
      "blastRadius": "100% of users"
    }'
  ```

  ```python Python theme={null}
  import requests

  resp = requests.post(
      "https://your-api-domain.com/api/v1/incident-ticket",
      headers={"Authorization": "Bearer <token>"},
      json={
          "summary": "Payment service down",
          "priority": "CRITICAL",
          "status": "OPEN",
          "source": "MONITORING",
          "serviceArea": "payments",
          "environment": "production",
          "region": "us-east-1",
          "assignedToEmail": "oncall@example.com",
          "description": "Customers cannot complete checkout.",
          "techDescription": "stripe-service pod crash-looping in k8s cluster.",
          "impactSummary": "100% of checkout requests failing since 14:32 UTC.",
          "blastRadius": "100% of users",
      },
  )
  print(resp.json())
  ```
</CodeGroup>

**Response**

```json theme={null}
{
  "success": true,
  "message": "Incident created",
  "data": {
    "id": "INC-20260522-0041",
    "summary": "Payment service down",
    "priority": "CRITICAL",
    "status": "OPEN",
    "createdAt": "2026-05-22T14:33:00Z"
  }
}
```

***

## List incidents

Returns a paginated list of incident tickets, ordered by creation date descending. Supports filtering by status, priority, environment, and date range.

`GET /`

<ParamField query="page" type="number" default="1">
  Page number.
</ParamField>

<ParamField query="limit" type="number" default="20">
  Items per page (max 100).
</ParamField>

<ParamField query="status" type="string">
  Filter by status: `OPEN`, `ACKNOWLEDGED`, `INVESTIGATION`, `MITIGATED`, `RESOLVED`, or `CLOSED`.
</ParamField>

<ParamField query="priority" type="string">
  Filter by priority: `LOW`, `MEDIUM`, `HIGH`, or `CRITICAL`.
</ParamField>

***

## Get incident analytics

Returns aggregate metrics across all incidents — useful for dashboards and SLA reporting. Includes total counts by status, mean time to acknowledge (MTTA), and mean time to resolve (MTTR).

`GET /analytics`

<ResponseField name="total" type="number">Total incident count in the workspace.</ResponseField>
<ResponseField name="byStatus" type="object">Count broken down by each status value.</ResponseField>
<ResponseField name="byPriority" type="object">Count broken down by each priority value.</ResponseField>
<ResponseField name="meanTimeToAcknowledge" type="number">Average acknowledgement time in minutes.</ResponseField>
<ResponseField name="meanTimeToResolve" type="number">Average resolution time in minutes.</ResponseField>

***

## Get an incident

`GET /:id`

<ParamField path="id" type="string" required>
  The incident ID.
</ParamField>

***

## Update an incident

Accepts the same fields as `POST /`. Only provided fields are updated.

`PUT /:id`

<ParamField path="id" type="string" required>
  The incident ID to update.
</ParamField>

***

## Delete an incident

`DELETE /:id`

<ParamField path="id" type="string" required>
  The incident ID to delete.
</ParamField>

<Warning>
  Deleting an incident is permanent. All associated comments, messages, and AI analyses are also removed. Consider moving the incident to `CLOSED` status instead.
</Warning>

***

## Add a comment

Post a comment to an incident ticket. Comments are visible to all team members with access to the ticket. Markdown is supported in `content`.

`POST /comment`

<ParamField body="ticketId" type="string" required>
  The incident ticket ID to comment on.
</ParamField>

<ParamField body="content" type="string" required>
  The comment body. Markdown is supported.
</ParamField>

***

## List comments

Retrieve all comments for an incident ticket in chronological order.

`GET /comment/:ticketId`

<ParamField path="ticketId" type="string" required>
  The incident ticket ID.
</ParamField>

***

## List messages

Retrieve the message thread for an incident ticket. Messages are distinct from comments — they typically represent system events, status transitions, and automated notifications.

`GET /message/:ticketId`

<ParamField path="ticketId" type="string" required>
  The incident ticket ID.
</ParamField>

***

## Resolve an incident

Mark an incident as `RESOLVED` and trigger any configured post-resolution hooks.

`POST /resolve/:id`

<ParamField path="id" type="string" required>
  The incident ID to resolve.
</ParamField>

***

## Resolve and generate a customer KB article

Resolve the incident and automatically draft a knowledge-base article for your customer-facing help center based on the incident summary and resolution steps.

`POST /resolve/customer-kb/:id`

<ParamField path="id" type="string" required>
  The incident ID.
</ParamField>

***

## AI: five-whys analysis

Trigger Ezra AI to perform a five-whys root cause analysis on the incident. Results are computed and returned synchronously.

`GET /resolve/ai/five-whys/:id`

<ParamField path="id" type="string" required>
  The incident ID to analyse.
</ParamField>

**Response**

```json theme={null}
{
  "success": true,
  "data": {
    "why1": "Checkout requests started failing",
    "why2": "stripe-service returned 503 errors",
    "why3": "Connection pool was exhausted",
    "why4": "Upstream gateway latency increased 10x",
    "why5": "No circuit breaker on the gateway call",
    "rootCause": "Missing circuit breaker on third-party payment gateway allowed slow responses to exhaust the connection pool."
  }
}
```

<ResponseField name="why1" type="string">First causal layer — observable symptom.</ResponseField>
<ResponseField name="why2" type="string">Second causal layer.</ResponseField>
<ResponseField name="why3" type="string">Third causal layer.</ResponseField>
<ResponseField name="why4" type="string">Fourth causal layer.</ResponseField>
<ResponseField name="why5" type="string">Fifth causal layer — root cause.</ResponseField>
<ResponseField name="rootCause" type="string">Synthesised root cause statement.</ResponseField>

***

## AI: remediation suggestion

Ask Ezra AI for recommended remediation steps based on the incident context and historical failure patterns.

`GET /resolve/ai/suggestion/:id`

<ParamField path="id" type="string" required>
  The incident ID.
</ParamField>

***

## AI: stakeholder update

Generate a pre-drafted stakeholder communication tailored for a non-technical audience.

`GET /resolve/ai/stakeholder/:id`

<ParamField path="id" type="string" required>
  The incident ID.
</ParamField>

***

## Generate a PDF report

Export an incident as a formatted PDF suitable for post-incident reviews or audit trails. The response is a binary PDF stream.

`POST /generate-pdf`

<ParamField body="incidentId" type="string" required>
  The incident ID to export.
</ParamField>

```bash cURL theme={null}
curl -X POST https://your-api-domain.com/api/v1/incident-ticket/generate-pdf \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"incidentId": "INC-20260522-0041"}' \
  --output incident-report.pdf
```

<Note>
  The response body is a binary PDF stream with `Content-Type: application/pdf`. Write it directly to a file rather than parsing it as JSON.
</Note>

***

## Status and priority reference

| Status          | Meaning                                               |
| --------------- | ----------------------------------------------------- |
| `OPEN`          | Newly created, not yet acknowledged.                  |
| `ACKNOWLEDGED`  | An engineer has seen and accepted the incident.       |
| `INVESTIGATION` | Active investigation underway.                        |
| `MITIGATED`     | Impact reduced but root cause not yet fully resolved. |
| `RESOLVED`      | Incident fully resolved.                              |
| `CLOSED`        | Post-resolution review complete; ticket archived.     |

| Priority   | When to use                                    |
| ---------- | ---------------------------------------------- |
| `LOW`      | Minimal impact, no customer effect.            |
| `MEDIUM`   | Degraded experience for a subset of users.     |
| `HIGH`     | Significant impact affecting many users.       |
| `CRITICAL` | Full service outage or data integrity at risk. |