Policies and Alerts API

These APIs cover both monitor definition and runtime alert handling.

Policy routes

POST /v1.0/policies
GET /v1.0/policies
GET /v1.0/policies/:policyID
PUT /v1.0/policies/:policyID

Policy object


{
  "policy_id": "58d3d98b-4dad-498c-a074-1e2f7f6bc5b0",
  "event_id": "34c57199-4c6d-4eb8-ae17-c386e17c7b95",
  "title": "Task duration too high",
  "description": "Alert when average task latency rises above 2s",
  "channel": "ops",
  "period": "hour",
  "aggregate": "average",
  "condition": "gt",
  "threshold": 2000,
  "severity": "warning",
  "enabled": true
}

Allowed enum values:

period: minute, hour, day
aggregate: sum, count, average, min, max, p95_est, p99_est
condition: gt, lt, eq, gte, lte
severity: info, warning, error, critical

Create and update policies

Raw API


curl -X POST "https://api.chirpier.co/v1.0/policies" \
  -H "Authorization: Bearer $CHIRPIER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "event_id": "'$EVENT_ID'",
    "title": "Task duration too high",
    "channel": "ops",
    "period": "hour",
    "aggregate": "average",
    "condition": "gt",
    "threshold": 2000,
    "severity": "warning",
    "enabled": true
  }'
 
curl -X PUT "https://api.chirpier.co/v1.0/policies/$POLICY_ID" \
  -H "Authorization: Bearer $CHIRPIER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Task duration still too high"}'

JavaScript


const policy = await client.createPolicy({
  event_id: EVENT_ID,
  title: "Task duration too high",
  channel: "ops",
  period: "hour",
  aggregate: "average",
  condition: "gt",
  threshold: 2000,
  severity: "warning",
  enabled: true,
});
 
const updated = await client.updatePolicy(policy.policy_id, {
  title: "Task duration still too high",
});

Python


policy = client.create_policy(
    {
        "event_id": EVENT_ID,
        "title": "Task duration too high",
        "channel": "ops",
        "period": "hour",
        "aggregate": "average",
        "condition": "gt",
        "threshold": 2000,
        "severity": "warning",
        "enabled": True,
    }
)
 
updated = client.update_policy(policy["policy_id"], {"title": "Task duration still too high"})

Go


policy, err := client.CreatePolicy(ctx, chirpier.Policy{
    EventID:   EVENT_ID,
    Title:     "Task duration too high",
    Channel:   "ops",
    Period:    "hour",
    Aggregate: "average",
    Condition: "gt",
    Threshold: 2000,
    Severity:  "warning",
    Enabled:   true,
})
 
updated, err := client.UpdatePolicy(ctx, policy.PolicyID, chirpier.Policy{Title: "Task duration still too high"})

GET /v1.0/policies returns all policies for the current user.

GET /v1.0/policies/:policyID and PUT /v1.0/policies/:policyID require policyID to be a UUID.

Alert routes

GET /v1.0/alerts
GET /v1.0/alerts/:alertID
GET /v1.0/alerts/:alertID/deliveries?kind=alert|test|all&limit=&offset=
POST /v1.0/alerts/:alertID/acknowledge
POST /v1.0/alerts/:alertID/resolve
POST /v1.0/alerts/:alertID/archive

Alert object

Alerts are runtime policy results. A response typically includes:

policy identity: alert_id, policy_id, event_id
stream context: agent, event, title, channel where channel is the policy routing namespace
monitor rule: period, aggregate, condition, threshold, severity
evaluation result: value, count, min, max
lifecycle state: status, triggered_at, acknowledged_at, resolved_at, alerted_at

Example:


{
  "alert_id": "414d5d9c-b8c0-4e8b-bf3a-0d4e3e616604",
  "policy_id": "58d3d98b-4dad-498c-a074-1e2f7f6bc5b0",
  "event_id": "34c57199-4c6d-4eb8-ae17-c386e17c7b95",
  "event": "task.duration_ms",
  "title": "Task duration too high",
  "channel": "ops",
  "period": "hour",
  "aggregate": "average",
  "condition": "gt",
  "threshold": 2000,
  "severity": "warning",
  "status": "triggered",
  "value": 2410,
  "count": 18,
  "min": 810,
  "max": 4100,
  "triggered_at": "2026-04-08T18:30:00Z"
}

Read alerts

GET /v1.0/alerts supports an optional status filter:

triggered
acknowledged
resolved
archived

Read alert deliveries

Query parameters:

kind: optional. One of alert, test, or all.
limit: optional integer. Defaults to 100.
offset: optional integer. Defaults to 0.

Example delivery attempt:


{
  "attempt_id": "72aa8ea6-aabd-4f75-b7f6-df31d7a0f41f",
  "alert_id": "414d5d9c-b8c0-4e8b-bf3a-0d4e3e616604",
  "destination_id": "5e9d6fd1-727a-46f6-a377-6c8ef407efdc",
  "channel": "slack",
  "target": "https://hooks.slack.com/services/...",
  "status": "delivered",
  "response_status": 200,
  "created_at": "2026-04-08T18:30:03Z"
}

Raw API


curl -G "https://api.chirpier.co/v1.0/alerts/$ALERT_ID/deliveries" \
  -H "Authorization: Bearer $CHIRPIER_TOKEN" \
  --data-urlencode "kind=alert" \
  --data-urlencode "limit=20" \
  --data-urlencode "offset=0"

JavaScript


const deliveries = await client.getAlertDeliveries(ALERT_ID, {
  kind: "alert",
  limit: 20,
  offset: 0,
});

Python


deliveries = client.get_alert_deliveries(ALERT_ID, kind="alert", limit=20, offset=0)

Go


deliveries, err := client.GetAlertDeliveries(ctx, ALERT_ID, 20, 0, "alert")

Lifecycle actions

Use the three action routes with an empty body:

POST /v1.0/alerts/:alertID/acknowledge
POST /v1.0/alerts/:alertID/resolve
POST /v1.0/alerts/:alertID/archive

Responses:

200 OK with the updated alert
404 Not Found if the alert does not exist
409 Conflict if the requested transition is invalid