> 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/sensor-settings.md).
# Sensor Settings
Sensor settings management
## Get settings for sensor
> Returns settings for all sensors owned by the authenticated user. Optionally filter by a single sensor MAC address using the \`sensor\` query parameter.
```json
{"openapi":"3.0.3","info":{"title":"Ruuvi Cloud - User API","version":"1.0.0"},"tags":[{"name":"Sensor-Settings","description":"Sensor settings management"}],"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"}}},"SettingGetResult":{"type":"object","required":["sensors"],"properties":{"sensors":{"type":"array","items":{"$ref":"#/components/schemas/Settings"}}}},"Settings":{"type":"object","allOf":[{"$ref":"#/components/schemas/SensorBase"},{"type":"object","required":["subscription","settings"],"properties":{"subscription":{"$ref":"#/components/schemas/Subscription"},"settings":{"$ref":"#/components/schemas/SettingObject"}}}]},"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"}}},"SettingObject":{"type":"object","description":"Sensor settings as flattened key-value pairs.\n- Setting values are stored with keys matching the setting type name.\n- Each setting has a corresponding `{settingName}_lastUpdated` field containing an epoch timestamp.\n- Up to 500 setting pairs (1000 total properties including timestamps).\n- Setting values are strings (max 1000 chars), timestamp fields are integers (epoch seconds).\n\n\n**Property patterns:**\n- Pattern `^(?!.*_lastUpdated$).+$`: Setting value\n- Pattern `^.+_lastUpdated$`: Epoch timestamp in seconds for when the setting was last updated","maxProperties":1000,"additionalProperties":{"oneOf":[{"type":"string","maxLength":1000,"description":"Setting value (matches pattern: ^(?!.*_lastUpdated$).+$)"},{"type":"integer","format":"int64","description":"Epoch timestamp in seconds for when the setting was last updated (matches pattern: ^.+_lastUpdated$)"}]}},"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":{"/sensor-settings":{"get":{"summary":"Get settings for sensor","operationId":"getSensorSetting","tags":["Sensor-Settings"],"description":"Returns settings for all sensors owned by the authenticated user. Optionally filter by a single sensor MAC address using the `sensor` query parameter.\n","parameters":[{"in":"query","name":"sensor","required":false,"description":"Filter results to a single sensor by its MAC address (e.g. C6:F1:E7:D3:DA:11).\n","schema":{"type":"string","pattern":"^[0-9A-F]{2}(:[0-9A-F]{2}){5}$"}}],"responses":{"200":{"description":"Sensor settings fetched successfully","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Success"},{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/SettingGetResult"}}}]}}}},"401":{"description":"UNAUTHORIZED - Auth token missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"FORBIDDEN - User does not have access to this sensor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NOT FOUND - Sensor does not exist, or it exists but user does not have permission to view this sensor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## Configure a setting for a sensor
> Creates a new setting for given sensor
```json
{"openapi":"3.0.3","info":{"title":"Ruuvi Cloud - User API","version":"1.0.0"},"tags":[{"name":"Sensor-Settings","description":"Sensor settings management"}],"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"}}},"SettingSetResult":{"type":"object","required":["action"],"properties":{"action":{"type":"string","description":"Outcome of the set setting operation","enum":["added","updated"]}}},"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":{"/sensor-settings":{"post":{"summary":"Configure a setting for a sensor","description":"Creates a new setting for given sensor","operationId":"setSensorSetting","tags":["Sensor-Settings"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["sensor","value","type"],"properties":{"sensor":{"type":"string","description":"MAC address of the sensor (e.g. `C6:F1:E7:D3:DA:11`)","pattern":"^([0-9A-Fa-f]{2}:){5}[0-9A-Fa-f]{2}$"},"value":{"type":"array","description":"Array of strings\nExample: `[\"\\\"CuriousSetting\\\"\"]`\n","items":{"type":"string"}},"type":{"type":"array","description":"Array of setting types (strings)","items":{"type":"string"}},"timestamp":{"type":"integer","format":"int64","description":"Optional epoch timestamp for the setting. If missing, it is assumed to be the current time."}}}}}},"responses":{"200":{"description":"Setting stored or updated successfully","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Success"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SettingSetResult"}}}]}}}},"400":{"description":"INVALID - Missing or malformed fields (`sensor`, `value`, or `type` missing; sensor not MAC; value not JSON array; type not array)\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 edit this sensor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NOT FOUND - Sensor does not exist, or it exists but user does not have permission to view this sensor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"CONFLICT - Setting 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/sensor-settings.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.