# Incident

URL: /business/nouns/incident · Id: `noun:incident`

> An Incident is an Issue where an Interface or Site fails Customers in production, tracked from detection to postmortem.

An Incident is an [Issue](/business/nouns/issue) where an [Interface](/business/nouns/interface) or [Site](/business/nouns/site) fails [Customers](/business/nouns/customer) in production, tracked from detection to postmortem.

## Properties
| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `severity` | `string` | Yes | One of `minor`, `major`, or `critical`. |
| `detectedAt` | `datetime` | Yes | When monitoring or a Customer first reported it. |
| `resolvedAt` | `datetime` | No | When service was restored. |
| `personalData` | `boolean` | No | True when the Incident exposed personal data, which starts the breach-notice clock. |

<details>
<summary>Inherited from [Issue](/business/nouns/issue): 2 properties</summary>

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `kind` | `string` | No | One of `bug`, `request`, or `question`. |
| `advisory` | `string` | No | For a vulnerability: the public advisory it matches, with the affected package and range. |

</details>

<details>
<summary>Inherited from [Task](/business/nouns/task): 3 properties</summary>

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `due` | `datetime` | No | When the Task is due. |
| `priority` | `integer` | No | Its rank in the inbox, highest first. |
| `recurrence` | `string` | No | The schedule a recurring duty repeats on. |

</details>

<details>
<summary>Inherited from [Action](/business/nouns/action): 11 properties</summary>

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | `string` | Yes | One of `pending`, `done`, `failed`, `canceled`, or `refused`. |
| `reason` | `string` | No | Why a pending Action waits: `queued`, `running`, `retrying`, `awaitingWorker`, `awaitingInput`, `awaitingSource`, `awaitingAction`, or `awaitingTime`. |
| `mode` | `string` | Yes | How the caller invoked it: `try`, `send`, or `do`. |
| `by` | [Worker](/business/nouns/worker) | No | The Worker that performed it. |
| `for` | [Party](/business/nouns/party) | No | The Party it was done on behalf of. |
| `via` | `string` | No | The Interface or request it arrived through. |
| `on` | `string` | No | The Action or Event that caused it, such as the failed attempt a retry follows. |
| `thing` | `string` | No | The record, at the Version the Action was decided against. |
| `input` | `json` | No | The input it was called with. |
| `createdAt` | `datetime` | No | When it was called. |
| `reserved` | `money` | No | The most this Action may cost, held against its Limits from the check until it settles, billed misses included. |

</details>

## Object
```json
{
  "$id": "https://api.sb/quietcopy.com/incidents/incident_1",
  "$type": "Incident",
  "status": "pending",
  "reason": "queued",
  "mode": "try",
  "by": "worker_1",
  "for": "party_1",
  "via": "API",
  "on": "Invoice.overdue",
  "thing": "invoice_1@v3",
  "input": {},
  "createdAt": "2026-10-22T12:00:00Z",
  "reserved": {
    "amount": 39,
    "currency": "USD"
  },
  "due": "2026-10-22T12:00:00Z",
  "priority": 1,
  "recurrence": "Weekly on Friday",
  "kind": "bug",
  "advisory": "GHSA-xxxx-xxxx-xxxx",
  "severity": "minor",
  "detectedAt": "2026-10-22T12:00:00Z",
  "resolvedAt": "2026-10-22T12:00:00Z",
  "personalData": true
}
```

## Relationships
- <a id="rel-monitor"></a>An Incident **has** one [Monitor](/business/nouns/monitor): a failing internal [Monitor](/business/nouns/monitor) opens an Incident, which names the Monitor that saw it first. `monitor`, inverse [`opens`](/business/nouns/monitor#rel-opens).

## Verbs
| Verb | Description | Subject | Event | Class |
| --- | --- | --- | --- | --- |
| [Incident.acknowledge](/business/nouns/incident/acknowledge) | Acknowledge records that an on-call Worker owns an open Incident and stops its escalation. | [Reliability Engineer](/agents/engineering/reliability-engineer) | [`Incident.acknowledged`](/business/events/Incident.acknowledged) | Two-way: `try`, `send`, `do` |
| [Incident.open](/business/nouns/incident/open) | Open starts an Incident from a failing Monitor, an error spike or a Metric past its threshold, and pages the on-call Worker. | [Reliability Engineer](/agents/engineering/reliability-engineer) | [`Incident.opened`](/business/events/Incident.opened) | Two-way: `try`, `send`, `do` |
| [Incident.resolve](/business/nouns/incident/resolve) | Resolve closes an Incident once its Monitors pass, posts the resolution to the status page and opens the review Task. | [Reliability Engineer](/agents/engineering/reliability-engineer) | [`Incident.resolved`](/business/events/Incident.resolved) | Two-way: `try`, `send`, `do` |
| <a id="create"></a>[Incident.create](/business/nouns/incident/create) | Creates an Incident. Inherited from [Noun](/business/nouns/noun). | None. | `Incident.created` | Two-way: `try`, `send`, `do` |
| <a id="get"></a>[Incident.get](/business/nouns/incident/get) | Returns one Incident by id. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |
| <a id="list"></a>[Incident.list](/business/nouns/incident/list) | Returns Incidents, newest first, one page at a time. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |
| <a id="update"></a>[Incident.update](/business/nouns/incident/update) | Changes the given properties of an Incident. Inherited from [Noun](/business/nouns/noun). | None. | `Incident.updated` | Two-way: `try`, `send`, `do` |
| <a id="delete"></a>[Incident.delete](/business/nouns/incident/delete) | Deletes an Incident; its history is kept. Inherited from [Noun](/business/nouns/noun). | None. | `Incident.deleted` | One-way: `send`, `do` |

## Permissions
Which Access level may call each Verb. One-way Verbs wait their delay window.

| Operation | `owner` | `admin` | `member` | `viewer` |
| --- | --- | --- | --- | --- |
| `Incident.create` | Yes | Yes | Yes | No |
| `Incident.get` | Yes | Yes | Yes | Yes |
| `Incident.list` | Yes | Yes | Yes | Yes |
| `Incident.update` | Yes | Yes | Yes | No |
| `Incident.delete` | Yes | Yes | Yes | No |
| `Incident.acknowledge` | Yes | Yes | Yes | No |
| `Incident.open` | Yes | Yes | Yes | No |
| `Incident.resolve` | Yes | Yes | Yes | No |

## Call it

**Ask**

```text
Open the latest incident.
```

**API**

```bash
curl -X POST https://api.sb/quietcopy.com/incidents/open \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"severity":"sev1","cause":"Example cause"}'
```

```json
{
  "api": "https://api.sb/quietcopy.com",
  "incident": {
    "$id": "https://api.sb/quietcopy.com/incidents/incident_1",
    "$type": "Incident",
    "status": "pending",
    "mode": "try",
    "severity": "minor",
    "detectedAt": "2026-10-22T12:00:00Z"
  },
  "action": {
    "$id": "https://api.sb/quietcopy.com/actions/action_1",
    "operation": "Incident.open",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/quietcopy.com/actions/action_1"
  }
}
```

**SDK**

```ts
import { $ } from 'startup-builder'

const incident = await $.Incident.open({ severity: 'sev1', cause: 'Example cause' })
```

**CLI**

```bash
npx startup-builder do Incident.open --json '{"severity":"sev1","cause":"Example cause"}'
```

**MCP**

```json
{
  "name": "do",
  "arguments": {
    "code": "return await $.Incident.open({ severity: 'sev1', cause: 'Example cause' })"
  }
}
```

## Example
Sign-in to a meal-planning [App](/business/nouns/app) fails for 9 minutes after a deploy. A major Incident opens at detection, the [Change](/business/nouns/change) reverts, and the postmortem links the fix that prevents a repeat.