# Incidents

> Incidents opened by monitoring and the AI ops team.

Incidents opened by monitoring and the AI ops team.

| Operation | Method and path |
| --- | --- |
| [List incidents](#list-incidents) | `GET /v1/incidents` |
| [Open an incident](#open-an-incident) | `POST /v1/incidents` |
| [Get an incident](#get-an-incident) | `GET /v1/incidents/{incident_id}` |
| [Update an incident](#update-an-incident) | `PATCH /v1/incidents/{incident_id}` |
| [Incident timeline](#incident-timeline) | `GET /v1/incidents/{incident_id}/events` |
| [Add to the timeline](#add-to-the-timeline) | `POST /v1/incidents/{incident_id}/events` |

## List incidents

```http
GET /v1/incidents
```

Platform admins see everything; customers see customer-visible incidents for their projects.

- **Operation:** `listIncidents`
- **Scopes:** `incidents:read`
- **Paginated:** `?limit=` and `?cursor=`

**Parameters**

| Name | In | Type | Description |
| --- | --- | --- | --- |
| `status` | query | [IncidentStatus](/docs/api/objects/incident-status/) |  |
| `project` | query | string |  |
| `severity` | query | [IncidentSeverity](/docs/api/objects/incident-severity/) |  |

**Responses**

| Status | Meaning | Body |
| --- | --- | --- |
| `200` OK | A page of Incident objects. | [IncidentList](/docs/api/objects/incident-list/) |

**Errors:** `400`, `401`, `403`, `429`, `500`, as [problem+json](/errors/) with a stable `code`.

**Example**

```bash
curl https://api.guv.dev/v1/incidents \
  -H "Authorization: Bearer $GUV_TOKEN"
```

**Example response**

```json
{
  "data": [
    {
      "id": "inc_01jbx2m9k7q4r8t5v6w3y0z1pr",
      "scope": "platform",
      "title": "api will run out of memory in about 6 hours",
      "summary": "string",
      "severity": "sev1",
      "status": "open",
      "source": "alert",
      "cell": "lon1-a",
      "workspace_id": "string",
      "project_id": "string",
      "affected": [
        {
          "type": "service",
          "id": "svc_01jbx2m9k7q4r8t5v6w3y0z1sv",
          "name": "web",
          "url": "/v1/projects/primecarers/services/web"
        }
      ],
      "opened_by": {
        "type": "agent",
        "id": "tok_01jbx2m9k7q4r8t5v6w3y0z1tk",
        "display": "Stewart Webb via agent claude-code-on-stewart-laptop",
        "via_agent": {
          "id": "tok_01jbx2m9k7q4r8t5v6w3y0z1tk",
          "name": "claude-code-on-stewart-laptop"
        },
        "on_behalf_of": {
          "id": "usr_01jbx2m9k7q4r8t5v6w3y0z1us",
          "display": "Stewart Webb"
        }
      },
      "assigned_agent": "sentinel",
      "customer_visible": false,
      "opened_at": "2026-10-22T13:05:00Z",
      "mitigated_at": "2026-10-22T13:05:00Z",
      "resolved_at": "2026-10-22T13:05:00Z",
      "postmortem_url": "https://guv.dev/"
    }
  ],
  "next_cursor": "string",
  "has_more": false
}
```

## Open an incident

```http
POST /v1/incidents
```

- **Operation:** `openIncident`
- **Scopes:** `incidents:write`
- **Idempotency-Key:** required

**Request body** (`application/json`, required): [IncidentCreate](/docs/api/objects/incident-create/)

| Field | Type | Description |
| --- | --- | --- |
| `scope` | `platform`, `project` | Default `platform`. |
| `title` * | string |  |
| `summary` | string |  |
| `severity` * | [IncidentSeverity](/docs/api/objects/incident-severity/) |  |
| `source` * | `alert`, `probe`, `detector`, `customer_report`, `agent`, `human` |  |
| `cell` | string |  |
| `project_id` | string |  |
| `affected` | array of [ResourceRef](/docs/api/objects/resource-ref/) |  |
| `customer_visible` | boolean | Default `false`. |
| `dedupe_key` | string | Incidents with the same open dedupe key are merged. |

**Responses**

| Status | Meaning | Body |
| --- | --- | --- |
| `201` Created | Created. | [Incident](/docs/api/objects/incident/) |

**Errors:** `400`, `401`, `403`, `409`, `422`, `429`, `500`, as [problem+json](/errors/) with a stable `code`.

**Example**

```bash
curl -X POST https://api.guv.dev/v1/incidents \
  -H "Authorization: Bearer $GUV_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "scope": "platform",
  "title": "string",
  "summary": "string",
  "severity": "sev1",
  "source": "alert",
  "cell": "string",
  "project_id": "string",
  "affected": [
    {
      "type": "service",
      "id": "svc_01jbx2m9k7q4r8t5v6w3y0z1sv",
      "name": "web",
      "url": "/v1/projects/primecarers/services/web"
    }
  ],
  "customer_visible": false,
  "dedupe_key": "string"
}'
```

**Example response**

```json
{
  "id": "inc_01jbx2m9k7q4r8t5v6w3y0z1pr",
  "scope": "platform",
  "title": "api will run out of memory in about 6 hours",
  "summary": "string",
  "severity": "sev1",
  "status": "open",
  "source": "alert",
  "cell": "lon1-a",
  "workspace_id": "string",
  "project_id": "string",
  "affected": [
    {
      "type": "service",
      "id": "svc_01jbx2m9k7q4r8t5v6w3y0z1sv",
      "name": "web",
      "url": "/v1/projects/primecarers/services/web"
    }
  ],
  "opened_by": {
    "type": "agent",
    "id": "tok_01jbx2m9k7q4r8t5v6w3y0z1tk",
    "display": "Stewart Webb via agent claude-code-on-stewart-laptop",
    "via_agent": {
      "id": "tok_01jbx2m9k7q4r8t5v6w3y0z1tk",
      "name": "claude-code-on-stewart-laptop"
    },
    "on_behalf_of": {
      "id": "usr_01jbx2m9k7q4r8t5v6w3y0z1us",
      "display": "Stewart Webb"
    }
  },
  "assigned_agent": "sentinel",
  "customer_visible": false,
  "opened_at": "2026-10-22T13:05:00Z",
  "mitigated_at": "2026-10-22T13:05:00Z",
  "resolved_at": "2026-10-22T13:05:00Z",
  "postmortem_url": "https://guv.dev/"
}
```

## Get an incident

```http
GET /v1/incidents/{incident_id}
```

- **Operation:** `getIncident`
- **Scopes:** `incidents:read`

**Parameters**

| Name | In | Type | Description |
| --- | --- | --- | --- |
| `incident_id` * | path | string |  |

**Responses**

| Status | Meaning | Body |
| --- | --- | --- |
| `200` OK | OK. | [Incident](/docs/api/objects/incident/) |

**Errors:** `400`, `401`, `403`, `404`, `429`, `500`, as [problem+json](/errors/) with a stable `code`.

**Example**

```bash
curl https://api.guv.dev/v1/incidents/inc_01jbx2m9k7q4r8t5v6w3y0z1pr \
  -H "Authorization: Bearer $GUV_TOKEN"
```

**Example response**

```json
{
  "id": "inc_01jbx2m9k7q4r8t5v6w3y0z1pr",
  "scope": "platform",
  "title": "api will run out of memory in about 6 hours",
  "summary": "string",
  "severity": "sev1",
  "status": "open",
  "source": "alert",
  "cell": "lon1-a",
  "workspace_id": "string",
  "project_id": "string",
  "affected": [
    {
      "type": "service",
      "id": "svc_01jbx2m9k7q4r8t5v6w3y0z1sv",
      "name": "web",
      "url": "/v1/projects/primecarers/services/web"
    }
  ],
  "opened_by": {
    "type": "agent",
    "id": "tok_01jbx2m9k7q4r8t5v6w3y0z1tk",
    "display": "Stewart Webb via agent claude-code-on-stewart-laptop",
    "via_agent": {
      "id": "tok_01jbx2m9k7q4r8t5v6w3y0z1tk",
      "name": "claude-code-on-stewart-laptop"
    },
    "on_behalf_of": {
      "id": "usr_01jbx2m9k7q4r8t5v6w3y0z1us",
      "display": "Stewart Webb"
    }
  },
  "assigned_agent": "sentinel",
  "customer_visible": false,
  "opened_at": "2026-10-22T13:05:00Z",
  "mitigated_at": "2026-10-22T13:05:00Z",
  "resolved_at": "2026-10-22T13:05:00Z",
  "postmortem_url": "https://guv.dev/"
}
```

## Update an incident

```http
PATCH /v1/incidents/{incident_id}
```

- **Operation:** `updateIncident`
- **Scopes:** `incidents:write`
- **Idempotency-Key:** required
- **Concurrency:** send the `ETag` you read as `If-Match`

**Parameters**

| Name | In | Type | Description |
| --- | --- | --- | --- |
| `incident_id` * | path | string |  |

**Request body** (`application/json`, required): [IncidentUpdate](/docs/api/objects/incident-update/)

| Field | Type | Description |
| --- | --- | --- |
| `title` | string |  |
| `summary` | string |  |
| `severity` | [IncidentSeverity](/docs/api/objects/incident-severity/) |  |
| `status` | [IncidentStatus](/docs/api/objects/incident-status/) |  |
| `assigned_agent` | string or null |  |
| `customer_visible` | boolean |  |
| `postmortem_url` | string or null |  |

**Responses**

| Status | Meaning | Body |
| --- | --- | --- |
| `200` OK | OK. | [Incident](/docs/api/objects/incident/) |

**Errors:** `400`, `401`, `403`, `404`, `409`, `412`, `422`, `429`, `500`, as [problem+json](/errors/) with a stable `code`.

**Example**

```bash
curl -X PATCH https://api.guv.dev/v1/incidents/inc_01jbx2m9k7q4r8t5v6w3y0z1pr \
  -H "Authorization: Bearer $GUV_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "string",
  "summary": "string",
  "severity": "sev1",
  "status": "open",
  "assigned_agent": "string",
  "customer_visible": false,
  "postmortem_url": "string"
}'
```

**Example response**

```json
{
  "id": "inc_01jbx2m9k7q4r8t5v6w3y0z1pr",
  "scope": "platform",
  "title": "api will run out of memory in about 6 hours",
  "summary": "string",
  "severity": "sev1",
  "status": "open",
  "source": "alert",
  "cell": "lon1-a",
  "workspace_id": "string",
  "project_id": "string",
  "affected": [
    {
      "type": "service",
      "id": "svc_01jbx2m9k7q4r8t5v6w3y0z1sv",
      "name": "web",
      "url": "/v1/projects/primecarers/services/web"
    }
  ],
  "opened_by": {
    "type": "agent",
    "id": "tok_01jbx2m9k7q4r8t5v6w3y0z1tk",
    "display": "Stewart Webb via agent claude-code-on-stewart-laptop",
    "via_agent": {
      "id": "tok_01jbx2m9k7q4r8t5v6w3y0z1tk",
      "name": "claude-code-on-stewart-laptop"
    },
    "on_behalf_of": {
      "id": "usr_01jbx2m9k7q4r8t5v6w3y0z1us",
      "display": "Stewart Webb"
    }
  },
  "assigned_agent": "sentinel",
  "customer_visible": false,
  "opened_at": "2026-10-22T13:05:00Z",
  "mitigated_at": "2026-10-22T13:05:00Z",
  "resolved_at": "2026-10-22T13:05:00Z",
  "postmortem_url": "https://guv.dev/"
}
```

## Incident timeline

```http
GET /v1/incidents/{incident_id}/events
```

- **Operation:** `listIncidentEvents`
- **Scopes:** `incidents:read`
- **Paginated:** `?limit=` and `?cursor=`

**Parameters**

| Name | In | Type | Description |
| --- | --- | --- | --- |
| `incident_id` * | path | string |  |

**Responses**

| Status | Meaning | Body |
| --- | --- | --- |
| `200` OK | A page of IncidentEvent objects. | [IncidentEventList](/docs/api/objects/incident-event-list/) |

**Errors:** `400`, `401`, `403`, `404`, `429`, `500`, as [problem+json](/errors/) with a stable `code`.

**Example**

```bash
curl https://api.guv.dev/v1/incidents/inc_01jbx2m9k7q4r8t5v6w3y0z1pr/events \
  -H "Authorization: Bearer $GUV_TOKEN"
```

**Example response**

```json
{
  "data": [
    {
      "id": "string",
      "incident_id": "string",
      "at": "2026-10-22T13:05:00Z",
      "actor": {
        "type": "agent",
        "id": "tok_01jbx2m9k7q4r8t5v6w3y0z1tk",
        "display": "Stewart Webb via agent claude-code-on-stewart-laptop",
        "via_agent": {
          "id": "tok_01jbx2m9k7q4r8t5v6w3y0z1tk",
          "name": "claude-code-on-stewart-laptop"
        },
        "on_behalf_of": {
          "id": "usr_01jbx2m9k7q4r8t5v6w3y0z1us",
          "display": "Stewart Webb"
        }
      },
      "kind": "note",
      "message": "string",
      "data": {}
    }
  ],
  "next_cursor": "string",
  "has_more": false
}
```

## Add to the timeline

```http
POST /v1/incidents/{incident_id}/events
```

- **Operation:** `addIncidentEvent`
- **Scopes:** `incidents:write`
- **Idempotency-Key:** required

**Parameters**

| Name | In | Type | Description |
| --- | --- | --- | --- |
| `incident_id` * | path | string |  |

**Request body** (`application/json`, required): [IncidentEventCreate](/docs/api/objects/incident-event-create/)

| Field | Type | Description |
| --- | --- | --- |
| `kind` * | `note`, `signal`, `tool_call`, `policy_decision`, `customer_notice` |  |
| `message` * | string |  |
| `data` | object |  |

**Responses**

| Status | Meaning | Body |
| --- | --- | --- |
| `201` Created | Created. | [IncidentEvent](/docs/api/objects/incident-event/) |

**Errors:** `400`, `401`, `403`, `404`, `409`, `422`, `429`, `500`, as [problem+json](/errors/) with a stable `code`.

**Example**

```bash
curl -X POST https://api.guv.dev/v1/incidents/inc_01jbx2m9k7q4r8t5v6w3y0z1pr/events \
  -H "Authorization: Bearer $GUV_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "kind": "note",
  "message": "string",
  "data": {}
}'
```

**Example response**

```json
{
  "id": "string",
  "incident_id": "string",
  "at": "2026-10-22T13:05:00Z",
  "actor": {
    "type": "agent",
    "id": "tok_01jbx2m9k7q4r8t5v6w3y0z1tk",
    "display": "Stewart Webb via agent claude-code-on-stewart-laptop",
    "via_agent": {
      "id": "tok_01jbx2m9k7q4r8t5v6w3y0z1tk",
      "name": "claude-code-on-stewart-laptop"
    },
    "on_behalf_of": {
      "id": "usr_01jbx2m9k7q4r8t5v6w3y0z1us",
      "display": "Stewart Webb"
    }
  },
  "kind": "note",
  "message": "string",
  "data": {}
}
```