1KEY Developers
Guides

Settings

Settings

A device's settings are its own configuration: a lock's auto-lock time, a motion sensor's sensitivity, how often a meter reports. Each device describes its own; the hub lists them as the device gives them.

Reading settings

curl
curl https://api.1keyplatform.dev/v1/hubs/1key-xfy2-nmf4-5xwp/devices/7/settings \
  -H "Authorization: Bearer $ONEKEY_API_KEY"
json
{
  "data": [
    {
      "id": "auto_lock",
      "title": "Auto-lock",
      "value": 0,
      "min": 0,
      "max": 300,
      "unit": "s",
      "default": 0,
      "readonly": false,
      "advanced": false
    },
    {
      "id": "2",
      "title": "Motion sensitivity",
      "value": 8,
      "min": 1,
      "max": 10,
      "default": 8,
      "readonly": false,
      "advanced": true
    }
  ]
}
Field
id Opaque. Use it as given to change the setting
value What the device last reported
pending A value sent and not yet reported by the device
min, max, step, default, unit What the device accepts, when it says
readonly Can't be changed
advanced Rarely changed; a UI can tuck it away
source For wakeup_interval: device (its own), quirk (the hub's correction for the product) or override (set through the API)

Needs hubs:read.

Changing a setting

curl
curl -X PATCH https://api.1keyplatform.dev/v1/hubs/1key-xfy2-nmf4-5xwp/devices/7/settings/auto_lock \
  -H "Authorization: Bearer $ONEKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"value": 30}'
json
{ "device_id": 7, "id": "auto_lock", "pending": 30 }

202 means the hub sent it. A device that sleeps takes it at its next wake-up; read the settings again to see the device's value. "value": null takes back a value set through the API, where the hub can. Needs hubs:write.

Refusal Why
400 "that setting is read-only" readonly
400 "that value is outside the range the device gave" outside min..max, or off step
400 "that interval would drain the device's battery…" a wakeup_interval below what the hub allows
422 command_refused a lock, keypad or garage door that did not join securely enough to be driven: its settings are read-only

Settings every device of a kind has

Setting Devices
auto_lock Locks Seconds after unlocking until it locks itself; 0 never. Many locks ship with it off
wakeup_interval Battery devices that sleep Seconds between check-ins. Shorter drains the battery; the hub's least is usually an hour

Other settings are the device's own and differ by product; the device registry links each product's manual.