Alerts API

Built-in alerts, acknowledgement and silences, and the webhook channels that receive them. This page lists 12 operations.

Set variables in the API overview. Download OpenAPI.

Operations

Details

GET /api/v1/alerts

Firing alerts (most severe and oldest first) with acknowledgement and silence, the silences in force, counts by severity and whether the evaluator runs. Needs cluster.view.

Operation ID: alerts

Needs: cluster.view.

Example request. Replace sample names, IDs and body values with resources and settings from your installation.

curl --fail-with-body -sS -X GET "$APELORA_URL/api/v1/alerts" \
  -H "Authorization: Bearer $APELORA_TOKEN" \
  -H "Accept: application/json"

TypeScript:

const result = await client.request("alerts", {});

Response 200 — Done; the response holds the result..

Content-Type: application/json.

Example response from a test installation; your IDs, names and times differ.

{
  "alerts": [
    {
      "id": 2,
      "rule": "job-failures",
      "title": "Jobs are failing",
      "subject": "instance.restart",
      "severity": "warning",
      "state": "firing",
      "summary": "2 instance.restart jobs failed in the last 15 minutes; the latest: instance default/mock-web-01 exists but was not created by Apelora; it is left untouched",
      "value": 2,
      "threshold": 1,
      "comparison": "at-least",
      "unit": "failed jobs in 15 minutes",
      "startedAt": "2026-10-28T23:26:56.824151Z",
      "firedAt": "2026-10-28T23:26:56.824151Z",
      "lastSeenAt": "2026-10-28T23:27:07.196025Z",
      "resolvedAt": null,
      "clearingSince": null,
      "acknowledged": null,
      "silencedBy": null,
      "runbook": "alerts.md#jobs-are-failing"
    }
  ],
  "silences": [],
  "counts": {
    "critical": 0,
    "warning": 1,
    "info": 0,
    "needsAttention": 1
  },
  "evaluator": {
    "lastPassAt": "2026-10-28T23:27:07.196025Z",
    "everySecs": 5,
    "worker": "docs-worker",
    "durationSecs": 0.136330958,
    "stale": false,
    "message": "Evaluated every 5 s by docs-worker."
  },
  "actions": {
    "respond": {
      "allowed": true,
      "reason": null
    },
    "configure": {
      "allowed": true,
      "reason": null
    }
  }
}

Errors. The body is {"error": {"code": …, "message": …}}; see error codes for the codes every operation shares.

POST /api/v1/alerts/{id}/acknowledge

Acknowledges a firing alert: who, when and an optional note. It keeps firing until its condition clears; acknowledging tells others someone is on it. Refused (409) when it is not firing (not_firing) or was acknowledged already (already_acknowledged). Needs alert.respond; audited as alert.acknowledge.

Operation ID: acknowledge_alert

Needs: alert.respond; audited as alert.acknowledge.

Request body (JSON):

{
  "note": "Looking into the failed job"
}

Example request. Replace sample names, IDs and body values with resources and settings from your installation.

This request can change state. Check permissions, prerequisites and any required approval before running it.

curl --fail-with-body -sS -X POST "$APELORA_URL/api/v1/alerts/2/acknowledge" \
  -H "Authorization: Bearer $APELORA_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  --data-raw '{"note":"Looking into the failed job"}'

TypeScript:

const result = await client.request("acknowledge_alert", { params: { id: "2" }, body: { note: "Looking into the failed job" } });

Response 200 — Done; the response holds the result..

Content-Type: application/json.

Example response from a test installation; your IDs, names and times differ.

{
  "id": 2,
  "rule": "job-failures",
  "title": "Jobs are failing",
  "subject": "instance.restart",
  "severity": "warning",
  "state": "firing",
  "summary": "2 instance.restart jobs failed in the last 15 minutes; the latest: instance default/mock-web-01 exists but was not created by Apelora; it is left untouched",
  "value": 2,
  "threshold": 1,
  "comparison": "at-least",
  "unit": "failed jobs in 15 minutes",
  "startedAt": "2026-10-28T23:26:56.824151Z",
  "firedAt": "2026-10-28T23:26:56.824151Z",
  "lastSeenAt": "2026-10-28T23:27:07.196025Z",
  "resolvedAt": null,
  "clearingSince": null,
  "acknowledged": {
    "by": "token:docs-verifier",
    "byName": "docs-verifier",
    "at": "2026-10-28T23:27:09.650977Z",
    "note": "Looking into the failed job"
  },
  "silencedBy": null,
  "runbook": "alerts.md#jobs-are-failing"
}

Errors. The body is {"error": {"code": …, "message": …}}; see error codes for the codes every operation shares.

GET /api/v1/alerts/channels

Webhook channels with their delivery state. The full URL only for callers who may configure channels. Needs cluster.view.

Operation ID: alert_channels

Needs: cluster.view.

Example request. Replace sample names, IDs and body values with resources and settings from your installation.

curl --fail-with-body -sS -X GET "$APELORA_URL/api/v1/alerts/channels" \
  -H "Authorization: Bearer $APELORA_TOKEN" \
  -H "Accept: application/json"

TypeScript:

const result = await client.request("alert_channels", {});

Response 200 — Done; the response holds the result..

Content-Type: application/json.

Example response from a test installation; your IDs, names and times differ.

{
  "items": [
    {
      "id": "a948c7f6-7876-49a1-a5b2-70258f9a63b4",
      "name": "On-call webhook",
      "kind": "webhook",
      "host": "hooks.example.invalid",
      "url": "https://hooks.example.invalid/apelora",
      "secretRef": "APELORA_ALERT_SECRET_ONCALL",
      "enabled": true,
      "minSeverity": "critical",
      "delivery": {
        "pending": 1,
        "failing": 0,
        "lastError": null,
        "lastDeliveredAt": null
      },
      "createdAt": "2026-10-28T23:26:51.119809Z",
      "createdBy": "token:docs-verifier",
      "updatedAt": "2026-10-28T23:26:51.145328Z"
    }
  ],
  "secretPrefix": "APELORA_ALERT_SECRET_",
  "actions": {
    "respond": {
      "allowed": true,
      "reason": null
    },
    "configure": {
      "allowed": true,
      "reason": null
    }
  }
}

Errors. The body is {"error": {"code": …, "message": …}}; see error codes for the codes every operation shares.

POST /api/v1/alerts/channels

Adds a webhook channel. HTTPS only; the signing secret is named, never sent. Needs alert.configure; audited as alert.channel.create (host only, not the URL).

Operation ID: create_alert_channel

Needs: alert.configure; audited as alert.channel.create (host only, not the URL).

Request body (JSON):

{
  "name": "On-call webhook",
  "url": "https://hooks.example.invalid/apelora",
  "secretRef": "APELORA_ALERT_SECRET_ONCALL",
  "minSeverity": "warning",
  "enabled": true
}

Example request. Replace sample names, IDs and body values with resources and settings from your installation.

This request can change state. Check permissions, prerequisites and any required approval before running it.

curl --fail-with-body -sS -X POST "$APELORA_URL/api/v1/alerts/channels" \
  -H "Authorization: Bearer $APELORA_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  --data-raw '{"name":"On-call webhook","url":"https://hooks.example.invalid/apelora","secretRef":"APELORA_ALERT_SECRET_ONCALL","minSeverity":"warning","enabled":true}'

TypeScript:

const result = await client.request("create_alert_channel", { body /* the request body above */ });

Response 201 — Created; the response describes what was created..

Content-Type: application/json.

Example response from a test installation; your IDs, names and times differ.

{
  "id": "a948c7f6-7876-49a1-a5b2-70258f9a63b4",
  "name": "On-call webhook",
  "kind": "webhook",
  "host": "hooks.example.invalid",
  "url": "https://hooks.example.invalid/apelora",
  "secretRef": "APELORA_ALERT_SECRET_ONCALL",
  "enabled": true,
  "minSeverity": "warning",
  "delivery": {
    "pending": 0,
    "failing": 0,
    "lastError": null,
    "lastDeliveredAt": null
  },
  "createdAt": "2026-10-28T23:26:51.119809Z",
  "createdBy": "token:docs-verifier",
  "updatedAt": "2026-10-28T23:26:51.119809Z"
}

Errors. The body is {"error": {"code": …, "message": …}}; see error codes for the codes every operation shares.

PUT /api/v1/alerts/channels/{id}

Changes a webhook channel. Needs alert.configure; audited as alert.channel.update.

Operation ID: update_alert_channel

Needs: alert.configure; audited as alert.channel.update.

Request body (JSON):

{
  "name": "On-call webhook",
  "url": "https://hooks.example.invalid/apelora",
  "secretRef": "APELORA_ALERT_SECRET_ONCALL",
  "minSeverity": "critical",
  "enabled": true
}

Example request. Replace sample names, IDs and body values with resources and settings from your installation.

This request can change state. Check permissions, prerequisites and any required approval before running it.

curl --fail-with-body -sS -X PUT "$APELORA_URL/api/v1/alerts/channels/a948c7f6-7876-49a1-a5b2-70258f9a63b4" \
  -H "Authorization: Bearer $APELORA_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  --data-raw '{"name":"On-call webhook","url":"https://hooks.example.invalid/apelora","secretRef":"APELORA_ALERT_SECRET_ONCALL","minSeverity":"critical","enabled":true}'

TypeScript:

const result = await client.request("update_alert_channel", { params: { id: "a948c7f6-7876-49a1-a5b2-70258f9a63b4" }, body /* the request body above */ });

Response 200 — Done; the response holds the result..

Content-Type: application/json.

Example response from a test installation; your IDs, names and times differ.

{
  "id": "a948c7f6-7876-49a1-a5b2-70258f9a63b4",
  "name": "On-call webhook",
  "kind": "webhook",
  "host": "hooks.example.invalid",
  "url": "https://hooks.example.invalid/apelora",
  "secretRef": "APELORA_ALERT_SECRET_ONCALL",
  "enabled": true,
  "minSeverity": "critical",
  "delivery": {
    "pending": 0,
    "failing": 0,
    "lastError": null,
    "lastDeliveredAt": null
  },
  "createdAt": "2026-10-28T23:26:51.119809Z",
  "createdBy": "token:docs-verifier",
  "updatedAt": "2026-10-28T23:26:51.145328Z"
}

Errors. The body is {"error": {"code": …, "message": …}}; see error codes for the codes every operation shares.

DELETE /api/v1/alerts/channels/{id}

Deletes a webhook channel; messages still waiting for it are dropped by the relay. Needs alert.configure; audited as alert.channel.delete.

Operation ID: delete_alert_channel

Needs: alert.configure; audited as alert.channel.delete.

Example request. Replace sample names, IDs and body values with resources and settings from your installation.

This request can change state. Check permissions, prerequisites and any required approval before running it.

curl --fail-with-body -sS -X DELETE "$APELORA_URL/api/v1/alerts/channels/a948c7f6-7876-49a1-a5b2-70258f9a63b4" \
  -H "Authorization: Bearer $APELORA_TOKEN"

TypeScript:

await client.request("delete_alert_channel", { params: { id: "a948c7f6-7876-49a1-a5b2-70258f9a63b4" } });

Response 204 — Done; nothing is returned., with no body.

Errors. The body is {"error": {"code": …, "message": …}}; see error codes for the codes every operation shares.

POST /api/v1/alerts/channels/{id}/test

Queues a test notification for one channel through the same outbox path as real alerts; the channel's delivery state shows the outcome within seconds. Needs alert.configure; audited as alert.channel.test in the same transaction as the message.

Operation ID: test_alert_channel

Needs: alert.configure; audited as alert.channel.test in the same transaction as the message.

Example request. Replace sample names, IDs and body values with resources and settings from your installation.

This request can change state. Check permissions, prerequisites and any required approval before running it.

curl --fail-with-body -sS -X POST "$APELORA_URL/api/v1/alerts/channels/a948c7f6-7876-49a1-a5b2-70258f9a63b4/test" \
  -H "Authorization: Bearer $APELORA_TOKEN" \
  -H "Accept: application/json"

TypeScript:

const result = await client.request("test_alert_channel", { params: { id: "a948c7f6-7876-49a1-a5b2-70258f9a63b4" } });

Response 202 — Accepted: the work is queued; the response says how to follow it..

Content-Type: application/json.

Example response from a test installation; your IDs, names and times differ.

{
  "messageId": 101
}

Errors. The body is {"error": {"code": …, "message": …}}; see error codes for the codes every operation shares.

GET /api/v1/alerts/history

Resolved alerts, newest first, paged with after and next. Kept 90 days. Needs cluster.view.

Operation ID: alert_history

Needs: cluster.view.

Example request. Replace sample names, IDs and body values with resources and settings from your installation.

curl --fail-with-body -sS -X GET "$APELORA_URL/api/v1/alerts/history" \
  -H "Authorization: Bearer $APELORA_TOKEN" \
  -H "Accept: application/json"

With options (after, limit):

curl --fail-with-body -sS -X GET "$APELORA_URL/api/v1/alerts/history?after=41&limit=1" \
  -H "Authorization: Bearer $APELORA_TOKEN" \
  -H "Accept: application/json"

Next page: repeat the request with after set to the response's next. The last page has no next.

TypeScript:

const result = await client.request("alert_history", { query: { after: "41", limit: 1 } });

Response 200 — Done; the response holds the result..

Content-Type: application/json.

Example response from a test installation; your IDs, names and times differ.

{
  "items": [],
  "next": null
}

Errors. The body is {"error": {"code": …, "message": …}}; see error codes for the codes every operation shares.

GET /api/v1/alerts/rules

The built-in rules with their parameters in force, their defaults and what the evaluator's last pass said about each source. Needs cluster.view.

Operation ID: alert_rules

Needs: cluster.view.

Example request. Replace sample names, IDs and body values with resources and settings from your installation.

curl --fail-with-body -sS -X GET "$APELORA_URL/api/v1/alerts/rules" \
  -H "Authorization: Bearer $APELORA_TOKEN" \
  -H "Accept: application/json"

TypeScript:

const result = await client.request("alert_rules", {});

Response 200 — Done; the response holds the result..

Content-Type: application/json.

Example response from a test installation; your IDs, names and times differ. Long lists are cut to their first items.

{
  "items": [
    {
      "id": "job-failures",
      "title": "Jobs are failing",
      "description": "Jobs of one kind that ended failed in the last 15 minutes. A failed job did not reach its goal after its retries.",
      "unit": "failed jobs in 15 minutes",
      "comparison": "at-least",
      "thresholdEditable": true,
      "thresholdMin": 1,
      "thresholdMax": 1000,
      "params": {
        "enabled": true,
        "threshold": 1,
        "forSecs": 0,
        "severity": "warning"
      },
      "defaults": {
        "enabled": true,
        "threshold": 1,
        "forSecs": 0,
        "severity": "warning"
      },
      "source": "Job queue",
      "sourceState": "ok",
      "firing": 1,
      "runbook": "alerts.md#jobs-are-failing",
      "updatedAt": "2026-10-28T23:26:51.236548Z",
      "updatedBy": "token:docs-verifier"
    },
    {
      "id": "job-queue-wait",
      "title": "Jobs are waiting too long",
      "description": "How long the oldest job that could run has waited. Long waits mean no worker is claiming jobs, or workers are busy.",
      "unit": "seconds",
      "comparison": "at-least",
      "thresholdEditable": true,
      "thresholdMin": 10,
      "thresholdMax": 86400,
      "params": {
        "enabled": true,
        "threshold": 300,
        "forSecs": 60,
        "severity": "warning"
      },
      "defaults": {
        "enabled": true,
        "threshold": 300,
        "forSecs": 60,
        "severity": "warning"
      },
      "source": "Job queue",
      "sourceState": "ok",
      "firing": 0,
      "runbook": "alerts.md#jobs-are-waiting-too-long",
      "updatedAt": null,
      "updatedBy": null
    }
  ],
  "actions": {
    "respond": {
      "allowed": true,
      "reason": null
    },
    "configure": {
      "allowed": true,
      "reason": null
    }
  }
}

Errors. The body is {"error": {"code": …, "message": …}}; see error codes for the codes every operation shares.

PUT /api/v1/alerts/rules/{rule}

Changes a rule's parameters (on or off, threshold within the rule's bounds, duration up to a day, severity). Takes effect on the evaluator's next pass. Needs alert.configure; audited as alert.rule.update with the parameters before and after.

Operation ID: update_alert_rule

Needs: alert.configure; audited as alert.rule.update with the parameters before and after.

Request body (JSON):

{
  "enabled": true,
  "threshold": 1,
  "forSecs": 0,
  "severity": "warning"
}

Example request. Replace sample names, IDs and body values with resources and settings from your installation.

This request can change state. Check permissions, prerequisites and any required approval before running it.

curl --fail-with-body -sS -X PUT "$APELORA_URL/api/v1/alerts/rules/job-failures" \
  -H "Authorization: Bearer $APELORA_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  --data-raw '{"enabled":true,"threshold":1,"forSecs":0,"severity":"warning"}'

TypeScript:

const result = await client.request("update_alert_rule", { params: { rule: "job-failures" }, body: { enabled: true, threshold: 1, forSecs: 0, severity: "warning" } });

Response 200 — Done; the response holds the result..

Content-Type: application/json.

Example response from a test installation; your IDs, names and times differ.

{
  "id": "job-failures",
  "title": "Jobs are failing",
  "description": "Jobs of one kind that ended failed in the last 15 minutes. A failed job did not reach its goal after its retries.",
  "unit": "failed jobs in 15 minutes",
  "comparison": "at-least",
  "thresholdEditable": true,
  "thresholdMin": 1,
  "thresholdMax": 1000,
  "params": {
    "enabled": true,
    "threshold": 1,
    "forSecs": 0,
    "severity": "warning"
  },
  "defaults": {
    "enabled": true,
    "threshold": 1,
    "forSecs": 0,
    "severity": "warning"
  },
  "source": "Job queue",
  "sourceState": "unknown",
  "firing": 0,
  "runbook": "alerts.md#jobs-are-failing",
  "updatedAt": "2026-10-28T23:26:51.236548Z",
  "updatedBy": "token:docs-verifier"
}

Errors. The body is {"error": {"code": …, "message": …}}; see error codes for the codes every operation shares.

POST /api/v1/alerts/silences

Silences a rule (every subject, or one) for minutes from now: no notification is sent for its alerts that fire or resolve meanwhile. Evaluation and history go on. Needs alert.respond; audited as alert.silence.create.

Operation ID: create_alert_silence

Needs: alert.respond; audited as alert.silence.create.

Request body (JSON):

{
  "rule": "backup-age",
  "minutes": 120,
  "note": "Backup pool maintenance tonight"
}

Example request. Replace sample names, IDs and body values with resources and settings from your installation.

This request can change state. Check permissions, prerequisites and any required approval before running it.

curl --fail-with-body -sS -X POST "$APELORA_URL/api/v1/alerts/silences" \
  -H "Authorization: Bearer $APELORA_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  --data-raw '{"rule":"backup-age","minutes":120,"note":"Backup pool maintenance tonight"}'

TypeScript:

const result = await client.request("create_alert_silence", { body: { rule: "backup-age", minutes: 120, note: "Backup pool maintenance tonight" } });

Response 201 — Created; the response describes what was created..

Content-Type: application/json.

Example response from a test installation; your IDs, names and times differ.

{
  "id": "ddb79999-ee9f-4c5b-b1cd-6053e160f13c",
  "rule": "backup-age",
  "ruleTitle": "A backup is overdue",
  "subject": null,
  "startsAt": "2026-10-28T23:26:51.29521Z",
  "endsAt": "2026-10-29T01:26:51.29521Z",
  "note": "Backup pool maintenance tonight",
  "createdBy": "token:docs-verifier",
  "createdByName": "docs-verifier"
}

Errors. The body is {"error": {"code": …, "message": …}}; see error codes for the codes every operation shares.

DELETE /api/v1/alerts/silences/{id}

Ends a silence now. Needs alert.respond; audited as alert.silence.end. 404 when it is not in force (ended or run out).

Operation ID: end_alert_silence

Needs: alert.respond; audited as alert.silence.end.

Example request. Replace sample names, IDs and body values with resources and settings from your installation.

This request can change state. Check permissions, prerequisites and any required approval before running it.

curl --fail-with-body -sS -X DELETE "$APELORA_URL/api/v1/alerts/silences/ddb79999-ee9f-4c5b-b1cd-6053e160f13c" \
  -H "Authorization: Bearer $APELORA_TOKEN"

TypeScript:

await client.request("end_alert_silence", { params: { id: "ddb79999-ee9f-4c5b-b1cd-6053e160f13c" } });

Response 204 — Done; nothing is returned., with no body.

Errors. The body is {"error": {"code": …, "message": …}}; see error codes for the codes every operation shares.