Alerts

Create and manage threshold-based alert rules for log projects. Alerts trigger notifications when a specified number of log entries at a given level occur within a time window.

Base URL: https://app.krafter.dev/api/v1

List Alerts

Retrieve all alerts for a project.

GET /logs/projects/:id/alerts

Required scope: logs:read

Example Request

curl https://app.krafter.dev/api/v1/logs/projects/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d/alerts \
  -H "Authorization: Bearer kr_live_abc123def456"

Example Response

{
  "data": [
    {
      "id": "f1e2d3c4-b5a6-9788-7c6d-5e4f3a2b1c0d",
      "project_id": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "name": "High Error Rate",
      "level": "error",
      "threshold": 10,
      "window_minutes": 5,
      "channels": ["email", "webhook"],
      "notify_email": "ops@example.com",
      "notify_webhook": "https://example.com/webhooks/alerts",
      "enabled": true,
      "last_triggered_at": "2025-01-15T14:30:00Z",
      "inserted_at": "2025-01-10T08:00:00Z",
      "updated_at": "2025-01-10T08:00:00Z"
    },
    {
      "id": "a2b3c4d5-e6f7-8901-2345-6789abcdef01",
      "project_id": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "name": "Fatal Alert",
      "level": "fatal",
      "threshold": 1,
      "window_minutes": 1,
      "channels": ["email"],
      "notify_email": "oncall@example.com",
      "notify_webhook": null,
      "enabled": true,
      "last_triggered_at": null,
      "inserted_at": "2025-01-12T09:00:00Z",
      "updated_at": "2025-01-12T09:00:00Z"
    }
  ]
}

---

Create Alert

Create a new alert rule for a project.

POST /logs/projects/:id/alerts

Required scope: logs:write

Request Body

Field	Type	Required	Description
name	string	Yes	Display name for the alert.
level	string	Yes	Log level to monitor: debug, info, warn, error, or fatal.
threshold	integer	Yes	Number of matching log entries to trigger the alert.
window_minutes	integer	Yes	Time window in minutes to count entries within.
channels	array	Yes	Notification channels: ["email"], ["webhook"], or ["email", "webhook"].
notify_email	string	No	Email address for email notifications. Required if channels includes "email".
notify_webhook	string	No	Webhook URL for HTTP notifications. Required if channels includes "webhook".
enabled	boolean	No	Whether the alert is active. Defaults to true.

Example Request

curl -X POST https://app.krafter.dev/api/v1/logs/projects/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d/alerts \
  -H "Authorization: Bearer kr_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "High Error Rate",
    "level": "error",
    "threshold": 10,
    "window_minutes": 5,
    "channels": ["email", "webhook"],
    "notify_email": "ops@example.com",
    "notify_webhook": "https://example.com/webhooks/alerts"
  }'

Example Response

// 201 Created
{
  "data": {
    "id": "f1e2d3c4-b5a6-9788-7c6d-5e4f3a2b1c0d",
    "project_id": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
    "name": "High Error Rate",
    "level": "error",
    "threshold": 10,
    "window_minutes": 5,
    "channels": ["email", "webhook"],
    "notify_email": "ops@example.com",
    "notify_webhook": "https://example.com/webhooks/alerts",
    "enabled": true,
    "last_triggered_at": null,
    "inserted_at": "2025-01-15T10:00:00Z",
    "updated_at": "2025-01-15T10:00:00Z"
  }
}

---

Update Alert

Update an existing alert. Only provided fields are changed.

PUT /logs/alerts/:id

Required scope: logs:write

Request Body

Field	Type	Required	Description
name	string	No	Display name for the alert.
level	string	No	Log level to monitor.
threshold	integer	No	Number of matching entries to trigger.
window_minutes	integer	No	Time window in minutes.
channels	array	No	Notification channels.
notify_email	string	No	Email address for notifications.
notify_webhook	string	No	Webhook URL for notifications.
enabled	boolean	No	Whether the alert is active.

Example Request

curl -X PUT https://app.krafter.dev/api/v1/logs/alerts/f1e2d3c4-b5a6-9788-7c6d-5e4f3a2b1c0d \
  -H "Authorization: Bearer kr_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "threshold": 25,
    "window_minutes": 10,
    "enabled": false
  }'

Example Response

{
  "data": {
    "id": "f1e2d3c4-b5a6-9788-7c6d-5e4f3a2b1c0d",
    "project_id": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
    "name": "High Error Rate",
    "level": "error",
    "threshold": 25,
    "window_minutes": 10,
    "channels": ["email", "webhook"],
    "notify_email": "ops@example.com",
    "notify_webhook": "https://example.com/webhooks/alerts",
    "enabled": false,
    "last_triggered_at": "2025-01-15T14:30:00Z",
    "inserted_at": "2025-01-10T08:00:00Z",
    "updated_at": "2025-01-16T11:00:00Z"
  }
}

---

Delete Alert

Permanently delete an alert rule.

DELETE /logs/alerts/:id

Required scope: logs:write

Example Request

curl -X DELETE https://app.krafter.dev/api/v1/logs/alerts/f1e2d3c4-b5a6-9788-7c6d-5e4f3a2b1c0d \
  -H "Authorization: Bearer kr_live_abc123def456"

Example Response

// 204 No Content