Alert Rules API

Alert rules define the connection between monitors and notification channels. Each rule specifies which trigger conditions (e.g., DOWN, SSL_EXPIRING) should send alerts through a given channel. You can scope rules to individual monitors or apply them organization-wide.

Alert Rule Object

{
  "id": "arl_abc123def456",
  "monitorId": "cly1abc2d0001abcdef012345",
  "channelId": "ach_abc123def456",
  "trigger": "DOWN",
  "consecutiveFailures": 3,
  "cooldownMinutes": 5,
  "enabled": true,
  "createdAt": "2025-01-15T08:30:00.000Z",
  "channel": {
    "id": "ach_abc123def456",
    "name": "Engineering Alerts",
    "type": "SLACK"
  },
  "monitor": {
    "id": "cly1abc2d0001abcdef012345",
    "name": "Production API"
  }
}

Field	Type	Description
`id`	`string`	Unique alert rule identifier
`monitorId`	`string\|null`	Monitor this rule applies to (`null` = all monitors in the organization)
`channelId`	`string`	Alert channel to notify when the rule triggers
`trigger`	`string`	Trigger type: `DOWN`, `UP`, `DEGRADED`, `SSL_EXPIRING`, `DOMAIN_EXPIRING`, `HEARTBEAT_MISSED`
`consecutiveFailures`	`number`	Number of consecutive failures before alerting (default `1`)
`cooldownMinutes`	`number`	Minutes to wait between repeat alerts for the same condition (default `5`)
`enabled`	`boolean`	Whether the rule is active
`createdAt`	`string`	ISO 8601 creation timestamp
`channel`	`object`	Summary of the associated alert channel: `{id, name, type}`
`monitor`	`object\|null`	Summary of the associated monitor: `{id, name}` — `null` when the rule applies to all monitors

tip

Set monitorId to null to create an organization-wide rule that fires for every monitor. This is useful for catch-all alerting channels like a shared Slack channel.

List Alert Rules

GET /v1/alert-rules

Returns a paginated list of alert rules for your organization. Supports filtering by monitor, channel, trigger type, and enabled status.

Query Parameters

Parameter	Type	Default	Description
`limit`	`number`	`50`	Number of rules to return (max 200)
`offset`	`number`	`0`	Number of rules to skip for pagination
`monitorId`	`string`	--	Filter by monitor ID
`channelId`	`string`	--	Filter by alert channel ID
`trigger`	`string`	--	Filter by trigger type: `DOWN`, `UP`, `DEGRADED`, `SSL_EXPIRING`, `DOMAIN_EXPIRING`, `HEARTBEAT_MISSED`
`enabled`	`boolean`	--	Filter by enabled status (`true` or `false`)

Example Request

curl "https://api.sentro.dev/v1/alert-rules?limit=10&trigger=DOWN" \
  -H "Authorization: Bearer sentro_sk_live_your_key_here"

Response `200 OK`

{
  "data": [
    {
      "id": "arl_abc123def456",
      "monitorId": "cly1abc2d0001abcdef012345",
      "channelId": "ach_abc123def456",
      "trigger": "DOWN",
      "consecutiveFailures": 3,
      "cooldownMinutes": 5,
      "enabled": true,
      "createdAt": "2025-01-15T08:30:00.000Z",
      "channel": {
        "id": "ach_abc123def456",
        "name": "Engineering Alerts",
        "type": "SLACK"
      },
      "monitor": {
        "id": "cly1abc2d0001abcdef012345",
        "name": "Production API"
      }
    },
    {
      "id": "arl_ghi789jkl012",
      "monitorId": null,
      "channelId": "ach_ghi789jkl012",
      "trigger": "DOWN",
      "consecutiveFailures": 1,
      "cooldownMinutes": 10,
      "enabled": true,
      "createdAt": "2025-01-10T12:00:00.000Z",
      "channel": {
        "id": "ach_ghi789jkl012",
        "name": "On-Call Email",
        "type": "EMAIL"
      },
      "monitor": null
    },
    {
      "id": "arl_mno345pqr678",
      "monitorId": "cly9xyz8w0002abcdef098765",
      "channelId": "ach_mno345pqr678",
      "trigger": "SSL_EXPIRING",
      "consecutiveFailures": 1,
      "cooldownMinutes": 1440,
      "enabled": false,
      "createdAt": "2025-01-05T09:15:00.000Z",
      "channel": {
        "id": "ach_mno345pqr678",
        "name": "Custom Webhook",
        "type": "WEBHOOK"
      },
      "monitor": {
        "id": "cly9xyz8w0002abcdef098765",
        "name": "Staging Frontend"
      }
    }
  ],
  "meta": {
    "total": 3
  }
}

GET/v1/alert-rules?limit=50&offset=0

Query Parameters

limit — Number of rules to return (max 200)

offset — Number of rules to skip

monitorId — Filter by monitor ID

channelId — Filter by alert channel ID

trigger — DOWN, UP, DEGRADED, SSL_EXPIRING, DOMAIN_EXPIRING, HEARTBEAT_MISSED

enabled — Filter by enabled status (true or false)

Click ⚙ to configure your API key, then hit Send.

Get Alert Rule

GET /v1/alert-rules/:id

Returns a single alert rule with its associated channel and monitor information.

Path Parameters

Parameter	Type	Description
`id`	`string`	The alert rule ID

Example Request

curl https://api.sentro.dev/v1/alert-rules/arl_abc123def456 \
  -H "Authorization: Bearer sentro_sk_live_your_key_here"

Response `200 OK`

{
  "data": {
    "id": "arl_abc123def456",
    "monitorId": "cly1abc2d0001abcdef012345",
    "channelId": "ach_abc123def456",
    "trigger": "DOWN",
    "consecutiveFailures": 3,
    "cooldownMinutes": 5,
    "enabled": true,
    "createdAt": "2025-01-15T08:30:00.000Z",
    "channel": {
      "id": "ach_abc123def456",
      "name": "Engineering Alerts",
      "type": "SLACK"
    },
    "monitor": {
      "id": "cly1abc2d0001abcdef012345",
      "name": "Production API"
    }
  }
}

Error

{
  "error": {
    "code": "NOT_FOUND",
    "message": "AlertRule with id 'arl_invalid' not found"
  }
}

GET/v1/alert-rules/:id

Path Parameters

:id

Click ⚙ to configure your API key, then hit Send.

Create Alert Rule

POST /v1/alert-rules

Creates a new alert rule linking a monitor (or all monitors) to a notification channel. Requires a READ_WRITE API key.

Request Body

Field	Type	Required	Description
`channelId`	`string`	Yes	Alert channel to notify
`trigger`	`string`	Yes	`DOWN`, `UP`, `DEGRADED`, `SSL_EXPIRING`, `DOMAIN_EXPIRING`, or `HEARTBEAT_MISSED`
`monitorId`	`string\|null`	No	Monitor to scope the rule to (`null` or omitted = all monitors)
`consecutiveFailures`	`number`	No	Failures before alerting (default: `1`, range: 1-10)
`cooldownMinutes`	`number`	No	Minutes between repeat alerts (default: `5`, range: 1-1440)
`enabled`	`boolean`	No	Whether the rule is active (default: `true`)

Example Request

curl -X POST https://api.sentro.dev/v1/alert-rules \
  -H "Authorization: Bearer sentro_sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "channelId": "ach_abc123def456",
    "trigger": "DOWN",
    "monitorId": "cly1abc2d0001abcdef012345",
    "consecutiveFailures": 3,
    "cooldownMinutes": 5
  }'

Response `201 Created`

{
  "data": {
    "id": "arl_new123abc456",
    "monitorId": "cly1abc2d0001abcdef012345",
    "channelId": "ach_abc123def456",
    "trigger": "DOWN",
    "consecutiveFailures": 3,
    "cooldownMinutes": 5,
    "enabled": true,
    "createdAt": "2025-01-15T10:00:00.000Z",
    "channel": {
      "id": "ach_abc123def456",
      "name": "Engineering Alerts",
      "type": "SLACK"
    },
    "monitor": {
      "id": "cly1abc2d0001abcdef012345",
      "name": "Production API"
    }
  }
}

Validation Error

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid alert rule data",
    "details": {
      "channelId": ["Required"],
      "trigger": ["Invalid trigger type"]
    }
  }
}

note

The channelId must reference an existing alert channel within your organization. If the specified channel does not exist, you will receive a NOT_FOUND error.

POST/v1/alert-rules

Request Body

Click ⚙ to configure your API key, then hit Send.

Update Alert Rule

PATCH /v1/alert-rules/:id

Updates an existing alert rule. Only the fields you include in the request body will be updated. Requires a READ_WRITE API key.

Path Parameters

Parameter	Type	Description
`id`	`string`	The alert rule ID

Request Body

All fields are optional. Include only the fields you want to change.

Field	Type	Description
`monitorId`	`string\|null`	Update the monitor scope (`null` = all monitors)
`channelId`	`string`	Update the notification channel
`trigger`	`string`	Update the trigger type
`consecutiveFailures`	`number`	Update failures threshold (range: 1-10)
`cooldownMinutes`	`number`	Update cooldown period (range: 1-1440)
`enabled`	`boolean`	Enable or disable the rule

Example Request

curl -X PATCH https://api.sentro.dev/v1/alert-rules/arl_abc123def456 \
  -H "Authorization: Bearer sentro_sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "consecutiveFailures": 5,
    "cooldownMinutes": 15,
    "enabled": false
  }'

Response `200 OK`

{
  "data": {
    "id": "arl_abc123def456",
    "monitorId": "cly1abc2d0001abcdef012345",
    "channelId": "ach_abc123def456",
    "trigger": "DOWN",
    "consecutiveFailures": 5,
    "cooldownMinutes": 15,
    "enabled": false,
    "createdAt": "2025-01-15T08:30:00.000Z",
    "channel": {
      "id": "ach_abc123def456",
      "name": "Engineering Alerts",
      "type": "SLACK"
    },
    "monitor": {
      "id": "cly1abc2d0001abcdef012345",
      "name": "Production API"
    }
  }
}

PATCH/v1/alert-rules/:id

Path Parameters

:id

Request Body

Click ⚙ to configure your API key, then hit Send.

Delete Alert Rule

DELETE /v1/alert-rules/:id

Permanently deletes an alert rule. The associated channel and monitor are not affected. Requires a READ_WRITE API key.

Path Parameters

Parameter	Type	Description
`id`	`string`	The alert rule ID

Example Request

curl -X DELETE https://api.sentro.dev/v1/alert-rules/arl_abc123def456 \
  -H "Authorization: Bearer sentro_sk_live_your_key_here"

Response `200 OK`

{
  "data": {
    "id": "arl_abc123def456",
    "deleted": true
  }
}

Error

{
  "error": {
    "code": "NOT_FOUND",
    "message": "AlertRule with id 'arl_invalid' not found"
  }
}

DELETE/v1/alert-rules/:id

Path Parameters

:id

Click ⚙ to configure your API key, then hit Send.

Trigger Types

Alert rules support six trigger types that cover different failure scenarios:

Trigger	Description
`DOWN`	Monitor endpoint is unreachable or returning an unexpected status code
`UP`	Monitor endpoint has recovered after being down
`DEGRADED`	Response time exceeds the degraded threshold configured on the monitor
`SSL_EXPIRING`	SSL certificate is expiring within the configured alert window (days)
`DOMAIN_EXPIRING`	Domain registration is expiring soon
`HEARTBEAT_MISSED`	A heartbeat monitor has not received a ping within its expected interval

tip

For comprehensive alerting, create paired rules for DOWN and UP triggers on the same channel. This ensures your team is notified both when an issue occurs and when it resolves.

Alert Rule Object​

List Alert Rules​

Query Parameters​

Example Request​

Response 200 OK​

Get Alert Rule​

Path Parameters​

Example Request​

Response 200 OK​

Error​

Create Alert Rule​

Request Body​

Example Request​

Response 201 Created​

Validation Error​

Update Alert Rule​

Path Parameters​

Request Body​

Example Request​

Response 200 OK​

Delete Alert Rule​

Path Parameters​

Example Request​

Response 200 OK​

Error​

Trigger Types​

Alert Rule Object

List Alert Rules

Query Parameters

Example Request

Response `200 OK`

Get Alert Rule

Path Parameters

Example Request

Response `200 OK`

Error

Create Alert Rule

Request Body

Example Request

Response `201 Created`

Validation Error

Update Alert Rule

Path Parameters

Request Body

Example Request

Response `200 OK`

Delete Alert Rule

Path Parameters

Example Request

Response `200 OK`

Error

Trigger Types