Alerting

The alerting API manages what the 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)

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

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.