Alerts API

Manage security alert rules, view fired alerts, and configure webhook delivery for your project. LogStitch ships with built-in detection rules and supports custom rules on paid plans.

List Rules#

GET/api/v1/alerts/rules

List all alert rules for the project, including built-in detection patterns and any custom rules you have created.

Auth: Master key or Project key

List all rules

curl https://logstitch.io/api/v1/alerts/rules \
  -H "Authorization: Bearer mk_..."

200Success

Response

{
  "rules": [
    {
      "id": "auth_brute_force",
      "type": "builtin",
      "name": "Auth Brute Force",
      "action_pattern": "auth.failed*",
      "threshold": 5,
      "window_seconds": 300,
      "group_by": "actor_id",
      "severity": "high",
      "enabled": true,
      "cooldown_seconds": 3600
    },
    {
      "id": "550e8400-...",
      "type": "custom",
      "name": "Bulk invite spike",
      "action_pattern": "team.member.invited",
      "threshold": 10,
      "window_seconds": 600,
      "group_by": "tenant_id",
      "severity": "medium",
      "enabled": true,
      "cooldown_seconds": 3600,
      "created_at": "2026-01-20T14:00:00.000Z"
    }
  ],
  "request_id": "req_abc123"
}

Create Rule#

POST/api/v1/alerts/rules

Create a custom alert rule. Custom rules require a paid plan.

Auth: Master key only

Paid plan required

Custom alert rules are only available on Pro and Enterprise plans. Free-tier projects can use the built-in rules.

Request body

Name	Type	Required	Description
name	string	Required	A human-readable label for the rule (1-100 chars)
action_pattern	string	Required	Glob pattern to match event actions (e.g. auth.failed, .deleted)
threshold	number	Required	Number of matching events to trigger the alert
window_seconds	number	Required	Sliding window in seconds (60-3600)
group_by	string	Required	Field to group counts by: actor_id or tenant_id
severity	string	Required	Alert severity: low, medium, high, or critical
cooldown_seconds	number	Optional	Minimum seconds between repeated alerts for the same group. Default: 3600
enabled	boolean	Optional	Whether the rule is active. Default: true

Create a custom rule

curl -X POST https://logstitch.io/api/v1/alerts/rules \
  -H "Authorization: Bearer mk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Bulk invite spike",
    "action_pattern": "team.member.invited",
    "threshold": 10,
    "window_seconds": 600,
    "group_by": "tenant_id",
    "severity": "medium"
  }'

201Success

Response

{
  "rule": {
    "id": "550e8400-...",
    "type": "custom",
    "name": "Bulk invite spike",
    "action_pattern": "team.member.invited",
    "threshold": 10,
    "window_seconds": 600,
    "group_by": "tenant_id",
    "severity": "medium",
    "enabled": true,
    "cooldown_seconds": 3600,
    "created_at": "2026-01-20T14:00:00.000Z"
  },
  "request_id": "req_abc123"
}

Update Rule#

PATCH/api/v1/alerts/rules/:id

Update an existing alert rule. For built-in rules, only enabled and cooldown_seconds can be changed.

Auth: Master key only

Request body

Name	Type	Required	Description
name	string	Optional	Updated rule name
action_pattern	string	Optional	Updated action glob pattern (custom rules only)
threshold	number	Optional	Updated threshold (custom rules only)
window_seconds	number	Optional	Updated window in seconds (custom rules only)
group_by	string	Optional	Updated group_by field (custom rules only)
severity	string	Optional	Updated severity (custom rules only)
cooldown_seconds	number	Optional	Updated cooldown in seconds
enabled	boolean	Optional	Enable or disable the rule

Disable a built-in rule

curl -X PATCH https://logstitch.io/api/v1/alerts/rules/auth_brute_force \
  -H "Authorization: Bearer mk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": false
  }'

200Success

Response

{
  "rule": {
    "id": "auth_brute_force",
    "type": "builtin",
    "name": "Auth Brute Force",
    "action_pattern": "auth.failed*",
    "threshold": 5,
    "window_seconds": 300,
    "group_by": "actor_id",
    "severity": "high",
    "enabled": false,
    "cooldown_seconds": 3600
  },
  "request_id": "req_abc123"
}

Delete Rule#

DELETE/api/v1/alerts/rules/:id

Permanently delete a custom alert rule. The rule stops being evaluated immediately. Previously fired alerts are not affected.

Auth: Master key only

Delete a custom rule

curl -X DELETE https://logstitch.io/api/v1/alerts/rules/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer mk_..."

200Success

Response

{
  "deleted": true,
  "request_id": "req_abc123"
}

Built-in rules cannot be deleted

Built-in rules cannot be deleted. Use the PATCH endpoint to disable them by setting enabled to false.

List Fired Alerts#

GET/api/v1/alerts

Retrieve alerts that have been triggered, with filtering and cursor-based pagination.

Auth: Master key or Project key

Query parameters

Name	Type	Required	Description
rule_id	string	Optional	Filter by the rule that triggered the alert
severity	string	Optional	Filter by severity: low, medium, high, critical
status	string	Optional	Filter by status: open, acknowledged, resolved
start_date	string	Optional	ISO 8601 datetime lower bound
end_date	string	Optional	ISO 8601 datetime upper bound
cursor	string	Optional	Pagination cursor from a previous response
limit	number	Optional	Results per page (1-100, default 50)

List open high-severity alerts

curl "https://logstitch.io/api/v1/alerts?status=open&severity=high" \
  -H "Authorization: Bearer pk_..."

200Success

Response

{
  "alerts": [
    {
      "id": "alt_01HX...",
      "rule_id": "auth_brute_force",
      "rule_name": "Auth Brute Force",
      "severity": "high",
      "status": "open",
      "group_key": "user_456",
      "event_count": 7,
      "sample_event_ids": ["evt_01HX...", "evt_01HX..."],
      "fired_at": "2026-01-20T15:30:00.000Z",
      "acknowledged_at": null,
      "resolved_at": null
    }
  ],
  "cursor": "eyJv...",
  "has_more": false,
  "request_id": "req_abc123"
}

Update Alert Status#

PATCH/api/v1/alerts/:id

Transition an alert from open to acknowledged, or from open/acknowledged to resolved.

Auth: Master key or Project key

Request body

Name	Type	Required	Description
status	string	Required	New status: acknowledged or resolved

Acknowledge an alert

curl -X PATCH https://logstitch.io/api/v1/alerts/alt_01HX... \
  -H "Authorization: Bearer pk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "status": "acknowledged"
  }'

200Success

Response

{
  "alert": {
    "id": "alt_01HX...",
    "status": "acknowledged",
    "acknowledged_at": "2026-01-20T16:00:00.000Z"
  },
  "request_id": "req_abc123"
}

List Webhooks#

GET/api/v1/alerts/webhooks

List all webhook endpoints configured for alert delivery.

Auth: Master key only

List webhooks

curl https://logstitch.io/api/v1/alerts/webhooks \
  -H "Authorization: Bearer mk_..."

200Success

Response

{
  "webhooks": [
    {
      "id": "wh_01HX...",
      "url": "https://example.com/hooks/logstitch",
      "enabled": true,
      "secret": "whsec_****...redacted",
      "created_at": "2026-01-20T14:00:00.000Z"
    }
  ],
  "request_id": "req_abc123"
}

Create Webhook#

POST/api/v1/alerts/webhooks

Register a webhook endpoint for alert delivery. When an alert fires, LogStitch sends a signed POST request to the webhook URL.

Auth: Master key only

Paid plan required

Webhook delivery is only available on Pro and Enterprise plans.

Request body

Name	Type	Required	Description
url	string	Required	HTTPS URL to receive webhook POST requests
enabled	boolean	Optional	Whether the webhook is active. Default: true

Create a webhook

curl -X POST https://logstitch.io/api/v1/alerts/webhooks \
  -H "Authorization: Bearer mk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/hooks/logstitch"
  }'

201Success

Response

{
  "webhook": {
    "id": "wh_01HX...",
    "url": "https://example.com/hooks/logstitch",
    "enabled": true,
    "secret": "whsec_abc123...",
    "created_at": "2026-01-20T14:00:00.000Z"
  },
  "request_id": "req_abc123"
}

Save the webhook secret

The secret field is only returned in full on creation. Use it to verify webhook signatures. See the Security Alerts guide for verification details.

Update Webhook#

PATCH/api/v1/alerts/webhooks/:id

Update an existing webhook endpoint.

Auth: Master key only

Request body

Name	Type	Required	Description
url	string	Optional	Updated HTTPS URL
enabled	boolean	Optional	Enable or disable the webhook

Disable a webhook

curl -X PATCH https://logstitch.io/api/v1/alerts/webhooks/wh_01HX... \
  -H "Authorization: Bearer mk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": false
  }'

200Success

Response

{
  "webhook": {
    "id": "wh_01HX...",
    "url": "https://example.com/hooks/logstitch",
    "enabled": false,
    "secret": "whsec_****...redacted",
    "created_at": "2026-01-20T14:00:00.000Z"
  },
  "request_id": "req_abc123"
}

Delete Webhook#

DELETE/api/v1/alerts/webhooks/:id

Permanently delete a webhook endpoint. It will no longer receive alert deliveries.

Auth: Master key only

Delete a webhook

curl -X DELETE https://logstitch.io/api/v1/alerts/webhooks/wh_01HX... \
  -H "Authorization: Bearer mk_..."

200Success

Response

{
  "deleted": true,
  "request_id": "req_abc123"
}