Alerts API: Threshold Alerts and Email Notifications

Surqo automatically generates alerts whenever a sensor reading crosses a predefined agronomic threshold. Each violation creates a database record and, if no alert email has been sent for that farm in the last 30 minutes, dispatches a styled HTML email via the Resend API. The 30-minute cooldown is tracked in Upstash Redis, so multiple simultaneous violations all produce DB records but only the first email is sent per window. All alerts endpoints require a valid Supabase JWT in the Authorization: Bearer header.

Threshold Reference

Condition	Threshold	Severity
Soil moisture	< 25%	warning
Soil moisture	< 15%	critical
Air temperature	> 38°C	warning
Air temperature	> 42°C	critical
VPD	> 1.6 kPa	warning
VPD	> 2.5 kPa	critical
Battery	< 3400 mV	warning
Battery	< 3200 mV	critical

When severity is critical, the recommended action is “Revisar condiciones del cultivo inmediatamente” and the response time is set to 2h. For warning alerts the recommended action is “Monitorear de cerca en las próximas horas” and response time is 6h.

Endpoints

GET /api/v1/alerts/active

Returns up to 50 unresolved alerts belonging to the authenticated user’s farms, ordered by created_at descending.

farm_id

string (UUID)

Filter to a single farm. The requesting user must own that farm, otherwise 403 is returned.

Response — 200 OK — list[AlertResponse]

GET /api/v1/alerts/history

Returns resolved and unresolved alerts for the user’s farms.

farm_id

string (UUID)

Filter to a specific farm owned by the user.

limit

integer

Maximum number of records to return. Defaults to 20.

Response — 200 OK — list[AlertResponse]

GET /api/v1/alerts/{alert_id}

Fetch a single alert by its UUID.

alert_id

string (UUID)

required

The UUID of the alert to retrieve. Returns 404 if not found and 403 if the farm does not belong to the requesting user.

Response — 200 OK — AlertResponse

PATCH /api/v1/alerts/{alert_id}/resolve

Mark an alert as resolved (or un-resolve it). Sets resolved_at to the current UTC timestamp when resolved: true.

alert_id

string (UUID)

required

UUID of the alert to resolve.

Request body

resolved

boolean

required

Set to true to resolve the alert. Set to false to reopen it (clears resolved_at).

Response — 200 OK — Updated AlertResponse

POST /api/v1/alerts/{alert_id}/notify

Manually re-send the email notification for an alert. Useful for renotifications or testing the email pipeline. Unlike the automatic flow this endpoint does not check the Redis cooldown — it always attempts delivery.

alert_id

string (UUID)

required

UUID of the alert to notify about.

Request body

to_email

string

required

Recipient email address. If the alert has a linked farm with owner_email configured, that value is used when this field is omitted.

farm_name

string

Display name for the farm used in the email subject and body. Defaults to "Finca".

Response — 200 OK — Updated AlertResponse with email_sent: true Error responses

Status	Condition
`403`	Alert belongs to a farm not owned by the user
`404`	Alert not found
`422`	No `to_email` provided and no email configured on the farm
`502`	Resend API call failed — verify `RESEND_API_KEY`

Alert Object

{
  "id": "uuid-alerta",
  "farm_id": "uuid-finca",
  "device_id": "ESP32-CAMPO-001",
  "alert_type": "threshold_violation",
  "severity": "warning",
  "title": "Humedad suelo baja: 22.3%",
  "description": "Lectura del dispositivo ESP32-CAMPO-001: Humedad suelo baja: 22.3%",
  "recommended_action": "Monitorear de cerca en las próximas horas",
  "response_time": "6h",
  "is_resolved": false,
  "resolved_at": null,
  "email_sent": true,
  "email_sent_at": "2026-06-28T10:05:00Z",
  "created_at": "2026-06-28T10:05:00Z"
}

Show Alert field reference

UUID

Unique identifier for the alert record.

farm_id

UUID | null

The farm this alert belongs to. May be null for system-level alerts.

device_id

string | null

The ESP32 device ID (MAC-derived) that produced the violating reading.

alert_type

string

Always "threshold_violation" for automatically generated alerts.

severity

string

"warning" or "critical".

title

string

Short human-readable description, e.g. "Humedad suelo baja: 22.3%".

description

string

Full description including the originating device.

recommended_action

string | null

Suggested agronomic action for the farmer.

response_time

string | null

Urgency window — "2h" for critical, "6h" for warning.

is_resolved

boolean

Whether the alert has been acknowledged and resolved.

resolved_at

datetime | null

UTC timestamp when the alert was resolved. null if still active.

email_sent

boolean

Whether an email notification was dispatched for this alert.

email_sent_at

datetime | null

UTC timestamp of the email dispatch.

created_at

datetime

UTC timestamp when the alert was created.

Email Cooldown

The 30-minute Redis cooldown is per farm. When multiple threshold violations arrive in the same 30-minute window, all violations create database records but only the first email is sent. If Redis is unavailable the cooldown check is skipped and the email is sent anyway, so delivery is always guaranteed.

The cooldown key stored in Redis is alert_email_cooldown:{farm_id} with a TTL of 1800 seconds (30 minutes). Once an email is sent, all alerts in that batch have their email_sent and email_sent_at fields set to reflect the delivery.

Visión General

Endpoints

Conceptos Avanzados

Alerts API: Threshold Alerts and Email Notifications

Threshold Reference

Endpoints

GET /api/v1/alerts/active

GET /api/v1/alerts/history

GET /api/v1/alerts/{alert_id}

PATCH /api/v1/alerts/{alert_id}/resolve

POST /api/v1/alerts/{alert_id}/notify

Alert Object

Email Cooldown

Build docs developers (and LLMs) love

Visión General

Endpoints

Conceptos Avanzados

Documentation Index

​Threshold Reference

​Endpoints

​GET /api/v1/alerts/active

​GET /api/v1/alerts/history

​GET /api/v1/alerts/{alert_id}

​PATCH /api/v1/alerts/{alert_id}/resolve

​POST /api/v1/alerts/{alert_id}/notify

​Alert Object

​Email Cooldown

Build docs developers (and LLMs) love

Threshold Reference

Endpoints

GET /api/v1/alerts/active

GET /api/v1/alerts/history

GET /api/v1/alerts/{alert_id}

PATCH /api/v1/alerts/{alert_id}/resolve

POST /api/v1/alerts/{alert_id}/notify

Alert Object

Email Cooldown