> 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.<br>

```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"}}}}}}}}}
```