> For the complete documentation index, see [llms.txt](https://docs.ruuvi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ruuvi.com/communicate-with-ruuvi-cloud/cloud/user-api/alerts.md).
# Alerts
Alert management for sensors
## Get alerts
> Fetches alerts for all sensors the user has access to or a single sensor if an optional parameter is provided.
```json
{"openapi":"3.0.3","info":{"title":"Ruuvi Cloud - User API","version":"1.0.0"},"tags":[{"name":"Alerts","description":"Alert management for sensors"}],"servers":[{"url":"https://network.ruuvi.com"},{"url":"https://testnet.ruuvi.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"Success":{"type":"object","required":["result","data"],"properties":{"result":{"type":"string","enum":["success"]},"data":{"description":"Endpoint-specific payload"}}},"AlertsResponse":{"type":"object","required":["sensors"],"properties":{"sensors":{"type":"array","description":"List of sensors with their alerts","items":{"$ref":"#/components/schemas/SensorWithAlerts"}}}},"SensorWithAlerts":{"allOf":[{"$ref":"#/components/schemas/SensorBase"},{"type":"object","required":["subscription","alerts"],"properties":{"subscription":{"$ref":"#/components/schemas/Subscription"},"alerts":{"type":"array","description":"List of alerts configured for this sensor","items":{"$ref":"#/components/schemas/Alert"}}}}]},"SensorBase":{"type":"object","required":["owner","sensor","name","public","canShare","offsetTemperature","offsetHumidity","offsetPressure","customProfile","lastUpdated"],"properties":{"owner":{"type":"string","format":"email"},"sensor":{"type":"string","description":"MAC address of the sensor"},"name":{"type":"string"},"picture":{"type":"string","maxLength":2048},"public":{"type":"boolean"},"canShare":{"type":"boolean"},"offsetTemperature":{"type":"number","format":"float"},"offsetHumidity":{"type":"number","format":"float"},"offsetPressure":{"type":"number","format":"float"},"customProfile":{"type":"boolean"},"lastUpdated":{"type":"integer","format":"int64","description":"Epoch timestamp in seconds when the sensor or its profile was last updated (whichever is more recent).\n"}}},"Subscription":{"type":"object","required":["subscriptionName","maxClaims","maxShares","maxSharesPerSensor","maxHistoryDays","maxResolutionMinutes","emailAlertAllowed","pushAlertAllowed","telegramAlertAllowed","delayedAlertAllowed","pdfExportAllowed","offlineAlertAllowed","isActive","startTime","endTime","endAt","lastUpdated"],"properties":{"subscriptionName":{"type":"string"},"maxClaims":{"type":"integer"},"maxShares":{"type":"integer"},"maxSharesPerSensor":{"type":"integer"},"maxHistoryDays":{"type":"integer"},"maxResolutionMinutes":{"type":"integer"},"emailAlertAllowed":{"type":"boolean"},"pushAlertAllowed":{"type":"boolean"},"telegramAlertAllowed":{"type":"boolean"},"delayedAlertAllowed":{"type":"boolean"},"pdfExportAllowed":{"type":"boolean"},"offlineAlertAllowed":{"type":"boolean"},"isActive":{"type":"boolean"},"startTime":{"type":"integer","format":"int64","description":"Epoch timestamp in seconds when the subscription started."},"endTime":{"type":"integer","format":"int64","description":"Epoch timestamp in seconds when the subscription ends."},"endAt":{"type":"string","format":"date-time"},"lastUpdated":{"type":"integer","format":"int64","description":"Epoch timestamp in seconds when the subscription was last updated. If missing, it is assumed to be the current time.\n"}}},"Alert":{"type":"object","required":["type","min","max","counter","delay","enabled","description","triggered","lastUpdated"],"properties":{"type":{"$ref":"#/components/schemas/AlertType"},"min":{"type":"number","format":"double","description":"Lower limit for the alert condition"},"max":{"type":"number","format":"double","description":"Upper limit for the alert condition"},"counter":{"type":"integer","description":"Movement counter threshold (relevant for movement type alerts)"},"delay":{"type":"integer","description":"Delay in minutes before triggering the alert"},"enabled":{"type":"boolean","description":"Whether the alert is active"},"description":{"type":"string","description":"User-provided description of the alert"},"triggered":{"type":"boolean","description":"Whether the alert has been triggered"},"triggeredAt":{"type":"string","format":"date-time","description":"ISO 8601 timestamp when the alert was triggered. '1970-01-01T00:00:00.000Z' indicates the alert has never been triggered"},"lastUpdated":{"type":"integer","format":"int64","description":"Epoch timestamp in seconds when the alert was last updated"}}},"AlertType":{"type":"string","enum":["temperature","pressure","humidity","humidityAbsolute","dewPoint","signal","movement","battery","offline","luminosity","voc","co2","sound","soundInstant","soundAverage","soundPeak","nox","pm10","pm25","pm40","pm100","aqi"],"description":"Type of alert condition"},"Error":{"type":"object","required":["result","error","code"],"properties":{"result":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable explanation"},"code":{"type":"string","description":"Machine-readable primary error code"},"sub_code":{"nullable":true,"type":"string","description":"Optional secondary code useful for client logic"}}}}},"paths":{"/alerts":{"get":{"summary":"Get alerts","operationId":"getAlerts","tags":["Alerts"],"description":"Fetches alerts for all sensors the user has access to or a single sensor if an optional parameter is provided.\n","parameters":[{"in":"query","name":"sensor","required":false,"description":"Optional filter to get alerts for a single sensor by its MAC address (e.g. C5:2A:E7:4D:CE:7F).\n","schema":{"type":"string","pattern":"^([0-9A-Fa-f]{2}:){5}[0-9A-Fa-f]{2}$"}}],"responses":{"200":{"description":"Alerts fetched successfully","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Success"},{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AlertsResponse"}}}]}}}},"401":{"description":"UNAUTHORIZED - Auth token missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"FORBIDDEN - User does not have access to the requested sensor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## Create and update Alerts
> Sets an alert on a sensor for a given metric. The alert condition is tested\
> against the absolute value received from the sensors in conjunction with the user-set\
> offsets for that particular sensor.
```json
{"openapi":"3.0.3","info":{"title":"Ruuvi Cloud - User API","version":"1.0.0"},"tags":[{"name":"Alerts","description":"Alert management for sensors"}],"servers":[{"url":"https://network.ruuvi.com"},{"url":"https://testnet.ruuvi.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"AlertType":{"type":"string","enum":["temperature","pressure","humidity","humidityAbsolute","dewPoint","signal","movement","battery","offline","luminosity","voc","co2","sound","soundInstant","soundAverage","soundPeak","nox","pm10","pm25","pm40","pm100","aqi"],"description":"Type of alert condition"},"Success":{"type":"object","required":["result","data"],"properties":{"result":{"type":"string","enum":["success"]},"data":{"description":"Endpoint-specific payload"}}},"AlertActionResult":{"type":"object","required":["action"],"properties":{"action":{"type":"string","description":"Result of the alert operation"}}},"Error":{"type":"object","required":["result","error","code"],"properties":{"result":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable explanation"},"code":{"type":"string","description":"Machine-readable primary error code"},"sub_code":{"nullable":true,"type":"string","description":"Optional secondary code useful for client logic"}}}}},"paths":{"/alerts":{"post":{"summary":"Create and update Alerts","description":"Sets an alert on a sensor for a given metric. The alert condition is tested\nagainst the absolute value received from the sensors in conjunction with the user-set\noffsets for that particular sensor.\n","operationId":"setAlert","tags":["Alerts"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["sensor","type"],"properties":{"sensor":{"type":"string","description":"MAC address of the sensor (e.g. `C5:2A:E7:4D:CE:7F`)","pattern":"^([0-9A-Fa-f]{2}:){5}[0-9A-Fa-f]{2}$"},"type":{"$ref":"#/components/schemas/AlertType"},"enabled":{"type":"boolean","description":"Whether the alert is active. If missing, defaults to false. If value was already existing, it will not be changed."},"min":{"type":"number","format":"double","description":"Lower limit for the alert condition. If missing, defaults to 0. If value was already existing, it will not be changed."},"max":{"type":"number","format":"double","description":"Upper limit for the alert condition. If missing, defaults to 0. If value was already existing, it will not be changed."},"counter":{"type":"integer","description":"Movement counter threshold (relevant for movement type alerts). If missing, defaults to 0. If value was already existing, it will not be changed."},"description":{"type":"string","description":"User-provided description of the alert. If missing, defaults to empty string. If value was already existing, it will not be changed."},"delay":{"type":"integer","description":"Delay in minutes before triggering the alert. If missing, defaults to 0. If value was already existing, it will not be changed."},"timestamp":{"type":"integer","format":"int64","description":"Optional epoch timestamp for the alert. If missing, it is assumed to be the current time."}}}}}},"responses":{"200":{"description":"Alert stored or updated successfully","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Success"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AlertActionResult"}}}]}}}},"400":{"description":"BAD REQUEST - Missing or malformed fields (`sensor`, `type`, or `enabled` missing; sensor not MAC address; type not valid)\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"UNAUTHORIZED - Auth token missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"FORBIDDEN - User does not have permission to set alerts for this sensor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"CONFLICT - Alert with same or newer timestamp already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```