---
title: "Push a custom incident (PagerDuty Events v2 envelope)"
method: POST
path: "/api/v1/incidents"
tags: ["ingestion"]
---

# Push a custom incident (PagerDuty Events v2 envelope)

`POST /api/v1/incidents`

## Request

- Base URL: `https://monit.rs`
- URL: `https://monit.rs/api/v1/incidents`
- Auth: HTTP bearer

Agent-detected incident. Action-based state machine: trigger opens or updates, acknowledge marks, resolve closes. Deduplicated on (user_id, dedup_key) — same key merges into one incident.

## Headers

- `Idempotency-Key` string

## Request body

- IncidentIngestRequest
  - `action` 'trigger' | 'acknowledge' | 'resolve', required
  - `dedup_key` string, required: Merges trigger/ack/resolve events into one incident (PagerDuty pattern).
  - `endpoint_id` string, uuid, nullable: Required on trigger; optional on ack/resolve.
  - `external_ref` string, nullable: Free-form caller-side reference (e.g. ticket number).
  - `payload` IncidentPayload, required
    - `title` string, required
    - `severity` 'critical' | 'error' | 'warning' | 'info', required
    - `description` string, nullable
    - `source` string, nullable

## Response `202`

Incident created or updated.

- IncidentIngestResponse
  - `incident_id` string, uuid, required
  - `dedup_key` string, required
  - `status` 'open' | 'acknowledged' | 'resolved', required

## Other responses

- `401`: Missing/invalid credentials.
- `403`: Missing ingest:incidents scope.
- `404`: endpoint_id not owned by caller (on trigger), OR no open incident with dedup_key (on ack/resolve).
- `409`: Idempotency-Key reused with different body.
- `422`: Validation error.
- `429`: Rate limit exceeded.

---

[API](https://skmtc.dev/monit/apis/monit-rs-public-api.md) · [All operations](https://skmtc.dev/monit/apis/monit-rs-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/monit/apis/monit-rs-public-api/revisions/7e1923981112?raw)