Skip to content
Docs menu

Build on Venom Incidents

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.

View .md

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

  • 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

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

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

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

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:

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

  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.
  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

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

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; a Sentry DSN can point here too (Migrate from Sentry).

Events

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

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.
  • Public status updates (public: true) reach the status page's subscribers as status.incident.* deliveries. See Build on the Status page.

REST routes

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).

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.

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.

MCP 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