Alerts API

Alerts notify you when important events occur in your project — a job exhausts all retries, an item is dead-lettered, or a worker stops sending heartbeats. Each alert setting maps one event type to one notification destination.

Base URL: https://api.zeridion.com/flare/v1

All endpoints require Bearer token authentication and are subject to rate limits.

---

Alert types

alert_type	Triggered when
job_failed	A job reaches failed state (exhausted all attempts).
dead_letter	A job is moved to dead_letter state.
worker_offline	A worker stops sending heartbeats and is considered offline.

Channels

channel	Supported	Notes
email	Yes	destination must be a valid email address (≤ 320 characters).
slack	Reserved	Not yet available.
webhook	Reserved	Not yet available.

---

GET /flare/v1/alerts

List all alert settings for the authenticated project, newest first.

Request

GET /flare/v1/alerts
Authorization: Bearer <api_key>

Response

200 OK

{
  "data": [
    {
      "id": "alert_01HYX3K7M8N9P2Q4R5S6T7U8V9",
      "alert_type": "job_failed",
      "channel": "email",
      "destination": "ops@example.com",
      "enabled": true,
      "created_at": "2026-03-18T15:30:00Z"
    }
  ]
}

Field	Type	Description
data	array	All alert settings for this project.
id	string	Unique alert setting ID.
alert_type	string	The event type that triggers this alert.
channel	string	The delivery channel.
destination	string	The notification target (email address, etc.).
enabled	boolean	false means the alert is paused.
created_at	string (ISO 8601)	When this alert setting was created.

---

POST /flare/v1/alerts

Create a new alert setting.

Request

POST /flare/v1/alerts
Authorization: Bearer <api_key>
Content-Type: application/json

Body

Field	Type	Required	Description
alert_type	string	Yes	One of: job_failed, dead_letter, worker_offline.
channel	string	Yes	email (the only supported channel today).
destination	string	Yes	Valid email address. Max 320 characters.

Example

{
  "alert_type": "job_failed",
  "channel": "email",
  "destination": "ops@example.com"
}

Response

201 Created

Returns a Location header pointing to the new resource and the created alert setting object:

{
  "id": "alert_01HYX3K7M8N9P2Q4R5S6T7U8V9",
  "alert_type": "job_failed",
  "channel": "email",
  "destination": "ops@example.com",
  "enabled": true,
  "created_at": "2026-03-18T15:30:00Z"
}

New alert settings are enabled by default.

Errors

Status	Code	Condition
400	invalid_request	Missing or invalid alert_type, channel, or destination.

---

PUT /flare/v1/alerts/{id}

Update an existing alert setting. Only enabled and destination can be changed after creation.

Request

PUT /flare/v1/alerts/{id}
Authorization: Bearer <api_key>
Content-Type: application/json

Body

All fields are optional; include only those you want to change.

Field	Type	Description
enabled	boolean	true to activate the alert; false to pause it.
destination	string	New destination address. Max 320 characters.

Example — pause an alert

{ "enabled": false }

Example — update destination and re-enable

{
  "destination": "oncall@example.com",
  "enabled": true
}

Response

200 OK — the full updated alert setting object.

Errors

Status	Code	Condition
400	invalid_request	Invalid destination format.
404	alert_not_found	Alert setting does not exist for this project.

---

DELETE /flare/v1/alerts/{id}

Permanently delete an alert setting. The deletion is immediate and cannot be undone.

Request

DELETE /flare/v1/alerts/{id}
Authorization: Bearer <api_key>

Response

204 No Content — no response body.

Errors

Status	Code	Condition
404	alert_not_found	Alert setting does not exist for this project.

See also

• Activity API — read the audit feed that backs the alert rule evaluations
• Errors — alert_not_found, invalid_threshold, and other failure modes
• Monitoring guide — set up dashboards, log shipping, and alert routing