# Alerts

Alert rules on a project's metrics, their history, and the team's alert channels.

Source: https://docs.orbits.africa/api/alerts

An alert watches one of a project's metrics over a window and notifies the team's channels when it crosses its threshold, and again when it recovers. Preview a rule against recent data before saving it. See [Alerts](https://docs.orbits.africa/observe/alerts).

Endpoints:

- `GET /v1/teams/{team}/projects/{project}/alerts`: A project's alert rules and their state
- `POST /v1/teams/{team}/projects/{project}/alerts`: Create an alert rule
- `POST /v1/teams/{team}/projects/{project}/alerts/preview`: How much traffic a draft rule would see
- `PATCH /v1/teams/{team}/projects/{project}/alerts/{alert}`: Change or switch an alert rule
- `DELETE /v1/teams/{team}/projects/{project}/alerts/{alert}`: Delete an alert rule
- `GET /v1/teams/{team}/projects/{project}/alerts/{alert}/events`: When a rule fired and resolved
- `GET /v1/teams/{team}/alert-channels`: The team's alert webhook
- `PUT /v1/teams/{team}/alert-channels/webhook`: Set the team's alert webhook
- `DELETE /v1/teams/{team}/alert-channels/webhook`: Remove the team's alert webhook
- `POST /v1/teams/{team}/alert-channels/webhook/test`: Send a test event to the webhook

## The alert object



- `id` (string, required)
- `name` (string, required): At most 60 characters.
- `metric` (string, required): `error-rate`: 5xx responses as a share of requests, in %. `p75`, `p99`: response time in ms. `requests`: requests per minute. One of `error-rate`, `p75`, `p99`, `requests`.
- `direction` (string, required): `below` only for `requests`. One of `above`, `below`.
- `threshold` (number, required)
- `window_minutes` (integer, required): One of `1`, `5`, `10`, `30`.
- `routes` (array of string, required): Routes as Observability names them; a trailing `*` matches a prefix. Empty for all routes.
- `channels` (array of string, required)
- `on` (boolean, required)
- `state` (string, required): One of `ok`, `firing`.
- `since` (string, required): When it last fired or resolved, or was created or changed.
- `last_value` (number or null, required): The value at the last check; null before one, or with too little traffic.
- `checked_at` (string or null, required)
- `created_at` (string, required)
- `updated_at` (string, required)
## A project's alert rules and their state

```http
GET /v1/teams/{team}/projects/{project}/alerts
```

The Alerts card on Observability: every rule of the project, oldest first, with its state. A rule watches production's requests (the same traffic as Observability) and is checked every minute, at :30, over its last `window_minutes` whole minutes. It fires as soon as its value is past the line (above `threshold`, or below it for `direction: below`), and resolves after 3 checks in a row back on the right side. `error-rate`, `p75` and `p99` need 20 requests in the window to say anything: under that a rule can't fire, and `last_value` is null. A firing rule counts such a check toward resolving, unless what few requests there were are still past the line, and resolves with `reason: quiet` when the last of the 3 is one. `webhook_configured` says whether `webhook` can be offered as a channel.

**Permissions:** Any team member. A non-member gets 404.

Token: any API token (`read` or `full`).

Path parameters:

- `team`: Team slug or `team_` id.
- `project`: Project slug or `prj_` id.

Example:

```sh
curl "https://api.theorbits.app/v1/teams/my-team/projects/my-app/alerts" \
  -H "Authorization: Bearer $ORBITS_TOKEN"
```

Response `200`:

```json
{
  "items": [
    {
      "id": "alr_7f3c2a1e-0d4b-4c55-9a7e-2b1f6c0d9e11",
      "name": "my-app",
      "metric": "error-rate",
      "direction": "above",
      "threshold": 1,
      "window_minutes": 1,
      "routes": [
        "routes"
      ],
      "channels": [
        "webhook"
      ],
      "on": false,
      "state": "ok",
      "since": "2026-11-10T09:30:00Z",
      "last_value": null,
      "checked_at": "2026-11-10T09:30:00Z",
      "created_at": "2026-11-10T09:30:00Z",
      "updated_at": "2026-11-10T09:30:00Z"
    }
  ],
  "webhook_configured": false
}
```

Errors:

- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
## Create an alert rule

```http
POST /v1/teams/{team}/projects/{project}/alerts
```

The Create alert form. The rule starts `ok` and is first checked at the next :30. 422 names the field: a name already used in the project, `direction: below` for anything but `requests`, an `error-rate` threshold of 100 or more, a route that doesn't start with `/` or has a `*` anywhere but the end, or `webhook` in `channels` while the team has no webhook (`webhook_configured` on the list).

**Permissions:** Owner, admin or member of the team. Viewers get 403. A non-member gets 404.

Token: a `full` API token. Send an `Idempotency-Key` header.

Path parameters:

- `team`: Team slug or `team_` id.
- `project`: Project slug or `prj_` id.

Body:

- `name` (string, required): At most 60 characters.
- `metric` (string, required): `error-rate`: 5xx responses as a share of requests, in %. `p75`, `p99`: response time in ms. `requests`: requests per minute. One of `error-rate`, `p75`, `p99`, `requests`.
- `direction` (string): One of `above`, `below`. Defaults to `above`.
- `threshold` (number, required): At most 1000000.
- `window_minutes` (integer, required): One of `1`, `5`, `10`, `30`.
- `routes` (array of string): At most 10 items.
- `channels` (array of string, required)
- `on` (boolean): Defaults to `true`.

Example:

```sh
curl -X POST "https://api.theorbits.app/v1/teams/my-team/projects/my-app/alerts" \
  -H "Authorization: Bearer $ORBITS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-app",
    "metric": "error-rate",
    "threshold": 1,
    "window_minutes": 1,
    "channels": [
      "webhook"
    ]
  }'
```

Response `201`:

```json
{
  "id": "alr_7f3c2a1e-0d4b-4c55-9a7e-2b1f6c0d9e11",
  "name": "my-app",
  "metric": "error-rate",
  "direction": "above",
  "threshold": 1,
  "window_minutes": 1,
  "routes": [
    "routes"
  ],
  "channels": [
    "webhook"
  ],
  "on": false,
  "state": "ok",
  "since": "2026-11-10T09:30:00Z",
  "last_value": null,
  "checked_at": "2026-11-10T09:30:00Z",
  "created_at": "2026-11-10T09:30:00Z",
  "updated_at": "2026-11-10T09:30:00Z"
}
```

Errors:

- `403`: Authenticated but not allowed in this team.
- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
- `422`: Validation failed, or the Idempotency-Key was reused with a different body.
## How much traffic a draft rule would see

```http
POST /v1/teams/{team}/projects/{project}/alerts/preview
```

For the Create and Edit forms. `median_requests` is the median number of requests a window of this size held over the last 24 hours on these routes (minutes without traffic count as none). When it is under `minimum_requests` (20 for `error-rate`, `p75` and `p99`; 0 for `requests`), warn under the window field, for example "These routes get about 6 requests in 1 minute. The rule won't fire until a window has 20. Try 5 or 10 minutes." It is a warning: the form can still be saved. `value` is what the rule would measure now, or null with too little traffic.

**Permissions:** Owner, admin or member of the team. Viewers get 403. A non-member gets 404.

Token: a `full` API token. Send an `Idempotency-Key` header.

Path parameters:

- `team`: Team slug or `team_` id.
- `project`: Project slug or `prj_` id.

Body:

- `metric` (string, required): `error-rate`: 5xx responses as a share of requests, in %. `p75`, `p99`: response time in ms. `requests`: requests per minute. One of `error-rate`, `p75`, `p99`, `requests`.
- `direction` (string): One of `above`, `below`.
- `window_minutes` (integer, required): One of `1`, `5`, `10`, `30`.
- `routes` (array of string): At most 10 items.

Example:

```sh
curl -X POST "https://api.theorbits.app/v1/teams/my-team/projects/my-app/alerts/preview" \
  -H "Authorization: Bearer $ORBITS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "metric": "error-rate",
    "window_minutes": 1
  }'
```

Response `200`:

```json
{
  "median_requests": 1,
  "minimum_requests": 1,
  "value": null
}
```

Errors:

- `403`: Authenticated but not allowed in this team.
- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
- `422`: Validation failed, or the Idempotency-Key was reused with a different body.
- `503`: A store this endpoint reads is unreachable. Try again shortly.
## Change or switch an alert rule

```http
PATCH /v1/teams/{team}/projects/{project}/alerts/{alert}
```

The rule's switch, and the Edit dialog. Send only what changes. Any change, switching it off or on included, starts the rule again from `ok`. A rule that was firing first resolves, so a receiver sees its incident close: `reason: changed` for an edit, `off` when switched off. Changing `metric` away from `requests` sets `direction` to `above` unless one is sent. 422 as for create.

**Permissions:** Owner, admin or member of the team. Viewers get 403. A non-member gets 404.

Token: a `full` API token.

Path parameters:

- `team`: Team slug or `team_` id.
- `project`: Project slug or `prj_` id.
- `alert`: An `alr_` id from `GET .../alerts`.

Body:

- `name` (string): At most 60 characters.
- `metric` (string): `error-rate`: 5xx responses as a share of requests, in %. `p75`, `p99`: response time in ms. `requests`: requests per minute. One of `error-rate`, `p75`, `p99`, `requests`.
- `direction` (string): One of `above`, `below`.
- `threshold` (number): At most 1000000.
- `window_minutes` (integer): One of `1`, `5`, `10`, `30`.
- `routes` (array of string): At most 10 items.
- `channels` (array of string)
- `on` (boolean)

Example:

```sh
curl -X PATCH "https://api.theorbits.app/v1/teams/my-team/projects/my-app/alerts/alr_01jc8x6e4mq2v7r9y3t5b0zp8w" \
  -H "Authorization: Bearer $ORBITS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-app",
    "metric": "error-rate",
    "direction": "above",
    "threshold": 1,
    "window_minutes": 1,
    "routes": [
      "routes"
    ],
    "channels": [
      "webhook"
    ],
    "on": false
  }'
```

Response `200`:

```json
{
  "id": "alr_7f3c2a1e-0d4b-4c55-9a7e-2b1f6c0d9e11",
  "name": "my-app",
  "metric": "error-rate",
  "direction": "above",
  "threshold": 1,
  "window_minutes": 1,
  "routes": [
    "routes"
  ],
  "channels": [
    "webhook"
  ],
  "on": false,
  "state": "ok",
  "since": "2026-11-10T09:30:00Z",
  "last_value": null,
  "checked_at": "2026-11-10T09:30:00Z",
  "created_at": "2026-11-10T09:30:00Z",
  "updated_at": "2026-11-10T09:30:00Z"
}
```

Errors:

- `403`: Authenticated but not allowed in this team.
- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
- `422`: Validation failed, or the Idempotency-Key was reused with a different body.
## Delete an alert rule

```http
DELETE /v1/teams/{team}/projects/{project}/alerts/{alert}
```

Deletes the rule and its history. A rule that was firing sends `alert.resolved` with `reason: deleted` first.

**Permissions:** Owner, admin or member of the team. Viewers get 403. A non-member gets 404.

Token: a `full` API token.

Path parameters:

- `team`: Team slug or `team_` id.
- `project`: Project slug or `prj_` id.
- `alert`: An `alr_` id from `GET .../alerts`.

Example:

```sh
curl -X DELETE "https://api.theorbits.app/v1/teams/my-team/projects/my-app/alerts/alr_01jc8x6e4mq2v7r9y3t5b0zp8w" \
  -H "Authorization: Bearer $ORBITS_TOKEN"
```

Response `204`: Deleted.

Errors:

- `403`: Authenticated but not allowed in this team.
- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
## When a rule fired and resolved

```http
GET /v1/teams/{team}/projects/{project}/alerts/{alert}/events
```

A rule's history, newest first, kept 90 days, with how each notification went (`deliveries`: one per channel, `pending` while it is still being tried, up to 5 times over about 30 minutes).

**Permissions:** Any team member. A non-member gets 404.

Token: any API token (`read` or `full`).

Path parameters:

- `team`: Team slug or `team_` id.
- `project`: Project slug or `prj_` id.
- `alert`

Query parameters:

- `limit` (integer): From 1 to 100. Defaults to `20`.
- `cursor` (string)

Example:

```sh
curl "https://api.theorbits.app/v1/teams/my-team/projects/my-app/alerts/alr_01jc8x6e4mq2v7r9y3t5b0zp8w/events" \
  -H "Authorization: Bearer $ORBITS_TOKEN"
```

Response `200`:

```json
{
  "items": [
    {
      "id": "id",
      "kind": "fired",
      "reason": "recovered",
      "value": null,
      "at": "2026-11-10T09:30:00Z",
      "deliveries": [
        {
          "channel": "webhook",
          "status": "pending",
          "error": null,
          "at": "2026-11-10T09:30:00Z"
        }
      ]
    }
  ],
  "next_cursor": null
}
```

Errors:

- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
- `422`: Validation failed, or the Idempotency-Key was reused with a different body.
## The team's alert webhook

```http
GET /v1/teams/{team}/alert-channels
```

The webhook every rule with the `webhook` channel sends to, one per team, or null. The secret is never shown again after it is made; `secret_last4` identifies it.

**Permissions:** Owner or admin of the team. Members and viewers get 403 (the list's `webhook_configured` tells them whether one is set). A non-member gets 404.

Token: any API token (`read` or `full`).

Path parameters:

- `team`: Team slug or `team_` id.

Example:

```sh
curl "https://api.theorbits.app/v1/teams/my-team/alert-channels" \
  -H "Authorization: Bearer $ORBITS_TOKEN"
```

Response `200`:

```json
{
  "webhook": {
    "url": "https://my-app.theorbits.app",
    "secret_last4": "secret-last4",
    "updated_at": "2026-11-10T09:30:00Z"
  }
}
```

Errors:

- `403`: Authenticated but not allowed in this team.
- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
## Set the team's alert webhook

```http
PUT /v1/teams/{team}/alert-channels/webhook
```

Sets the URL (https only). The first time, or with `rotate_secret`, a new secret is made and returned in `secret`, this once; the old one stops working at once. Otherwise `secret` is null and the secret is kept.

Every request Orbits sends is a JSON `POST` with `X-Signature-256: sha256=<hex>` (HMAC-SHA256 of the raw body with the secret), `X-Delivery-Id` (the same on every retry of one notification) and `X-Orbits-Event` (`alert.fired`, `alert.resolved` or `alert.test`). The body is an AlertWebhookPayload. A 2xx answer is delivered; anything else, or no answer in 10 seconds, is tried again. Redirects aren't followed, and addresses that aren't on the public internet are refused. The webhook-receiver template verifies these as they are.

**Permissions:** Owner or admin of the team. Members and viewers get 403. A non-member gets 404.

Token: a `full` API token.

Path parameters:

- `team`: Team slug or `team_` id.

Body:

- `url` (string, required): An https URL without a user name or password. At most 2000 characters.
- `rotate_secret` (boolean): Defaults to `false`.

Example:

```sh
curl -X PUT "https://api.theorbits.app/v1/teams/my-team/alert-channels/webhook" \
  -H "Authorization: Bearer $ORBITS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://my-app.theorbits.app"
  }'
```

Response `200`:

```json
{
  "webhook": {
    "url": "https://my-app.theorbits.app",
    "secret_last4": "secret-last4",
    "updated_at": "2026-11-10T09:30:00Z"
  },
  "secret": null
}
```

Errors:

- `403`: Authenticated but not allowed in this team.
- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
- `422`: Validation failed, or the Idempotency-Key was reused with a different body.
## Remove the team's alert webhook

```http
DELETE /v1/teams/{team}/alert-channels/webhook
```

Notifications still waiting for the webhook fail with "The team has no webhook".

**Permissions:** Owner or admin of the team. Members and viewers get 403. A non-member gets 404.

Token: a `full` API token.

Path parameters:

- `team`: Team slug or `team_` id.

Example:

```sh
curl -X DELETE "https://api.theorbits.app/v1/teams/my-team/alert-channels/webhook" \
  -H "Authorization: Bearer $ORBITS_TOKEN"
```

Response `204`: Removed.

Errors:

- `403`: Authenticated but not allowed in this team.
- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
## Send a test event to the webhook

```http
POST /v1/teams/{team}/alert-channels/webhook/test
```

Sends a signed `alert.test` now and says how it went: `delivered` for a 2xx answer, otherwise the receiver's `status` (null when nothing answered) and an `error` to show. 404 when the team has no webhook.

**Permissions:** Owner or admin of the team. Members and viewers get 403. A non-member gets 404.

Token: a `full` API token. Send an `Idempotency-Key` header.

Path parameters:

- `team`: Team slug or `team_` id.

Example:

```sh
curl -X POST "https://api.theorbits.app/v1/teams/my-team/alert-channels/webhook/test" \
  -H "Authorization: Bearer $ORBITS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"
```

Response `200`:

```json
{
  "delivered": false,
  "status": null,
  "error": null
}
```

Errors:

- `403`: Authenticated but not allowed in this team.
- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
