# Alerting

> Incidents, notification channels, routes, silences and the delivery log

Source: https://www.apitraffic.io/docs/api-reference/alerting

The alerting API manages what the [Alerts](https://www.apitraffic.io/docs/alerts) pages show. Every path is scoped to an account, and an account can only reach its own records.

**Permissions.** Creating, changing and deleting channels, changing routes and redelivering notifications need an owner or admin (or an API token with the `administrator` role). Silences longer than 24 hours need an owner or admin too. Everything else is open to any member. Ingest tokens can't use this API.

**Secrets.** Channel credentials are write-only. Responses carry a short `secretHint` instead. A webhook's signing secret is returned once, in the create (and rotate) response, as `signingSecret`.

All examples use `Authorization: Bearer `.

## Incidents

`GET https://api.apitraffic.io/v1/accounts/{accountSid}/incidents`

List incidents, newest first.

- **status (query, string)**:
  `open`, `acknowledged` or `resolved`

- **active (query, boolean)**:
  Only incidents that are not resolved (`open` or `acknowledged`). Ignored when `status` is set

- **severity (query, string)**:
  `critical`, `warning` or `info`

- **bucketSid (query, string)**:
  Only incidents in this bucket

- **environmentSid (query, string)**:
  Only incidents in this environment

- **include (query, string)**:
  `alerts` adds each incident's unresolved alerts, with the detector row that raised each one

- **before (query, string)**:
  ISO 8601. Page backwards: incidents opened before this time (pass the oldest `openedAt` you have)

- **limit (query, number)**:
  Default 50, at most 200

### Response

- **hasMore (boolean)**:
  More incidents exist before the oldest returned

- **alertingActive (boolean)**:
  Whether alerting is running. While it is `false`, nothing opens incidents, so an empty list doesn't mean nothing is wrong

- **records (array)**:

**Incident objects**

- **sid (string)**: Incident ID (`inc_…`)

- **reference (string)**: `INC-142`

- **title (string)**: What is wrong

- **severity (string)**: `critical`, `warning` or `info`

- **status (string)**: `open`, `acknowledged` or `resolved`

- **openedAt (string)**: ISO 8601

- **acknowledgedAt (string)**: ISO 8601 or null

- **resolvedAt (string)**: ISO 8601 or null

- **sources (array)**: What raised its alerts, for example `attention`, `drift`, `alerting`

- **labels (object)**: Labels of its alerts

- **alerts (array)**: With `include=alerts` only. Its unresolved alerts, worst first: `source` (`attention`, `drift`, …), `sourceRef` (the attention signal or drift finding ID that raised it), `severity` and `title`

`GET https://api.apitraffic.io/v1/accounts/{accountSid}/incidents/{incidentSid}`

One incident with its alerts, its timeline, and every notification with why it was or wasn't sent (`why`, `status`, `statusReason`, `lastError`, `nextAttemptAt`).

`PATCH https://api.apitraffic.io/v1/accounts/{accountSid}/incidents/{incidentSid}`

Acknowledge, resolve, reopen, assign or rename an incident. Acknowledging cancels escalation steps and reminders.

- **status (body, string)**:
  `acknowledged`, `resolved`, or `open` to reopen

- **ownerUserSid (body, string)**:
  The user who owns it, or null

- **title (body, string)**:
  A new title (1–200 characters)

```bash
curl -X PATCH "https://api.apitraffic.io/v1/accounts/acc_…/incidents/inc_…" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"status": "acknowledged"}'
```

`POST https://api.apitraffic.io/v1/accounts/{accountSid}/incidents/{incidentSid}/comments`

Add a comment. Channels already told about the incident receive it.

- **body (body, string, required)**:
  The comment (1–2,000 characters)

## Channels

`GET https://api.apitraffic.io/v1/accounts/{accountSid}/alerting/providers`

The channel types you can create, with what each supports (`capabilities.digest`, `capabilities.supportsTagValues`, …).

`GET https://api.apitraffic.io/v1/accounts/{accountSid}/notificationChannels`

List channels with their `status` (`healthy`, `pending_verification`, `failing`, `disabled`), `statusReason`, `lastSuccessAt` and `lastFailureAt`.

`GET https://api.apitraffic.io/v1/accounts/{accountSid}/notificationChannels/{channelSid}`

One channel.

`POST https://api.apitraffic.io/v1/accounts/{accountSid}/notificationChannels`

Create a channel. It starts as `pending_verification` until a test or delivery gets through.

> **Note:** Owners and admins only (API tokens with the `administrator` role).

- **type (body, string, required)**:
  `webhook`, `slack_webhook`, `email`, `pagerduty` or `jira`

- **name (body, string, required)**:
  Up to 120 characters

- **config (body, object)**:
  Settings for the type (below)

- **secret (body, string)**:
  The credential for the type (below). Never returned

- **includeTagValues (body, boolean)**:
  Show tag values (such as customer IDs) in notifications. Default false

| `type` | `config` | `secret` |
|---|---|---|
| `webhook` | `{"url": "https://…"}` | none: a signing secret is generated and returned once as `signingSecret` |
| `slack_webhook` | `{}` | the Slack incoming webhook URL |
| `email` | `{"recipients": {"roles": ["owner","admin"], "addresses": ["oncall@example.com"], "userSids": []}}` | none |
| `pagerduty` | `{"region": "us"}` or `"eu"` | the Events API v2 integration key |
| `jira` | `{"deployment": "cloud", "baseUrl": "https://your-site.atlassian.net", "email": "ops@example.com", "projectKey": "OPS", "issueType": "Task", "resolveStatus": "Done", "priorities": {"critical": "Highest"}}` | an API token (Cloud) or personal access token (Data Center) |

```bash
curl -X POST "https://api.apitraffic.io/v1/accounts/acc_…/notificationChannels" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"type": "webhook", "name": "Ops webhook", "config": {"url": "https://hooks.example.com/apitraffic"}}'
```

`PATCH https://api.apitraffic.io/v1/accounts/{accountSid}/notificationChannels/{channelSid}`

Change a channel's `name`, `config`, `secret` or `includeTagValues`. Changing the config sets it back to `pending_verification`. For Jira, changing `baseUrl`, `deployment` or `email` needs the `secret` again.

> **Note:** Owners and admins only (API tokens with the `administrator` role).

`DELETE https://api.apitraffic.io/v1/accounts/{accountSid}/notificationChannels/{channelSid}`

Delete a channel and destroy its credentials. Refused when it is the only channel of a step of the default route.

> **Note:** Owners and admins only (API tokens with the `administrator` role).

`POST https://api.apitraffic.io/v1/accounts/{accountSid}/notificationChannels/{channelSid}/test`

Send a test notification now. The response has `ok`, `category`, `statusCode`, `latencyMs`, `responseExcerpt` and `traceId`.

`POST https://api.apitraffic.io/v1/accounts/{accountSid}/notificationChannels/{channelSid}/rotateSecret`

Webhooks only: generate a new signing secret, returned once as `signingSecret`. The previous secret keeps signing for 24 hours.

> **Note:** Owners and admins only (API tokens with the `administrator` role).

`GET https://api.apitraffic.io/v1/accounts/{accountSid}/notificationChannels/{channelSid}/deliveries`

The delivery log, newest first: each attempt with `incidentReference`, `attempt`, `category`, `statusCode`, `latencyMs`, `responseExcerpt`, `nextAttemptAt` and `notificationStatus`. Viewing it is recorded in the account's activity history.

- **limit (query, number)**:
  Default 100, at most 500

`POST https://api.apitraffic.io/v1/accounts/{accountSid}/notifications/{notificationSid}/redeliver`

Send a notification again.

> **Note:** Owners and admins only (API tokens with the `administrator` role).

## Routes

`GET https://api.apitraffic.io/v1/accounts/{accountSid}/notificationRoutes`

List routes in the order they are tried. The default route (`isFallback: true`) is last.

`POST https://api.apitraffic.io/v1/accounts/{accountSid}/notificationRoutes`

Create a route.

> **Note:** Owners and admins only (API tokens with the `administrator` role).

- **name (body, string, required)**:
  Up to 120 characters

- **steps (body, array, required)**:
  1–5 steps: `[{"afterMs": 0, "channelSids": ["ch_…"]}, {"afterMs": 900000, "channelSids": ["ch_…"]}]`. The first step has `afterMs` 0; each later one waits longer, at most 24 hours

- **match (body, object)**:
  `severity` (for example `">= warning"` or `"critical"`), `sources`, `buckets`, `environments`, `labels`. Empty matches everything

- **quietHours (body, object)**:
  `{"tz": "Europe/Berlin", "from": "20:00", "to": "08:00", "days": ["mon","tue"], "allowCritical": true}` or null

- **digest (body, boolean)**:
  Batch anything below critical into a digest

- **digestSchedule (body, object)**:
  `{"every": "hourly"}` or `{"every": "daily", "at": "09:00", "tz": "Europe/Berlin"}`

- **repeatUnackedEveryMs (body, number)**:
  Critical incidents only: remind the first step this often while unacknowledged (15 minutes to 24 hours), or null

- **continue (body, boolean)**:
  Keep trying later routes after this one matches

- **enabled (body, boolean)**:
  Default true

`PATCH https://api.apitraffic.io/v1/accounts/{accountSid}/notificationRoutes/{routeSid}`

Change a route. Send only the fields to change. The default route can't be disabled.

> **Note:** Owners and admins only (API tokens with the `administrator` role).

`PUT https://api.apitraffic.io/v1/accounts/{accountSid}/notificationRoutes/order`

Set the order routes are tried in.

> **Note:** Owners and admins only (API tokens with the `administrator` role).

- **routeSids (body, array, required)**:
  Every non-default route, in order

`DELETE https://api.apitraffic.io/v1/accounts/{accountSid}/notificationRoutes/{routeSid}`

Delete a route. The default route can't be deleted.

> **Note:** Owners and admins only (API tokens with the `administrator` role).

## Silences

`GET https://api.apitraffic.io/v1/accounts/{accountSid}/silences`

Active and scheduled silences.

- **includeExpired (query, boolean)**:
  Include ended silences

`POST https://api.apitraffic.io/v1/accounts/{accountSid}/silences`

Create a silence. Incidents still open and show; nobody is notified about matching ones.

- **matchers (body, object, required)**:
  At least one of `severity`, `environments`, `buckets`, `labels`, `sources`, `fingerprints` (specific alerts)

- **endsAt (body, string, required)**:
  ISO 8601. At most 30 days after the start; more than 24 hours needs an owner or admin

- **startsAt (body, string)**:
  ISO 8601. Default now

- **comment (body, string)**:
  Why, shown to your team

`DELETE https://api.apitraffic.io/v1/accounts/{accountSid}/silences/{silenceSid}`

End a silence now.