> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hookstream.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Alert Rules

Define threshold-based alerts for error rates, latency, volume, DLQ, and circuit breakers.

Alert rules define conditions that trigger notifications. hookstream evaluates alert rules every 5 minutes via a Cron trigger. When a rule's threshold is exceeded, notifications are sent to configured channels. Rules auto-resolve after 30 minutes if the condition clears.

Five alert types are supported: `failure_rate`, `latency`, `volume_drop`, `dlq`, and `issue_opened`.

## List Alert Rules

GET `/v1/alert-rules`

List all alert rules.

**Authentication:** API key or session cookie.

```json 200 OK
{
  "alert_rules": [
    {
      "id": "ar_b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3",
      "name": "High Error Rate",
      "rule_type": "failure_rate",
      "rule_config": { "threshold": 0.1 },
      "channel_ids": ["nc_a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2"],
      "cooldown_minutes": 60,
      "enabled": true,
      "last_triggered_at": null,
      "created_at": "2026-02-28T10:00:00Z"
    }
  ]
}
```

## Create Alert Rule

POST `/v1/alert-rules`

Create a new alert rule.

**Authentication:** API key or session cookie.

### Body Parameters

Display name for the rule.

Alert type: `failure_rate`, `latency`, `volume_drop`, `dlq`, or `issue_opened`.

Type-specific configuration:
  - `failure_rate`: `{ threshold }` (decimal, e.g., `0.1` for 10%)
  - `latency`: `{ threshold_ms, percentile_target }`
  - `volume_drop`: `{ threshold }`
  - `dlq`: `{ threshold }`

Array of notification channel IDs to send alerts to.

Minimum minutes between alert triggers.

```bash cURL
curl -X POST https://hookstream.io/v1/alert-rules \
  -H "X-API-Key: $HOOKSTREAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "High Error Rate",
    "rule_type": "failure_rate",
    "rule_config": { "threshold": 0.1 },
    "channel_ids": ["nc_a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2"],
    "cooldown_minutes": 60
  }'
```

```json 201 Created
{
  "alert_rule": {
    "id": "ar_b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3",
    "name": "High Error Rate",
    "rule_type": "failure_rate",
    "rule_config": { "threshold": 0.1 },
    "channel_ids": ["nc_a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2"],
    "cooldown_minutes": 60,
    "enabled": true,
    "created_at": "2026-03-01T12:00:00Z"
  }
}
```

## Retrieve Alert Rule

GET `/v1/alert-rules/:id`

Get a single alert rule with its trigger history.

**Authentication:** API key or session cookie.

```json 200 OK
{
  "alert_rule": {
    "id": "ar_b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3",
    "name": "High Error Rate",
    "rule_type": "failure_rate",
    "rule_config": { "threshold": 0.1 },
    "channel_ids": ["nc_a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2"],
    "cooldown_minutes": 60,
    "enabled": true,
    "last_triggered_at": "2026-03-01T10:05:00Z",
    "created_at": "2026-02-28T10:00:00Z"
  },
  "history": [
    {
      "id": "ah_1a2b3c",
      "alert_rule_id": "ar_b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3",
      "triggered_at": "2026-03-01T10:05:00Z",
      "message": "Failure rate 15% exceeds 10% threshold",
      "created_at": "2026-03-01T10:05:00Z"
    }
  ]
}
```

## Update Alert Rule

PATCH `/v1/alert-rules/:id`

Update an alert rule.

**Authentication:** API key or session cookie.

```bash cURL
curl -X PATCH https://hookstream.io/v1/alert-rules/ar_b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3 \
  -H "X-API-Key: $HOOKSTREAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"rule_config": {"threshold": 0.05}, "cooldown_minutes": 30}'
```

```json 200 OK
{
  "alert_rule": {
    "id": "ar_b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3",
    "name": "High Error Rate",
    "rule_type": "failure_rate",
    "rule_config": { "threshold": 0.05 },
    "cooldown_minutes": 30,
    "updated_at": "2026-03-01T15:00:00Z"
  }
}
```

## Delete Alert Rule

DELETE `/v1/alert-rules/:id`

Delete an alert rule.

**Authentication:** API key or session cookie.

```json 200 OK
{ "deleted": true }
```