We're looking for beta testers.

API reference

Alerts

Configure Starlink alerts, profiles, and delivery settings.

Configure Outage alerts (single threshold), profiles, and daily digest settings for an organization. Members can read settings; owners and admins can change them with a write scope.

The dashboard uses one Outage after duration per monitor or profile. The API still returns edgeOffline mirrored from longOutage for compatibility; webhooks may still emit edge_offline when silence is due to the Edge device or network.

← API overview


Authentication

Authorization: Bearer <user_or_service_token>

Use a user token or a service token for the same organization. Monitor tokens cannot access these routes.


Endpoint map

MethodPathWho can change
GET/v1/organizations/:org_id/alertsMember (read)
PUT/v1/organizations/:org_id/alertsOwner / admin (write)
POST/v1/organizations/:org_id/alerts/threshold-noticeOwner / admin: dismiss auto-raise notice
GET/v1/organizations/:org_id/alerts/monitorsMember
PUT/v1/organizations/:org_id/alerts/monitorsOwner / admin: batch monitor updates
GET/v1/organizations/:org_id/alerts/profilesMember
POST/v1/organizations/:org_id/alerts/profilesOwner / admin
GET/v1/organizations/:org_id/alerts/profiles/:profile_idMember
PUT/v1/organizations/:org_id/alerts/profiles/:profile_idOwner / admin
DELETE/v1/organizations/:org_id/alerts/profiles/:profile_idOwner / admin
POST/v1/organizations/:org_id/alerts/profiles/:profile_id/webhook-secretOwner / admin: rotate profile webhook secret
POST/v1/organizations/:org_id/alerts/webhook-secretOwner / admin: rotate org webhook secret
POST/v1/organizations/:org_id/alerts/testOwner / admin: send test notification
GET/v1/organizations/:org_id/alerts/deliveriesMember: recent delivery log
GET/v1/monitors/:monitor_id/alert-settingsMember
PUT/v1/monitors/:monitor_id/alert-settingsOwner / admin
DELETE/v1/monitors/:monitor_id/alert-settingsOwner / admin: clear overrides

Get organization alert settings

GET /v1/organizations/:org_id/alerts
Authorization: Bearer <token>

Response 200 (excerpt)

{
  "data": {
    "longOutage": { "enabled": true, "thresholdSec": 300 },
    "edgeOffline": { "enabled": true, "thresholdSec": 300 },
    "digest": { "enabled": false, "maxDurationSec": 15 },
    "email": { "enabled": true, "recipients": ["ops@example.com"] },
    "webhook": { "enabled": false, "url": null, "secret": null }
  },
  "profiles": { "profiles": [] },
  "limits": {
    "ingestIntervalSec": 60,
    "minOutageThresholdSec": 90,
    "minEdgeOfflineSec": 90
  },
  "canManage": true,
  "thresholdsRaisedNotice": null
}
FieldDescription
limits.minOutageThresholdSecMinimum Outage after (ceil(1.5× org data interval); per-monitor rows include their own floor)
limits.minEdgeOfflineSecDeprecated mirror of minOutageThresholdSec (#371)
canManagetrue for owners and admins
webhook.secretMasked signing secret if configured
webhookHeadersCustom headers configured for the org webhook ({ name, set: true } only; values are never returned)

Update organization alert settings

PUT /v1/organizations/:org_id/alerts
Authorization: Bearer <token>
Content-Type: application/json

{
  "longOutage": { "enabled": true, "thresholdSec": 300 },
  "edgeOffline": { "enabled": true, "thresholdSec": 300 },
  "digest": { "enabled": true, "maxDurationSec": 15 },
  "email": { "enabled": true, "recipients": ["ops@example.com"] },
  "webhook": { "enabled": true, "url": "https://hooks.example.com/orbimon" }
}

Thresholds below limits return 400 invalid_request.

Include webhookHeaders in the same request to replace the org destination’s custom headers (owners and admins only). Send the full list on each update. Each item is either { "name": "Header-Name", "value": "…" } to set a value, or { "name": "Header-Name", "keep": true } to keep an existing value without resending it. Names not in the list are removed. Responses include only name and set flags, for example { "name": "Authorization", "set": true }.

Custom headers

Alert webhooks support up to 5 optional custom HTTP headers per destination (organization default or a profile’s own webhook URL). Profiles that use organization channels inherit the organization’s headers.

  • Header names must be 1 to 64 characters and use RFC 7230 token characters. Names are unique case-insensitively.
  • Header values are 1 to 1024 printable ASCII characters (no CR, LF, or NUL).
  • Values are write-only: after you save, the API only reports which names are set. You cannot read values back.
  • These names are reserved and cannot be set: Content-Type, Content-Length, Host, Connection, Transfer-Encoding, User-Agent, and any name starting with X-Orbimon-.
  • Orbimon always sends X-Orbimon-Timestamp, X-Orbimon-Signature, X-Orbimon-Event, and X-Orbimon-Delivery. Your custom headers cannot override them.

Example (organization settings):

PUT /v1/organizations/:org_id/alerts
Authorization: Bearer <token>
Content-Type: application/json

{
  "webhook": { "enabled": true, "url": "https://hooks.example.com/orbimon" },
  "webhookHeaders": [
    { "name": "Authorization", "value": "Bearer <your-token>" }
  ]
}

Use the same webhookHeaders field on PUT /v1/organizations/:org_id/alerts/profiles/:profile_id for a profile that defines its own webhook URL.


Per-monitor settings

GET /v1/monitors/:monitor_id/alert-settings
Authorization: Bearer <token>

Returns effective settings for one monitor (organization defaults, profile, and overrides).

PUT /v1/monitors/:monitor_id/alert-settings
Authorization: Bearer <token>
Content-Type: application/json

{
  "profileId": "prof_…",
  "longOutage": { "enabled": true, "thresholdSec": 120 },
  "timezone": "Europe/Madrid"
}

Test notification

POST /v1/organizations/:org_id/alerts/test
Authorization: Bearer <token>
Content-Type: application/json

{ "channel": "email" }

channel may be email or webhook.


Recent deliveries

GET /v1/organizations/:org_id/alerts/deliveries?limit=50
Authorization: Bearer <token>

Returns delivery attempts newest first. The daily digest also writes one skipped row per monitor when it does not send, for example digest off, digest on, no email recipients, quiet day, nothing to report, or query failed. These rows have attempt: 0, skipped: true, and a readable error reason, so a silent digest leaves an audit trail.


See also