Alert rules

The operations about alert rules. Each one is a POST with a JSON object as its body: Making a request has the rules they share.

Create alert rule #

POST /api/v1/alerts.create · Write

Adds an alert rule to one site: a goal or a funnel, a metric, a comparison with a threshold, a trailing window and a webhook address. Rules are checked once an hour. When the value crosses the threshold a delivery with type alert.triggered is queued, again after cooldownHours while it stays breached, and alert.recovered when it is fine again. Deliveries are sent every five minutes, signed as Standard Webhooks describes. The answer carries webhookSecret, the signing secret, this once. The webhook address must be https on the default port with a public host name: no bare IP address, no user name or password, no localhost or internal name, and not an address of this service (400 invalid webhookUrl). Redirects are not followed. The endpoint starts unverified: call alerts.test to send a test, and the first 2xx answer verifies it. An unverified rule is switched off after its first failed delivery and is not retried. The metric must fit the subject (400 invalid metric), a rate threshold is at most 1 (400 invalid threshold), the subject must be a goal or funnel of this site (400 invalid subjectId). A site holds at most 25 rules and a workspace 50 (409 limit_reached). Needs a token with the Write permission.

Input #

Output #

Example #

curl -s -X POST https://clearsaga.com/api/v1/alerts.create \
  -H "Authorization: Bearer $CLEARSAGA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"siteId":"site_abc123def456","name":"Signup rate dropped","subjectType":"goal","subjectId":"GOAL_ID","metric":"goal_rate","comparison":"below","threshold":0.02,"window":"7d","webhookUrl":"https://example.com/hooks/alerts"}'

clearsaga alerts create --input '{"siteId":"site_abc123def456","name":"Signup rate dropped","subjectType":"goal","subjectId":"GOAL_ID","metric":"goal_rate","comparison":"below","threshold":0.02,"window":"7d","webhookUrl":"https://example.com/hooks/alerts"}'

Not offered as an MCP tool: Makes our server call an address the caller chooses. Left to people and their own programs: use the API, the CLI or the dashboard.

Run clearsaga help alerts create for one flag per field.

Delete alert rule #

POST /api/v1/alerts.delete · Write

Removes an alert rule from one site for good, together with its delivery log (what alerts.deliveries lists) and its signing secret. This cannot be undone. To pause a rule and keep its log, call alerts.update with enabled false instead. The id comes from alerts.list. The rule is checked no more. Deliveries that were still waiting are removed with it and none is queued after that; only one that is being sent at that very moment can still arrive. The goal or funnel the rule watched is not touched, and neither is any report. An id the site does not have is not an error: the answer says deleted false and nothing was changed, so sending the same call twice is safe. Needs a token with the Write permission.

Input #

Output #

Example #

curl -s -X POST https://clearsaga.com/api/v1/alerts.delete \
  -H "Authorization: Bearer $CLEARSAGA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"siteId":"site_abc123def456","id":"ALERT_ID"}'

clearsaga alerts delete --input '{"siteId":"site_abc123def456","id":"ALERT_ID"}'

Not offered as an MCP tool: Alert rules are created, changed and removed outside MCP, by people and their own programs: use the API, the CLI or the dashboard.

Run clearsaga help alerts delete for one flag per field.

List alert deliveries #

POST /api/v1/alerts.deliveries · Read

The webhook deliveries of one alert rule, newest first: what was sent (triggered, recovered or a test), the value at that moment, and how the sending went (status, attempts, the last HTTP status, when it is tried next). A failed delivery to a verified endpoint is retried with growing gaps for about a day and a half; an endpoint that never answered is not retried. The newest 200 deliveries of a rule are kept. The rows never carry the webhook address or the body that was sent. An unknown id answers 404. Keeps working while the workspace is locked.

Needs a token with the Read permission. Keeps answering while the dashboards of the workspace are locked.

Input #

Output #

Example #

curl -s -X POST https://clearsaga.com/api/v1/alerts.deliveries \
  -H "Authorization: Bearer $CLEARSAGA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"siteId":"site_abc123def456","id":"ALERT_ID"}'

clearsaga alerts deliveries --input '{"siteId":"site_abc123def456","id":"ALERT_ID"}'

Tool: alerts_deliveries
Arguments: {"siteId":"site_abc123def456","id":"ALERT_ID"}

Run clearsaga help alerts deliveries for one flag per field.

List alert rules #

POST /api/v1/alerts.list · Read

Lists the alert rules of one site, oldest first. A rule watches one conversion goal or one funnel over the last 24 hours or 7 days and calls a webhook when its number crosses a threshold. Each row says what the last hourly check found (state, lastValue, lastSample), when the rule last fired, whether its endpoint is verified and, when the system switched it off, why. The full webhook address is only in the answer for a token with the Write permission; a read token gets webhookUrl null and the host name in webhookHost. The signing secret is never listed. Keeps working while the workspace is locked.

Needs a token with the Read permission. Keeps answering while the dashboards of the workspace are locked.

Input #

Output #

Example #

curl -s -X POST https://clearsaga.com/api/v1/alerts.list \
  -H "Authorization: Bearer $CLEARSAGA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"siteId":"site_abc123def456"}'

clearsaga alerts list --input '{"siteId":"site_abc123def456"}'

Tool: alerts_list
Arguments: {"siteId":"site_abc123def456"}

Run clearsaga help alerts list for one flag per field.

Send test delivery #

POST /api/v1/alerts.test · Write

Queues one test delivery (type alert.test) for an alert rule, with the numbers of its last check, and answers the delivery row with status pending. Nothing is sent during this call: deliveries are sent every five minutes, so read alerts.deliveries afterwards to see whether it arrived. A 2xx answer to a test verifies the endpoint, and switches a rule back on that was off only because its endpoint had never answered. A failed test to an unverified endpoint switches the rule off. A test is never retried. One test per rule can wait at a time (409 limit_reached test), and a rule takes at most 10 tests an hour (429 rate_limited). An unknown id answers 404. Needs a token with the Write permission.

Input #

Output #

Example #

curl -s -X POST https://clearsaga.com/api/v1/alerts.test \
  -H "Authorization: Bearer $CLEARSAGA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"siteId":"site_abc123def456","id":"ALERT_ID"}'

clearsaga alerts test --input '{"siteId":"site_abc123def456","id":"ALERT_ID"}'

Not offered as an MCP tool: Makes our server call an address the caller chooses. Left to people and their own programs: use the API, the CLI or the dashboard.

Run clearsaga help alerts test for one flag per field.

Update alert rule #

POST /api/v1/alerts.update · Write

Changes one alert rule. Send id and only the fields to change; a field left out keeps its value. Changing what is measured (subjectType, subjectId, metric, comparison, threshold, window, minSample) starts the rule over: its state goes back to fine and the next hourly check judges the new condition. A new webhookUrl makes the endpoint unverified again until a delivery to it gets a 2xx answer. regenerateSecret true issues a new signing secret, which is in the answer as webhookSecret this once; the old one stops working at once. The webhook address must be https on the default port with a public host name: no bare IP address, no user name or password, no localhost or internal name, and not an address of this service (400 invalid webhookUrl). Redirects are not followed. The same value rules as alerts.create apply. An unknown id answers 404. Needs a token with the Write permission.

Input #

Output #

Example #

curl -s -X POST https://clearsaga.com/api/v1/alerts.update \
  -H "Authorization: Bearer $CLEARSAGA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"siteId":"site_abc123def456","id":"ALERT_ID"}'

clearsaga alerts update --input '{"siteId":"site_abc123def456","id":"ALERT_ID"}'

Not offered as an MCP tool: Makes our server call an address the caller chooses. Left to people and their own programs: use the API, the CLI or the dashboard.

Run clearsaga help alerts update for one flag per field.