Alerting Beta

Decide who hears about an outage. A monitor can alert people in your workspace, contacts who have no login, and named teams, and you can read back every alert that was sent.

Every endpoint in this group needs an X-API-Key header, and each call counts once against your daily quota. Reading needs access to uptime monitoring in the app; changing contacts and teams needs permission to manage uptime monitors. See Monitoring API: getting started for authentication, rate limits and errors.

Endpoints

Method	Endpoint	Does
`GET`	`/api/v1/alerts`	Alert history, filtered by monitor, event, status or time
`GET`	`/api/v1/alerting/contacts`	List alert contacts
`POST`	`/api/v1/alerting/contacts`	Create a contact
`GET`	`/api/v1/alerting/contacts/{id}`	One contact
`PATCH`	`/api/v1/alerting/contacts/{id}`	Change a contact and its addresses
`DELETE`	`/api/v1/alerting/contacts/{id}`	Delete a contact
`DELETE`	`/api/v1/alerting/contacts?ids=…`	Delete several contacts
`GET`	`/api/v1/alerting/teams`	List teams
`POST`	`/api/v1/alerting/teams`	Create a team
`GET`	`/api/v1/alerting/teams/{id}`	One team
`PATCH`	`/api/v1/alerting/teams/{id}`	Change a team and its members
`DELETE`	`/api/v1/alerting/teams/{id}`	Delete a team
`DELETE`	`/api/v1/alerting/teams?ids=…`	Delete several teams

Who gets alerted

A monitor alerts its own members (recipients, people in your workspace), its contacts (contacts) and its teams (teams). Set all three in the monitor settings.
Everyone is merged and de-duplicated by address, so somebody who is a member, in a team and a contact still gets one email.
Contacts are people without a RankNibbler login, such as a client or an out-of-hours number. Each has one or more addresses.
Teams are named groups of workspace members and contacts, so a monitor can alert "Support" rather than eight people.

Severity

Each address has a severity:

all: every alert for every monitor it covers.
high: only monitors marked importance: "high". Use it for an address that should only hear about the things that matter most.

Opting out

Every alert to a contact carries an opt-out link. Using it stops alerts to that one address, leaving the contact and its other addresses alone. The address then shows optedOut: true.

This can't be undone through the API, by design: the person asked not to be emailed, so they have to ask to be added again. Workspace members don't get an opt-out link; they manage alerts in the app.

Channels

Alerts are sent by email. kind is email on every method today. Other channels, such as SMS, are planned, and kind is there so nothing has to change when they arrive.

The contact object

contact

{
"id": "ct_5b8d1f0a9c2e4d6f7a83",
"name": "Night shift",
"methods": [
{ "id": "318", "kind": "email", "target": "[email protected]", "severity": "all", "optedOut": false },
{ "id": "319", "kind": "email", "target": "[email protected]", "severity": "high", "optedOut": false }
],
"createdAt": "2026-09-17T09:02:11.000Z",
"updatedAt": "2026-09-17T09:02:11.000Z"
}

Field	Type	Description
`id`	string	The contact id, starting `ct_`.
`name`	string	What you call this contact. Up to 120 characters.
`methods`	object[]	How to reach them, up to 5.
`methods[].id`	string	The address id.
`methods[].kind`	string	`email`.
`methods[].target`	string	The email address.
`methods[].severity`	string	`all` or `high`.
`methods[].optedOut`	boolean	`true` when the person used the opt-out link. That address is no longer alerted.
`createdAt`, `updatedAt`	string	When the contact was created and last changed.

The team object

team

{
"id": "tm_2c7e91a4b6d0f3e85a17",
"name": "Support",
"userIds": [42, 57],
"users": [
{ "id": 42, "name": "Sam Taylor", "email": "[email protected]" },
{ "id": 57, "name": "Ada Okoro", "email": "[email protected]" }
],
"contactIds": ["ct_5b8d1f0a9c2e4d6f7a83"],
"contacts": [{ "id": "ct_5b8d1f0a9c2e4d6f7a83", "name": "Night shift" }],
"createdAt": "2026-09-17T09:10:40.000Z",
"updatedAt": "2026-09-17T09:10:40.000Z"
}

Field	Type	Description
`id`	string	The team id, starting `tm_`.
`name`	string	The team name. Up to 120 characters.
`userIds`, `users`	integer[], object[]	Workspace members in the team, as ids and as `{ id, name, email }`.
`contactIds`, `contacts`	string[], object[]	Contacts in the team, as ids and as `{ id, name }`.
`createdAt`, `updatedAt`	string	When the team was created and last changed.

Monitor settings: point a monitor at contacts and teams
Alert history: what was actually sent
Maintenance windows: hold alerts back during planned work