> 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"}}}}}}}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.ruuvi.com/communicate-with-ruuvi-cloud/cloud/user-api/alerts.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.