> ## 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: Lifecycle, Statuses, and Key Fields

> Learn how Scrubbe models incidents from detection through resolution, including statuses, priorities, and how tickets connect to your team's workflow.

An incident in Scrubbe is a structured record of an event that disrupts or degrades your service. Every incident moves through a defined lifecycle — from the moment it is opened to the point it is closed — giving your team a shared, traceable account of what happened, who responded, and how it was resolved. Incidents are the central object in Scrubbe: comments, messages, SLA tracking, AI analysis, and post-mortems all attach to an incident ticket.

## Generating a ticket ID

Before creating an incident, generate a unique ticket ID. Scrubbe uses this ID to track the incident across all systems, including integrations and the customer knowledge base.

```http theme={null}
GET /api/v1/incident-ticket/generate-id
```

Pass the returned ID as the `ticketId` field when creating the ticket.

## Creating an incident

Send a `POST` request to `/api/v1/incident-ticket` with the following body:

```json theme={null}
{
  "summary": "Payment service down",
  "priority": "CRITICAL",
  "status": "OPEN",
  "source": "MONITORING",
  "serviceArea": "payments",
  "environment": "production",
  "region": "us-east-1",
  "assignedToEmail": "oncall@example.com",
  "description": "The payment gateway is returning 500 errors.",
  "techDescription": "Redis connection pool exhausted.",
  "impactSummary": "All checkout flows are failing.",
  "blastRadius": "100% of users attempting checkout"
}
```

### Key fields

<AccordionGroup>
  <Accordion title="Identity and routing">
    | Field             | Description                                                                               |
    | ----------------- | ----------------------------------------------------------------------------------------- |
    | `summary`         | Short, human-readable title of the incident                                               |
    | `source`          | How the incident entered the system: `MANUAL`, `API`, `WEBHOOK`, `MONITORING`, or `ALERT` |
    | `serviceArea`     | The service or area of your system affected                                               |
    | `environment`     | Deployment environment (e.g. `production`, `staging`)                                     |
    | `region`          | Cloud or geographic region (e.g. `us-east-1`)                                             |
    | `assignedToEmail` | Email of the team member responsible for the incident                                     |
  </Accordion>

  <Accordion title="Description fields">
    | Field             | Description                                                                         |
    | ----------------- | ----------------------------------------------------------------------------------- |
    | `description`     | Human-readable account of what is happening                                         |
    | `techDescription` | Technical detail for engineers — root system behavior, error messages, stack traces |
    | `impactSummary`   | Business-level description of what is affected                                      |
    | `blastRadius`     | Scope of the impact (e.g., which percentage of users, which features)               |
  </Accordion>

  <Accordion title="Priority and status">
    | Field      | Description                                                      |
    | ---------- | ---------------------------------------------------------------- |
    | `priority` | Severity of the incident: `LOW`, `MEDIUM`, `HIGH`, or `CRITICAL` |
    | `status`   | Current lifecycle stage (see below)                              |
  </Accordion>
</AccordionGroup>

## Incident lifecycle

Every incident progresses through the following statuses. Scrubbe records timestamps at key transitions — `acknowledgedAt`, `resolvedAt`, and `closedAt` — which feed into MTTR calculations and SLA tracking.

<Steps>
  <Step title="OPEN">
    The incident has been created and is awaiting a responder. Tickets created manually or promoted from an unmatched signal start here. SLA response timers begin as soon as a ticket reaches `OPEN`.
  </Step>

  <Step title="ACKNOWLEDGED">
    A team member has accepted the incident. The response SLA timer stops here. Use `PUT /api/v1/incident-ticket/:id` to move a ticket to this status.
  </Step>

  <Step title="INVESTIGATION">
    Active investigation is underway. The team is diagnosing root cause. During this phase, engineers typically add comments, link related changes, and use AI analysis tools.
  </Step>

  <Step title="MITIGATED">
    The immediate impact has been reduced or stopped, but the root cause may not yet be fully addressed. You can communicate mitigation to stakeholders from this state.
  </Step>

  <Step title="RESOLVED">
    The incident is fully resolved. Call `POST /api/v1/incident-ticket/resolve/:id` to transition a ticket to this state. Resolution triggers post-mortem creation and optionally publishes a summary to the customer knowledge base.
  </Step>

  <Step title="CLOSED">
    The incident record has been reviewed and closed. No further action is expected.
  </Step>
</Steps>

<Note>
  Incidents raised by Scrubbe's automation pipeline may also pass through intermediate machine states (`DETECTED`, `ENRICHED`, `ACTION_PROPOSED`, `EXECUTING`) before reaching `OPEN`. These transitions happen automatically and do not require manual action.
</Note>

## Priority levels

Priority determines how urgently the incident must be addressed and which SLA policy applies.

| Priority   | When to use                                                                    |
| ---------- | ------------------------------------------------------------------------------ |
| `LOW`      | Minimal or no user impact; can be addressed in normal work hours               |
| `MEDIUM`   | Degraded experience for some users; requires a response within business hours  |
| `HIGH`     | Significant user impact; requires prompt attention outside normal hours        |
| `CRITICAL` | Full service outage or data loss risk; requires immediate response at any hour |

## Comments and messages

Two collaboration primitives are available on every ticket:

* **Comments** (`POST /api/v1/incident-ticket/comment`) — structured annotations on the ticket record. Use these for status updates, investigation notes, and decisions. Retrieve all comments for a ticket with `GET /api/v1/incident-ticket/comment/:ticketId`.
* **Messages** (`POST /api/v1/incident-ticket/message/:ticketId`) — real-time chat thread attached to the ticket. Use these for live coordination during an active incident. Retrieve the thread with `GET /api/v1/incident-ticket/message/:ticketId`.

## Analytics

`GET /api/v1/incident-ticket/analytics` returns aggregated metrics for your incidents, including volume by status, priority distribution, and MTTR trends. Use this endpoint to populate dashboards or audit SLA compliance.

## Resolution and the customer knowledge base

When you resolve an incident, Scrubbe generates a post-mortem record and an AI-assisted analysis. You can then publish a sanitized resolution summary to the customer knowledge base:

```http theme={null}
POST /api/v1/incident-ticket/resolve/customer-kb/:id
```

This makes the resolution visible to users with access to your customer portal, keeping them informed without requiring manual communication.