---
title: Build on Venom Incidents
description: Triage errors, run incidents and manage on-call from code or an agent. Read and resolve error issues, declare and update incidents, page people and change alert rules over REST or MCP, and send errors from your apps with an SDK key.
section: developers
order: 90
audience: [builder, agent]
sources: [services/nodejs-cloud/lib/errors/mcp/index.ts, services/nodejs-cloud/lib/errors/auth.ts, services/nodejs-cloud/lib/errors/access.ts, services/nodejs-cloud/lib/incidents/mcp-tools.ts, services/nodejs-cloud/lib/incidents/mcp-more-tools.ts, services/nodejs-cloud/lib/incidents/oncall-service.ts, services/nodejs-cloud/app/incidents/api/v1, services/nodejs-cloud/app/incidents/sdk, services/nodejs-cloud/app/incidents/mcp/route.ts, services/nodejs-cloud/contracts/incidents-openapi.yaml, services/nodejs-cloud/lib/mcp/rest.ts, services/nodejs-cloud/lib/oauth, docs/adr/0055-venom-incidents.md]
features: []
---

Venom Incidents groups your apps' errors into issues, runs incidents with a timeline, and pages whoever is on call.
Everything the app does is also an MCP tool and a route of the Incidents API under `/incidents/api/v1`. Your apps send
errors to `/incidents/sdk/events` with an environment's SDK key.

## What you can build {#build}

- **A triage agent.** List open issues by count (`incidents_error_list`), read the top one with its stack, release and the flags that were served (`incidents_error_get`), then assign or resolve it (`incidents_error_update`, `PATCH /incidents/api/v1/errors/{id}`).
- **Incidents from your own tooling.** Declare one from a chat command or a monitor (`POST /incidents/api/v1/incidents`), link the error issues and the fix commit (`POST /incidents/api/v1/incidents/{ref}/links`) and post status updates that also show on the status page (`POST /incidents/api/v1/incidents/{ref}/updates` with `public: true`).
- **Release tracking from CI.** Record each deploy (`POST /incidents/api/v1/releases`) and upload source maps for it (`POST /incidents/api/v1/releases/{version}/artifacts`), so stacks are mapped and a spike is tied to the release.
- **Pages from any monitor.** Add an alert source (`incidents_oncall_source_create`) and point Alertmanager, Grafana or any JSON sender at `POST /incidents/api/v1/inbound/{id}`.
- **On-call from your HR or calendar system.** Read who is on call (`incidents_oncall_who`), cover a shift (`incidents_oncall_override`) or replace a whole schedule (`incidents_oncall_schedule_set`).
- **Rollback from an agent.** Rank what changed before the spike (`incidents_incident_implicate`) and undo the top flag change as an audited Flags revert (`incidents_incident_rollback`).

## At a glance {#glance}

Generated from the code on every docs build.

| | |
|---|---|
| MCP endpoint | `https://cloud.usevenom.dev/workspace/mcp/incidents`, server name `venom-incidents` |
| Connect | `claude mcp add --transport http venom-incidents https://cloud.usevenom.dev/workspace/mcp/incidents` |
| MCP tools | 56 (24 read, 32 write) |
| OAuth scopes | `incidents:read` `incidents:write` `incidents:admin` |
| REST twin | 60 routes under `https://cloud.usevenom.dev/api/v1` |
| Incidents API | 51 operations |
| Webhook events | `errors.issue.created`, `errors.issue.regressed`, `errors.alert.fired`, `incidents.created`, `incidents.updated`, `incidents.resolved`, `incidents.page` |

Incidents also serves the same tools at `$VENOM_CLOUD/incidents/mcp` (server `venom-incidents`), its original endpoint.
Both take the same credentials.

## Authentication and scopes {#scopes}

Incidents has three permissions: `incidents:read`, `incidents:write` and `incidents:admin`. What a caller gets depends
on the credential:

- A **personal API key** acts with its member's org role. Owners and admins get all three; developers get read and
  write; billing members and viewers read only.
- A **team key** has no member. It gets `incidents:read` and `incidents:write`, so a CI job or an agent can change
  issues and incidents, but never `incidents:admin`.
- An **OAuth app** gets the member's role narrowed to the scopes granted. `incidents:admin` is a separate scope the
  app must ask for.
- An **SDK key** (`vfs_…` server, `vfm_…` mobile) or a **client id** (`vfc_…`) belongs to a Venom Flags environment.
  It only sends events to `/incidents/sdk/events`; it reads nothing.

`incidents:admin` is checked by the service, not by the tool's listed scope, so a tool shown as `incidents:write` in
the table below may still answer `This needs the incidents:admin permission`. These need it:

| What | MCP tools | REST |
|---|---|---|
| Alert rules: create, replace, delete | `incidents_alert_set` (except `test: true`), `incidents_alert_delete` | `POST`, `PUT`, `DELETE /incidents/api/v1/alerts…` |
| Fingerprint rules: create, delete | `incidents_rule_create`, `incidents_rule_delete` | `POST /incidents/api/v1/rules`, `DELETE /incidents/api/v1/rules/{id}` |
| The incident loop's settings | `incidents_setting_update` | `PUT /incidents/api/v1/settings` |
| On-call schedules and escalation policies: create, replace, delete | `incidents_oncall_schedule_set`, `incidents_oncall_schedule_delete`, `incidents_oncall_policy_set`, `incidents_oncall_policy_delete` | `/incidents/api/v1/oncall/schedules…`, `/incidents/api/v1/oncall/policies…` |
| Alert sources: list, create, change, delete | `incidents_oncall_source_list`, `incidents_oncall_source_create`, `incidents_oncall_source_update`, `incidents_oncall_source_delete` | `/incidents/api/v1/oncall/sources…` |

Covering a shift, paging, acknowledging and escalating need only `incidents:write`. The GitHub write token for
reproducer PRs is set only by an owner or admin in person (`PUT /incidents/api/v1/github-token`); any agent is refused,
and `incidents_github_token_get` only says whether one is set.

Other rules:

- **The add-on.** Without Venom Incidents on the org, the MCP handshake works and every tool call answers that the
  add-on is needed. REST answers `403 addon_required`. `GET /incidents/api/v1/me` reports the caller's permissions and
  whether the org has it.
- **Naming the agent.** A key may send `x-venom-agent: daemon:<uuid>` or `session:<id>` to record the change under one
  of the org's daemons or sessions. It grants nothing extra. Changes made over MCP are recorded with the agent's name
  and "via mcp".
- **Rate limits.** The REST API answers at most 600 requests a minute per credential; `/incidents/mcp` 240 tool calls
  a minute. Over the limit is `429` with `retry-after`.
- **Agents are never the commander.** An incident opened by an agent has no commander unless the call names a person.

## Worked example {#example}

Declare a SEV2 for the `web` project, link the error issue behind it, and post a public status update:

```bash
curl -X POST "$VENOM_CLOUD/incidents/api/v1/incidents" \
  -H "Authorization: Bearer $VENOM_API_KEY" -H 'Content-Type: application/json' \
  -d '{"title": "Checkout errors after 1.4.2", "severity": 2, "projects": ["web"], "environments": ["production"]}'

curl -X POST "$VENOM_CLOUD/incidents/api/v1/incidents/INC-12/links" \
  -H "Authorization: Bearer $VENOM_API_KEY" -H 'Content-Type: application/json' \
  -d '{"kind": "error_issue", "ref": "<issue-id>"}'

curl -X POST "$VENOM_CLOUD/incidents/api/v1/incidents/INC-12/updates" \
  -H "Authorization: Bearer $VENOM_API_KEY" -H 'Content-Type: application/json' \
  -d '{"body": "We found the cause and are rolling back.", "status": "identified", "public": true}'
```

The first call answers `201` with `{"incident": {...}}`; use its number as `ref` (`12`, `INC-12` or the id). The same
over MCP, from a client connected to `/workspace/mcp/incidents`:

```json
{ "jsonrpc": "2.0", "id": 1, "method": "tools/call",
  "params": { "name": "incidents_incident_open",
              "arguments": { "title": "Checkout errors after 1.4.2", "severity": 2, "projects": ["web"], "environments": ["production"] } } }
```

```json
{ "jsonrpc": "2.0", "id": 2, "method": "tools/call",
  "params": { "name": "incidents_link_create",
              "arguments": { "ref": "INC-12", "links": [{ "kind": "error_issue", "ref": "<issue-id>" }] } } }
```

```json
{ "jsonrpc": "2.0", "id": 3, "method": "tools/call",
  "params": { "name": "incidents_update_create",
              "arguments": { "ref": "INC-12", "body": "We found the cause and are rolling back.", "status": "identified", "public": true } } }
```

## A triage loop {#triage}

1. `incidents_error_list` with `state: "open"` and `sort: "count"`.
2. `incidents_error_get` on the top one: read the culprit, the release it started in and the flags served.
3. If every event had the same flag value, the cause is probably that flag: look it up with the
   [Flags tools](/docs/developers/flags.md).
4. `incidents_error_update` with `assignee: "agent:triage"`, or `state: "resolved"` and `resolveNext: true` once a fix
   is merged.

A version conflict (`409 version_conflict`, or a tool error saying the issue changed) means someone changed it since
you read it: call `incidents_error_get` again and retry with the new `expectVersion`. Over REST, send the version as
`If-Match: "<version>"`.

## Tool notes {#tool-notes}

What the tools' arguments mean, beyond their input schemas:

- **Answers.** Every tool takes `format: "json"` for a structured result; the default is compact markdown. An issue's
  stack shows in-app frames first, at most 12 by default, source-mapped when the release has maps.
- **`incidents_error_list`.** `state` is `open` (default), `all`, `unresolved`, `resolved`, `ignored` or `regressed`.
  Filter by `project`, `env`, `release`, `assignee` (a member uid, `agent:<id>`, `none` or `me`) or `q`; page with
  `cursor`.
- **`incidents_error_update`.** `state` resolved (with `resolvedIn` or `resolveNext`), ignored (with `ignoreCount` or
  `ignoreUntil`) or unresolved; `assignee`; or `mergeInto`. Pass `expectVersion` from `incidents_error_get`.
- **`incidents_incident_get`.** `since` is a timeline cursor from an earlier answer, so a loop reads only what is new.
- **`incidents_incident_update`.** Changes `status`, `severity`, `title`, `summary` and roles; `update` posts a status
  update (`publish: true` also shows it on the status page), `note` an internal note, and `linkKind` with `link` adds
  one link. `expectVersion` guards it.
- **`incidents_incident_implicate`.** Ranks Flags changes (by timing, and by how much of the sampled errors were served
  one variation compared with its share of evaluations) and releases, each with a confidence and why.
- **`incidents_incident_rollback`.** Undoes a flag change as a normal, audited Flags revert. With `ref`, the incident's
  top flag (or `flag`, `auditId`); without it, `project`, `flag`, `auditId` and `env`. Where the environment needs
  approvals it files a request to turn the flag off instead.
- **`incidents_incident_postmortem`.** Writes the blameless postmortem into Notes, or returns the one that exists.
  `ai: true` drafts the prose; `fileActions: true` files its action items in Tasks.
- **`incidents_alert_set`.** Creates a rule (no `id`), replaces one (`id` with `expectVersion`), dry-runs one over the
  last 24 hours (`test: true`, nothing recorded) or deletes one (`delete: true`).
- **`incidents_oncall_schedule_set`.** Creates or replaces a schedule with its rotations; a rotation names members or an
  org team. `incidents_oncall_schedule_get` with `from` and `to` adds the timeline.
- **`incidents_oncall_source_create`.** Returns the source's webhook secret once. Store it in the monitor and never log
  it.
- **`incidents_reproducer_write`.** Writes a failing test and opens it as a draft PR on `venom/reproducer-<ref>`. It
  needs the org's GitHub write token and says so when there is none.
- **`incidents_eval_case_draft`.** Drafts an eval task from the incident's linked fix or revert commit for a person to
  review. It runs nothing.

## Sending errors from your apps {#sdk}

`POST /incidents/sdk/events` takes one event, a list of up to 100, or `{"events": [...], "release": {...}}`, at most
200 KB, with `Authorization: Bearer vfs_…` (or `vfm_…`) or `x-venom-client-id: vfc_…`. It answers
`202 {"accepted", "rejected", "ids"}`. The SDKs, the event fields and the limits are in
[Error SDKs](/docs/incidents/errors-sdk.md); a Sentry DSN can point here too ([Migrate from Sentry](/docs/incidents/migrate-from-sentry.md)).

## Events {#events}

7 org webhook events, generated from `lib/webhooks/events.ts`. Subscribe an endpoint to them in Settings, Webhooks (see [Webhooks and events](/docs/developers/webhooks)).

| Event | When |
|---|---|
| `errors.issue.created` | A new error issue appeared in Venom Incidents (id, project, title, count and release; never the event itself). |
| `errors.issue.regressed` | A resolved error issue happened again in Venom Incidents. |
| `errors.alert.fired` | One of the org's error alert rules fired (rule, kind, issue, the numbers behind it, and the action). |
| `incidents.created` | An incident was declared in Venom Incidents (number, title, severity, status, projects; never its notes). |
| `incidents.updated` | An incident's status, severity, roles or title changed. |
| `incidents.resolved` | An incident was resolved. |
| `incidents.page` | Someone is being paged: the page, its title, the escalation level and the members told (so an org can bridge SMS or voice through its own gateway). Sent again at each escalation. |

Two more ways in, beyond org webhooks:

- **Alert sources** take alerts in: `POST /incidents/api/v1/inbound/{id}`, authenticated by the source's secret as a
  bearer token or an `X-Venom-Signature` HMAC of the body. Firing pages the policy and may open an incident; resolved
  resolves the page. See [Alert sources](/docs/incidents/alert-sources.md).
- **Public status updates** (`public: true`) reach the status page's subscribers as `status.incident.*` deliveries. See
  [Build on the Status page](/docs/developers/status.md).

## REST routes {#rest}

The REST twin: 60 routes under `https://cloud.usevenom.dev/api/v1`, each calling the MCP tool named in its row with the same arguments (see [the REST twin](/docs/developers/rest)).

| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | `/api/v1/incidents/errors` | Error groups, filtered by project, environment, release, state, assignee or text | `incidents_error_list` |
| POST | `/api/v1/incidents/errors/split` | Split merged error groups back apart | `incidents_error_split` |
| GET | `/api/v1/incidents/errors/{id}` | One error group with its latest (or a chosen) event | `incidents_error_get` |
| PATCH | `/api/v1/incidents/errors/{id}` | Resolve, ignore, reopen, assign or merge an error group | `incidents_error_update` |
| GET | `/api/v1/incidents/errors/{id}/events` | An error group's events, newest first | `incidents_event_list` |
| GET | `/api/v1/incidents/errors/{id}/events/{event}` | One event of an error group, with its stack | `incidents_event_get` |
| POST | `/api/v1/incidents/errors/{into}/merge` | Merge other error groups into this one | `incidents_error_merge` |
| POST | `/api/v1/incidents/errors/{id}/tasks-issue` | File a Venom Tasks issue for an error group | `incidents_error_file` |
| GET | `/api/v1/incidents/alerts` | Error alert rules, with recent hits | `incidents_alert_list` |
| POST | `/api/v1/incidents/alerts` | Add an error alert rule | `incidents_alert_set` |
| DELETE | `/api/v1/incidents/alerts` | Delete error alert rules by id (ids=a,b) | `incidents_alert_delete` |
| GET | `/api/v1/incidents/alerts/hits` | When alert rules fired | `incidents_alert_hit_list` |
| POST | `/api/v1/incidents/alerts/test` | What an alert rule would have fired on, without saving it | `incidents_alert_test` |
| PUT | `/api/v1/incidents/alerts/{id}` | Change, test or delete an error alert rule | `incidents_alert_set` |
| GET | `/api/v1/incidents/incidents` | Incidents, open first | `incidents_incident_list` |
| POST | `/api/v1/incidents/incidents` | Open an incident | `incidents_incident_open` |
| GET | `/api/v1/incidents/incidents/{ref}` | One incident with its timeline | `incidents_incident_get` |
| PATCH | `/api/v1/incidents/incidents/{ref}` | Change an incident: status, severity, roles, an update, a link or a note | `incidents_incident_update` |
| GET | `/api/v1/incidents/incidents/{ref}/implicate` | The changes (deploys, flags) most likely behind an incident, ranked | `incidents_incident_implicate` |
| POST | `/api/v1/incidents/incidents/{ref}/rollback` | Roll back the flag change behind an incident | `incidents_incident_rollback` |
| POST | `/api/v1/incidents/incidents/{ref}/postmortem` | Draft an incident's postmortem (optionally filing its action items) | `incidents_incident_postmortem` |
| GET | `/api/v1/incidents/incidents/{ref}/eval-case` | An incident's eval case | `incidents_eval_case_get` |
| POST | `/api/v1/incidents/incidents/{ref}/eval-case` | Draft an eval case from an incident | `incidents_eval_case_draft` |
| GET | `/api/v1/incidents/incidents/{ref}/reproducer` | An incident's reproducer | `incidents_reproducer_get` |
| POST | `/api/v1/incidents/incidents/{ref}/reproducer` | Write a reproducer for an incident | `incidents_reproducer_write` |
| POST | `/api/v1/incidents/incidents/{ref}/links` | Link errors, issues or other things to an incident | `incidents_link_create` |
| DELETE | `/api/v1/incidents/incidents/{ref}/links` | Remove a link from an incident | `incidents_link_delete` |
| POST | `/api/v1/incidents/incidents/{ref}/updates` | Post an update on an incident (public: on the status page) | `incidents_update_create` |
| POST | `/api/v1/incidents/rollback` | Roll back a flag change by flag or audit id, without an incident | `incidents_incident_rollback` |
| GET | `/api/v1/incidents/projects` | The org's error-tracking projects | `incidents_project_list` |
| GET | `/api/v1/incidents/settings` | The incident loop's settings per project | `incidents_setting_get` |
| PUT | `/api/v1/incidents/settings` | Set a project's incident loop: auto-rollback, threshold, team, triage agent, postmortems | `incidents_setting_update` |
| GET | `/api/v1/incidents/rules` | A project's grouping rules | `incidents_rule_list` |
| POST | `/api/v1/incidents/rules` | Add a grouping rule | `incidents_rule_create` |
| DELETE | `/api/v1/incidents/rules` | Delete grouping rules by id (ids=a,b) | `incidents_rule_delete` |
| GET | `/api/v1/incidents/releases` | A project's releases | `incidents_release_list` |
| POST | `/api/v1/incidents/releases` | Record a release or deploy | `incidents_release_create` |
| GET | `/api/v1/incidents/releases/{version}/artifacts` | A release's source maps and debug files | `incidents_artifact_list` |
| GET | `/api/v1/incidents/github-token` | Whether a GitHub token is set for reproducers (never the token) | `incidents_github_token_get` |
| GET | `/api/v1/incidents/oncall/now` | Who is on call now, and open pages | `incidents_oncall_who` |
| GET | `/api/v1/incidents/oncall/members` | Members who can be put on call | `incidents_oncall_member_list` |
| GET | `/api/v1/incidents/oncall/schedules` | On-call schedules | `incidents_oncall_schedule_list` |
| POST | `/api/v1/incidents/oncall/schedules` | Create an on-call schedule | `incidents_oncall_schedule_set` |
| GET | `/api/v1/incidents/oncall/schedules/{schedule}` | A schedule, optionally with its timeline | `incidents_oncall_schedule_get` |
| PUT | `/api/v1/incidents/oncall/schedules/{id}` | Replace a schedule (send it whole) | `incidents_oncall_schedule_set` |
| DELETE | `/api/v1/incidents/oncall/schedules/{id}` | Delete a schedule | `incidents_oncall_schedule_delete` |
| POST | `/api/v1/incidents/oncall/schedules/{schedule}/overrides` | Put someone on call for a while instead | `incidents_oncall_override` |
| PATCH | `/api/v1/incidents/oncall/overrides/{id}` | Move an override or change who covers it | `incidents_oncall_override_move` |
| DELETE | `/api/v1/incidents/oncall/overrides/{id}` | Delete an override | `incidents_oncall_override_delete` |
| GET | `/api/v1/incidents/oncall/policies` | Escalation policies | `incidents_oncall_policy_list` |
| POST | `/api/v1/incidents/oncall/policies` | Create an escalation policy | `incidents_oncall_policy_set` |
| PUT | `/api/v1/incidents/oncall/policies/{id}` | Replace an escalation policy (send it whole) | `incidents_oncall_policy_set` |
| DELETE | `/api/v1/incidents/oncall/policies/{id}` | Delete an escalation policy | `incidents_oncall_policy_delete` |
| POST | `/api/v1/incidents/oncall/pages` | Page whoever is on call | `incidents_oncall_page_create` |
| POST | `/api/v1/incidents/oncall/pages/{page}/ack` | Acknowledge a page (resolve: true resolves it) | `incidents_oncall_ack` |
| POST | `/api/v1/incidents/oncall/pages/{page}/escalate` | Escalate a page to the next level now | `incidents_oncall_page_escalate` |
| GET | `/api/v1/incidents/oncall/sources` | Inbound alert sources (never their secrets) | `incidents_oncall_source_list` |
| POST | `/api/v1/incidents/oncall/sources` | Add an alert source webhook (its secret is in the answer once) | `incidents_oncall_source_create` |
| PATCH | `/api/v1/incidents/oncall/sources/{id}` | Enable or disable an alert source, or change its policy or severity | `incidents_oncall_source_update` |
| DELETE | `/api/v1/incidents/oncall/sources/{id}` | Delete an alert source | `incidents_oncall_source_delete` |

Also the Incidents API: 51 operations, generated from `services/nodejs-cloud/contracts/incidents-openapi.yaml`. "Key or token" is a Venom API key or an OAuth access token; SDK keys and client ids belong to an environment and are for your app's runtime.

**/me**

| Method | Path | Summary | Auth |
|---|---|---|---|
| GET | `/incidents/api/v1/me` | Who is calling | key or token |

**/projects**

| Method | Path | Summary | Auth |
|---|---|---|---|
| GET | `/incidents/api/v1/projects` | Venom Flags' projects with their environments. | key or token |

**/errors**

| Method | Path | Summary | Auth |
|---|---|---|---|
| GET | `/incidents/api/v1/errors` | List error issues. | key or token |
| GET | `/incidents/api/v1/errors/{id}` | An issue with its counts, releases, tags, flags served, merged issues and activity. | key or token |
| PATCH | `/incidents/api/v1/errors/{id}` | Resolve, ignore, reopen or assign. | key or token |
| GET | `/incidents/api/v1/errors/{id}/events` | The issue's stored events | key or token |
| GET | `/incidents/api/v1/errors/{id}/events/{event}` | One event | key or token |
| POST | `/incidents/api/v1/errors/{id}/merge` | Merge other issues of the project into this one. | key or token |
| POST | `/incidents/api/v1/errors/{id}/split` | Give a merged issue its own fingerprint and count back. | key or token |
| POST | `/incidents/api/v1/errors/{id}/tasks-issue` | File the issue into Venom Tasks with the stack, release and flags; stores the link. | key or token |

**/releases**

| Method | Path | Summary | Auth |
|---|---|---|---|
| GET | `/incidents/api/v1/releases` | A project's releases. | key or token |
| POST | `/incidents/api/v1/releases` | Announce a release from CI. | key or token |
| GET | `/incidents/api/v1/releases/{version}/artifacts` | The release's source maps. | key or token |
| POST | `/incidents/api/v1/releases/{version}/artifacts` | Upload a source map for one generated file. The body is the map (gzip with Content-Encoding for more than 4 MB). | key or token |

**/rules**

| Method | Path | Summary | Auth |
|---|---|---|---|
| GET | `/incidents/api/v1/rules` | A project's fingerprint rules. | key or token |
| POST | `/incidents/api/v1/rules` | Add a fingerprint rule (incidents:admin). | key or token |
| DELETE | `/incidents/api/v1/rules/{id}` | Remove a fingerprint rule (incidents:admin). | key or token |

**/alerts**

| Method | Path | Summary | Auth |
|---|---|---|---|
| GET | `/incidents/api/v1/alerts` | A project's error alert rules. | key or token |
| POST | `/incidents/api/v1/alerts` | Create an alert rule (incidents:admin). kind is new_issue, regression, spike, threshold or slo_burn. | key or token |
| PUT | `/incidents/api/v1/alerts/{id}` | Replace an alert rule (incidents:admin). | key or token |
| DELETE | `/incidents/api/v1/alerts/{id}` | Delete an alert rule (incidents:admin). | key or token |
| POST | `/incidents/api/v1/alerts/test` | What a rule would have fired in the last 24 hours. Nothing is recorded or sent. | key or token |
| GET | `/incidents/api/v1/alerts/hits` | Recent alert hits. | key or token |
| POST | `/incidents/api/v1/alerts/seen` | Mark the bell's alert hits as seen for the caller. | key or token |

**/incidents**

| Method | Path | Summary | Auth |
|---|---|---|---|
| GET | `/incidents/api/v1/incidents` | List incidents, worst severity first. | key or token |
| POST | `/incidents/api/v1/incidents` | Declare an incident. The opener becomes the commander unless an agent opens it. | key or token |
| GET | `/incidents/api/v1/incidents/{ref}` | An incident with its links and timeline. | key or token |
| PATCH | `/incidents/api/v1/incidents/{ref}` | Change status, severity, title, summary, projects, environments or a role. A status change is a timeline entry. | key or token |
| POST | `/incidents/api/v1/incidents/{ref}/updates` | Post a status update (kind status_update, may move the status; public shows it on the status page) or an internal note. | key or token |
| POST | `/incidents/api/v1/incidents/{ref}/links` | Link an error issue (id), a flag (project/key), a release (version) or a Tasks issue (key). | key or token |
| DELETE | `/incidents/api/v1/incidents/{ref}/links` | Remove a link. | key or token |
| GET | `/incidents/api/v1/incidents/{ref}/implicate` | Rank what changed before the incident's error spike (Flags changes and releases), each with a confidence and the evidence. | key or token |
| POST | `/incidents/api/v1/incidents/{ref}/rollback` | Roll back the top-ranked flag change (or the one named by flag or auditId) as a normal Flags revert. Where the environment needs approvals, files a request to turn the flag off. | key or token |
| POST | `/incidents/api/v1/incidents/{ref}/postmortem` | Write the incident's blameless postmortem into Venom Notes (or return the existing one). ai drafts the prose with the org's model; fileActions files the note's unchecked action items in Tasks. | key or token |
| GET | `/incidents/api/v1/incidents/{ref}/eval-case` | The eval case drafted from the regression behind the incident (VEN-246), or draft null with a reason. | key or token |
| POST | `/incidents/api/v1/incidents/{ref}/eval-case` | Draft it, or draft it again, from the incident's linked fix or revert commit, or the merged pull requests and commits on its Tasks issue. A draft for a person to review; nothing runs an eval or calls a model. 200 with a reason and no draft when nothing is linked. Needs incidents:write. | key or token |
| GET | `/incidents/api/v1/incidents/{ref}/reproducer` | The incident's reproducer runs (VEN-246, ADR 0076), newest first, with each draft PR's CI outcome as the GitHub webhook reports it. | key or token |
| POST | `/incidents/api/v1/incidents/{ref}/reproducer` | Write a failing test with the org's own model and open it as a draft pull request on a new branch venom/reproducer-<ref>, through the org's GitHub write token. New test files only (never under .github/ or outside the repository). One run at a time per incident, a daily cap. Needs incidents:write. 409 no_github_token (no token set), no_repo, reproducer_running or branch_exists; 422 reproducer_refused (a proposed file failed the path checks; nothing was written); 429 reproducer_cap. | key or token |
| POST | `/incidents/sdk/events` | Send one event, a list of up to 100, or {events, release}. 200 KB at most. | SDK key or client id |

**/rollback**

| Method | Path | Summary | Auth |
|---|---|---|---|
| POST | `/incidents/api/v1/rollback` | Undo a Flags change with no incident behind it, and write a short postmortem. | key or token |

**/github-token**

| Method | Path | Summary | Auth |
|---|---|---|---|
| GET | `/incidents/api/v1/github-token` | Whether the org's GitHub write token for reproducer PRs is set (its last four characters and the default repository; never the token). | key or token |
| PUT | `/incidents/api/v1/github-token` | Save or replace the token (a fine-grained personal access token with Contents and Pull requests read and write), sealed in the vault, and the default repository. An owner or admin in person; agents are refused. | key or token |
| DELETE | `/incidents/api/v1/github-token` | Remove the token. An owner or admin in person. | key or token |

**/settings**

| Method | Path | Summary | Auth |
|---|---|---|---|
| GET | `/incidents/api/v1/settings` | The loop's settings per project and environment (automatic rollback, confidence, the Tasks team and triage agent, postmortems). | key or token |
| PUT | `/incidents/api/v1/settings` | Change them for a project (env empty) or an environment. Needs incidents:admin. Automatic rollback is off until set. | key or token |

**/oncall**

| Method | Path | Summary | Auth |
|---|---|---|---|
| GET | `/incidents/api/v1/oncall/{path}` | Read on-call. now (who is on call), members, schedules, schedules/{id}/timeline?from=&to= (segments), policies, pages?status=, sources (admin). | key or token |
| POST | `/incidents/api/v1/oncall/{path}` | Create or act. schedules (name, tz, rotations[{members, startDate, handoff, lengthDays, layer, restriction}]), schedules/{id}/overrides (member, startAt, endAt), policies (name, levels[{targets, delayMin}], repeat, slackChannel, isDefault), pages (title, policy), pages/{id}/ack\|resolve\|escalate, sources (name, kind, escalationId, openIncident; the secret is returned once). | key or token |
| PUT | `/incidents/api/v1/oncall/{path}` | Replace a schedule (schedules/{id}) or a policy (policies/{id}); If-Match names the version. | key or token |
| PATCH | `/incidents/api/v1/oncall/{path}` | Turn a source on or off, or change what it opens (sources/{id}); move an override to a new window, optionally to someone else (overrides/{id} with startAt, endAt, member?). | key or token |
| DELETE | `/incidents/api/v1/oncall/{path}` | Delete a schedule, override, policy or source. | key or token |

**/inbound**

| Method | Path | Summary | Auth |
|---|---|---|---|
| POST | `/incidents/api/v1/inbound/{id}` | Alerts from Alertmanager, Grafana or any JSON sender. Authenticated by the source's secret (Authorization Bearer, or X-Venom-Signature sha256=HMAC of the body, optionally with X-Venom-Timestamp). Firing pages the policy and may open an incident; resolved resolves the page. | none |

The on-call routes are one catch-all, `/incidents/api/v1/oncall/{path}`: `now`, `members`, `schedules`,
`schedules/{id}`, `schedules/{id}/timeline`, `schedules/{id}/overrides`, `overrides/{id}`, `policies`,
`policies/{id}`, `pages`, `pages/{id}/ack`, `pages/{id}/resolve`, `pages/{id}/escalate`, `sources` and `sources/{id}`.
See [On-call](/docs/incidents/on-call.md#rest).

Every Incidents tool also has a route on the workspace REST twin, under `/api/v1/incidents` with the same paths
(`GET /api/v1/incidents/errors`, `PATCH /api/v1/incidents/incidents/{ref}`, `GET /api/v1/incidents/oncall/now` and so
on). It takes the credentials `/workspace/mcp` takes, an OAuth token for the workspace included, and a request becomes
the tool's arguments by name (camelCase, as the tools take them). `If-Match` fills `expectVersion`. A few twin routes
take a list in place of a path id: `POST /api/v1/incidents/errors/split` (`ids`), `DELETE /api/v1/incidents/alerts`
and `DELETE /api/v1/incidents/rules` (`?ids=a,b`). See [REST](/docs/developers/rest.md).

## MCP tools {#tools}

56 tools: 24 read, 32 write. Generated from the code; "write (destructive)" is the tool's `destructiveHint`. A tool with a REST route is the same call over HTTP.

| Tool | Title | Access | Scope | REST route |
|---|---|---|---|---|
| `incidents_alert_delete` | Delete error alert rules | write (destructive) | `incidents:admin` | `DELETE /api/v1/incidents/alerts` |
| `incidents_alert_hit_list` | List alert hits | read | `incidents:read` | `GET /api/v1/incidents/alerts/hits` |
| `incidents_alert_list` | List error alert rules | read | `incidents:read` | `GET /api/v1/incidents/alerts` |
| `incidents_alert_set` | Create, change, test or delete an error alert rule | write | `incidents:admin` | `POST /api/v1/incidents/alerts` (+1) |
| `incidents_alert_test` | Dry-run an alert rule | read | `incidents:read` | `POST /api/v1/incidents/alerts/test` |
| `incidents_artifact_list` | List a release's source maps | read | `incidents:read` | `GET /api/v1/incidents/releases/{version}/artifacts` |
| `incidents_error_file` | File an error issue into Tasks | write | `incidents:write` | `POST /api/v1/incidents/errors/{id}/tasks-issue` |
| `incidents_error_get` | Read an error issue | read | `incidents:read` | `GET /api/v1/incidents/errors/{id}` |
| `incidents_error_list` | List error issues | read | `incidents:read` | `GET /api/v1/incidents/errors` |
| `incidents_error_merge` | Merge error issues | write | `incidents:write` | `POST /api/v1/incidents/errors/{into}/merge` |
| `incidents_error_split` | Split a merged error issue | write | `incidents:write` | `POST /api/v1/incidents/errors/split` |
| `incidents_error_update` | Resolve, ignore, assign or merge an error issue | write | `incidents:write` | `PATCH /api/v1/incidents/errors/{id}` |
| `incidents_eval_case_draft` | Draft an eval case from an incident | write | `incidents:write` | `POST /api/v1/incidents/incidents/{ref}/eval-case` |
| `incidents_eval_case_get` | Read an incident's eval case draft | read | `incidents:read` | `GET /api/v1/incidents/incidents/{ref}/eval-case` |
| `incidents_event_get` | Read one error event | read | `incidents:read` | `GET /api/v1/incidents/errors/{id}/events/{event}` |
| `incidents_event_list` | List an error issue's events | read | `incidents:read` | `GET /api/v1/incidents/errors/{id}/events` |
| `incidents_github_token_get` | Is a GitHub write token set for reproducers | read | `incidents:read` | `GET /api/v1/incidents/github-token` |
| `incidents_incident_get` | Read an incident | read | `incidents:read` | `GET /api/v1/incidents/incidents/{ref}` |
| `incidents_incident_implicate` | What changed before the spike | read | `incidents:read` | `GET /api/v1/incidents/incidents/{ref}/implicate` |
| `incidents_incident_list` | List incidents | read | `incidents:read` | `GET /api/v1/incidents/incidents` |
| `incidents_incident_open` | Declare an incident | write | `incidents:write` | `POST /api/v1/incidents/incidents` |
| `incidents_incident_postmortem` | Write the postmortem | write | `incidents:write` | `POST /api/v1/incidents/incidents/{ref}/postmortem` |
| `incidents_incident_rollback` | Roll back the implicated flag | write (destructive) | `incidents:write` | `POST /api/v1/incidents/incidents/{ref}/rollback` (+1) |
| `incidents_incident_update` | Update an incident | write | `incidents:write` | `PATCH /api/v1/incidents/incidents/{ref}` |
| `incidents_link_create` | Link things to an incident | write | `incidents:write` | `POST /api/v1/incidents/incidents/{ref}/links` |
| `incidents_link_delete` | Unlink from an incident | write (destructive) | `incidents:write` | `DELETE /api/v1/incidents/incidents/{ref}/links` |
| `incidents_oncall_ack` | Acknowledge a page | write | `incidents:write` | `POST /api/v1/incidents/oncall/pages/{page}/ack` |
| `incidents_oncall_member_list` | List members to put on call | read | `incidents:read` | `GET /api/v1/incidents/oncall/members` |
| `incidents_oncall_override` | Cover a shift | write | `incidents:write` | `POST /api/v1/incidents/oncall/schedules/{schedule}/overrides` |
| `incidents_oncall_override_delete` | Remove a shift cover | write (destructive) | `incidents:write` | `DELETE /api/v1/incidents/oncall/overrides/{id}` |
| `incidents_oncall_override_move` | Move a shift cover | write | `incidents:write` | `PATCH /api/v1/incidents/oncall/overrides/{id}` |
| `incidents_oncall_page_create` | Page the on-call | write | `incidents:write` | `POST /api/v1/incidents/oncall/pages` |
| `incidents_oncall_page_escalate` | Escalate a page now | write | `incidents:write` | `POST /api/v1/incidents/oncall/pages/{page}/escalate` |
| `incidents_oncall_policy_delete` | Delete an escalation policy | write (destructive) | `incidents:admin` | `DELETE /api/v1/incidents/oncall/policies/{id}` |
| `incidents_oncall_policy_list` | List escalation policies | read | `incidents:read` | `GET /api/v1/incidents/oncall/policies` |
| `incidents_oncall_policy_set` | Create or replace an escalation policy | write | `incidents:admin` | `POST /api/v1/incidents/oncall/policies` (+1) |
| `incidents_oncall_schedule_delete` | Delete an on-call schedule | write (destructive) | `incidents:admin` | `DELETE /api/v1/incidents/oncall/schedules/{id}` |
| `incidents_oncall_schedule_get` | Read an on-call schedule | read | `incidents:read` | `GET /api/v1/incidents/oncall/schedules/{schedule}` |
| `incidents_oncall_schedule_list` | List on-call schedules | read | `incidents:read` | `GET /api/v1/incidents/oncall/schedules` |
| `incidents_oncall_schedule_set` | Create or replace an on-call schedule | write | `incidents:admin` | `POST /api/v1/incidents/oncall/schedules` (+1) |
| `incidents_oncall_source_create` | Add an alert source | write | `incidents:admin` | `POST /api/v1/incidents/oncall/sources` |
| `incidents_oncall_source_delete` | Delete an alert source | write (destructive) | `incidents:admin` | `DELETE /api/v1/incidents/oncall/sources/{id}` |
| `incidents_oncall_source_list` | List alert sources | read | `incidents:admin` | `GET /api/v1/incidents/oncall/sources` |
| `incidents_oncall_source_update` | Change an alert source | write | `incidents:admin` | `PATCH /api/v1/incidents/oncall/sources/{id}` |
| `incidents_oncall_who` | Who is on call | read | `incidents:read` | `GET /api/v1/incidents/oncall/now` |
| `incidents_project_list` | List projects and environments | read | `incidents:read` | `GET /api/v1/incidents/projects` |
| `incidents_release_create` | Record a release | write | `incidents:write` | `POST /api/v1/incidents/releases` |
| `incidents_release_list` | List releases | read | `incidents:read` | `GET /api/v1/incidents/releases` |
| `incidents_reproducer_get` | Read an incident's reproducer PRs | read | `incidents:read` | `GET /api/v1/incidents/incidents/{ref}/reproducer` |
| `incidents_reproducer_write` | Write a reproducer PR for an incident | write | `incidents:write` | `POST /api/v1/incidents/incidents/{ref}/reproducer` |
| `incidents_rule_create` | Create a fingerprint rule | write | `incidents:admin` | `POST /api/v1/incidents/rules` |
| `incidents_rule_delete` | Delete fingerprint rules | write (destructive) | `incidents:admin` | `DELETE /api/v1/incidents/rules` |
| `incidents_rule_list` | List fingerprint rules | read | `incidents:read` | `GET /api/v1/incidents/rules` |
| `incidents_setting_get` | Read the incident loop's settings | read | `incidents:read` | `GET /api/v1/incidents/settings` |
| `incidents_setting_update` | Change the incident loop's settings | write | `incidents:admin` | `PUT /api/v1/incidents/settings` |
| `incidents_update_create` | Post an incident update | write | `incidents:write` | `POST /api/v1/incidents/incidents/{ref}/updates` |

## Related {#related}

- [Venom Incidents](/docs/incidents.md), [Error issues](/docs/incidents/errors.md), [Incidents](/docs/incidents/incidents.md), [The loop](/docs/incidents/the-loop.md), [Alerts](/docs/incidents/alerts.md) and [On-call](/docs/incidents/on-call.md).
- [Authentication and scopes](/docs/developers/auth.md), [Errors, limits and pagination](/docs/developers/conventions.md), [Webhooks](/docs/developers/webhooks.md), [MCP](/docs/developers/mcp.md) and [REST](/docs/developers/rest.md).
