API reference · ObserveAlerts
Alerts
Alert rules on a project's metrics, their history, and the team's alert channels.
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.
The alert object
Fields
idstringrequirednamestringrequiredAt most 60 characters.
metricstringrequirederror-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.directionstringrequiredbelowonly forrequests.One of
above,below.thresholdnumberrequiredwindow_minutesintegerrequiredOne of
1,5,10,30.routesarray of stringrequiredRoutes as Observability names them; a trailing
*matches a prefix. Empty for all routes.channelsarray of stringrequiredonbooleanrequiredstatestringrequiredOne of
ok,firing.sincestringrequiredWhen it last fired or resolved, or was created or changed.
last_valuenumber or nullrequiredThe value at the last check; null before one, or with too little traffic.
checked_atstring or nullrequiredcreated_atstringrequiredupdated_atstringrequired
A project's alert rules and their state
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.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….
Path parameters
teamstringrequiredTeam slug or
team_id.projectstringrequiredProject slug or
prj_id.
Response 200
The rules.itemsarray of AlertrequiredShow 15 child fieldsHide child fields
idstringrequirednamestringrequiredAt most 60 characters.
metricstringrequirederror-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.directionstringrequiredbelowonly forrequests.One of
above,below.thresholdnumberrequiredwindow_minutesintegerrequiredOne of
1,5,10,30.routesarray of stringrequiredRoutes as Observability names them; a trailing
*matches a prefix. Empty for all routes.channelsarray of stringrequiredonbooleanrequiredstatestringrequiredOne of
ok,firing.sincestringrequiredWhen it last fired or resolved, or was created or changed.
last_valuenumber or nullrequiredThe value at the last check; null before one, or with too little traffic.
checked_atstring or nullrequiredcreated_atstringrequiredupdated_atstringrequired
webhook_configuredbooleanrequiredWhether the team has a webhook, so
webhookcan be chosen.
Errors
- 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
Every code is explained in Errors.
curl "https://api.theorbits.app/v1/teams/my-team/projects/my-app/alerts" \
-H "Authorization: Bearer $ORBITS_TOKEN"{
"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
}Create an alert rule
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.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….Idempotency-KeystringrequiredA new value, such as a UUID, for each change. Resend with the same value and body to retry safely.
From 8 to 128 characters.
Path parameters
teamstringrequiredTeam slug or
team_id.projectstringrequiredProject slug or
prj_id.
Body
application/jsonnamestringrequiredAt most 60 characters.
metricstringrequirederror-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.directionstringOne of
above,below. Defaults toabove.thresholdnumberrequiredAt most 1000000.
window_minutesintegerrequiredOne of
1,5,10,30.routesarray of stringAt most 10 items.
channelsarray of stringrequiredonbooleanDefaults to
true.
Response 201
Created.idstringrequirednamestringrequiredAt most 60 characters.
metricstringrequirederror-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.directionstringrequiredbelowonly forrequests.One of
above,below.thresholdnumberrequiredwindow_minutesintegerrequiredOne of
1,5,10,30.routesarray of stringrequiredRoutes as Observability names them; a trailing
*matches a prefix. Empty for all routes.channelsarray of stringrequiredonbooleanrequiredstatestringrequiredOne of
ok,firing.sincestringrequiredWhen it last fired or resolved, or was created or changed.
last_valuenumber or nullrequiredThe value at the last check; null before one, or with too little traffic.
checked_atstring or nullrequiredcreated_atstringrequiredupdated_atstringrequired
Errors
- 403Authenticated but not allowed in this team.
- 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
- 422Validation failed, or the Idempotency-Key was reused with a different body.
Every code is explained in Errors.
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"
]
}'{
"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"
}How much traffic a draft rule would see
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.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….Idempotency-KeystringrequiredA new value, such as a UUID, for each change. Resend with the same value and body to retry safely.
From 8 to 128 characters.
Path parameters
teamstringrequiredTeam slug or
team_id.projectstringrequiredProject slug or
prj_id.
Body
application/jsonmetricstringrequirederror-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.directionstringOne of
above,below.window_minutesintegerrequiredOne of
1,5,10,30.routesarray of stringAt most 10 items.
Response 200
The traffic and the value now.median_requestsnumberrequiredMedian requests per window over the last 24 hours.
minimum_requestsintegerrequiredWhat a window needs before the rule acts: 20, or 0 for
requests.valuenumber or nullrequiredThe value over the last window, or null with too little traffic.
Errors
- 403Authenticated but not allowed in this team.
- 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
- 422Validation failed, or the Idempotency-Key was reused with a different body.
- 503A store this endpoint reads is unreachable. Try again shortly.
Every code is explained in Errors.
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
}'{
"median_requests": 1,
"minimum_requests": 1,
"value": null
}Change or switch an alert rule
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.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….
Path parameters
teamstringrequiredTeam slug or
team_id.projectstringrequiredProject slug or
prj_id.alertstringrequiredAn
alr_id fromGET .../alerts.
Body
application/jsonnamestringAt most 60 characters.
metricstringerror-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.directionstringOne of
above,below.thresholdnumberAt most 1000000.
window_minutesintegerOne of
1,5,10,30.routesarray of stringAt most 10 items.
channelsarray of stringonboolean
Response 200
The rule as saved.idstringrequirednamestringrequiredAt most 60 characters.
metricstringrequirederror-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.directionstringrequiredbelowonly forrequests.One of
above,below.thresholdnumberrequiredwindow_minutesintegerrequiredOne of
1,5,10,30.routesarray of stringrequiredRoutes as Observability names them; a trailing
*matches a prefix. Empty for all routes.channelsarray of stringrequiredonbooleanrequiredstatestringrequiredOne of
ok,firing.sincestringrequiredWhen it last fired or resolved, or was created or changed.
last_valuenumber or nullrequiredThe value at the last check; null before one, or with too little traffic.
checked_atstring or nullrequiredcreated_atstringrequiredupdated_atstringrequired
Errors
- 403Authenticated but not allowed in this team.
- 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
- 422Validation failed, or the Idempotency-Key was reused with a different body.
Every code is explained in Errors.
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
}'{
"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"
}Delete an alert rule
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.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….
Path parameters
teamstringrequiredTeam slug or
team_id.projectstringrequiredProject slug or
prj_id.alertstringrequiredAn
alr_id fromGET .../alerts.
Response 204
Deleted. No body.
Errors
- 403Authenticated but not allowed in this team.
- 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
Every code is explained in Errors.
curl -X DELETE "https://api.theorbits.app/v1/teams/my-team/projects/my-app/alerts/alr_01jc8x6e4mq2v7r9y3t5b0zp8w" \
-H "Authorization: Bearer $ORBITS_TOKEN"When a rule fired and resolved
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.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….
Path parameters
teamstringrequiredTeam slug or
team_id.projectstringrequiredProject slug or
prj_id.alertstringrequired
Query parameters
limitintegerFrom 1 to 100. Defaults to
20.cursorstring
Response 200
One page of events.itemsarray of AlertEventrequiredShow 6 child fieldsHide child fields
idstringrequiredkindstringrequiredOne of
fired,resolved.reasonstring or nullrequiredWhy it resolved: its value came back, its traffic went too quiet to measure (
valueis null), or it was changed, switched off or deleted while firing.One of
recovered,quiet,changed,off,deleted.valuenumber or nullrequiredatstringrequireddeliveriesarray of AlertDeliveryrequiredShow 4 child fieldsHide child fields
channelstringrequiredwebhook: the team's webhook.email: the team's owners, admins and members.One of
webhook,email.statusstringrequiredOne of
pending,delivered,failed.errorstring or nullrequiredWhy the last try failed, e.g. "The webhook answered 500".
atstring or nullrequiredWhen it was delivered or given up on.
next_cursorstring or nullrequired
Errors
- 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
- 422Validation failed, or the Idempotency-Key was reused with a different body.
Every code is explained in Errors.
curl "https://api.theorbits.app/v1/teams/my-team/projects/my-app/alerts/alr_01jc8x6e4mq2v7r9y3t5b0zp8w/events" \
-H "Authorization: Bearer $ORBITS_TOKEN"{
"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
}The team's alert webhook
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.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….
Path parameters
teamstringrequiredTeam slug or
team_id.
Response 200
The webhook, or null.webhookAlertWebhook or nullrequiredShow 3 child fieldsHide child fields
urlstringrequiredsecret_last4stringrequiredupdated_atstringrequired
Errors
- 403Authenticated but not allowed in this team.
- 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
Every code is explained in Errors.
curl "https://api.theorbits.app/v1/teams/my-team/alert-channels" \
-H "Authorization: Bearer $ORBITS_TOKEN"{
"webhook": {
"url": "https://my-app.theorbits.app",
"secret_last4": "secret-last4",
"updated_at": "2026-11-10T09:30:00Z"
}
}Set the team's alert 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.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….
Path parameters
teamstringrequiredTeam slug or
team_id.
Body
application/jsonurlstringrequiredAn https URL without a user name or password.
At most 2000 characters.
rotate_secretbooleanDefaults to
false.
Response 200
Saved.webhookAlertWebhookrequiredShow 3 child fieldsHide child fields
urlstringrequiredsecret_last4stringrequiredupdated_atstringrequired
secretstring or nullrequiredThe new secret (64 hex characters), shown this once; null when it was kept.
Errors
- 403Authenticated but not allowed in this team.
- 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
- 422Validation failed, or the Idempotency-Key was reused with a different body.
Every code is explained in Errors.
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"
}'{
"webhook": {
"url": "https://my-app.theorbits.app",
"secret_last4": "secret-last4",
"updated_at": "2026-11-10T09:30:00Z"
},
"secret": null
}Remove the team's alert 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.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….
Path parameters
teamstringrequiredTeam slug or
team_id.
Response 204
Removed. No body.
Errors
- 403Authenticated but not allowed in this team.
- 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
Every code is explained in Errors.
curl -X DELETE "https://api.theorbits.app/v1/teams/my-team/alert-channels/webhook" \
-H "Authorization: Bearer $ORBITS_TOKEN"Send a test event to the webhook
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.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….Idempotency-KeystringrequiredA new value, such as a UUID, for each change. Resend with the same value and body to retry safely.
From 8 to 128 characters.
Path parameters
teamstringrequiredTeam slug or
team_id.
Response 200
How the test went.deliveredbooleanrequiredstatusinteger or nullrequirederrorstring or nullrequired
Errors
- 403Authenticated but not allowed in this team.
- 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
Every code is explained in Errors.
curl -X POST "https://api.theorbits.app/v1/teams/my-team/alert-channels/webhook/test" \
-H "Authorization: Bearer $ORBITS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)"{
"delivered": false,
"status": null,
"error": null
}