1KEY Developers
Guides

Devices

Devices

A hub's devices are the locks, thermostats, switches and sensors joined to it. Their state lives on the hub: the API asks the hub live, so these calls need the hub online.

Devices and channels

Each device has channels: the things it reads or sets. A lock has a lock channel and usually battery; a thermostat has temperature, mode and heating_setpoint; a two-gang switch has a switch channel on endpoint 1 and on endpoint 2.

curl
curl https://api.1keyplatform.dev/v1/hubs/1key-xfy2-nmf4-5xwp/devices/7 \
  -H "Authorization: Bearer $ONEKEY_API_KEY"
json
{
  "id": 7,
  "name": "Front door",
  "manufacturer": "Yale",
  "model": "YRD256",
  "channels": [
    { "key": "battery", "endpoint": 0, "label": null, "category": "diagnostic", "readable": true, "writable": false, "observable": true, "stateful": true,
      "schema": { "type": "number", "unit": "%", "minimum": 0, "maximum": 100 }, "available": true,
      "value": 82, "observed_at": "2026-10-03T13:58:00.000000Z", "desired": null, "desired_at": null, "status": "synchronized" },
    { "key": "lock", "endpoint": 0, "label": null, "category": "primary", "readable": true, "writable": true, "observable": true, "stateful": true,
      "schema": { "type": "boolean" }, "available": true,
      "value": true, "observed_at": "2026-10-03T14:00:00.000000Z", "desired": null, "desired_at": null, "status": "synchronized" }
  ]
}

GET /hubs/{hub_id}/devices lists every device with its channels, without values. Get one device for its values. Both need hubs:read. Each device also carries room, null until you set one (below).

listens says when a device hears the hub:

listens
always any time; mains-powered devices
on_demand any time, after a moment to wake; battery locks and thermostats
on_wake only when it wakes, on its interval or when its button is pressed; a command or test waits until then
null not known yet, before the hub has interviewed it

A channel's value is only ever what the device last reported. desired is what the last command asked for, and status compares them:

status Meaning
unknown Nothing asked, nothing reported yet
synchronized The device reports what was asked, or nothing was asked
pending A command is under way
diverged The device has since reported something else
failed The command was refused or abandoned

Channel keys

Every channel key has one type and one unit, whatever the device's protocol: the channel reference lists them all. In short: switches and locks are true/false; brightness and fan speed are 0–100 %; shades are % closed (0 fully open); temperatures are °C; contact is true when closed; thermostat modes and alarm states are named values.

A device has only the channels it reported supporting. Check writable before sending a command; a command whose value doesn't fit its channel's type is refused with 400 before it reaches the hub.

Product information

Every device carries product: what 1key's device registry knows about its model, or null when it isn't in the registry.

json
"product": {
  "id": "0x0129-yrd256",
  "manufacturer": "Yale",
  "label": "YRD256",
  "description": "Assure Lock SL",
  "manual_url": "https://...",
  "support": "supported",
  "firmware_update": { "version": "1.5", "changelog": "* ...", "region": "usa" }
}

firmware_update is the newest published firmware for the device's model that is newer than the firmware it reports, or null. The API reports the update; it doesn't install it.

GET /products/{product_id} has the rest: the manufacturer's inclusion, exclusion, reset and wake-up steps, its configuration parameters by firmware version, and known firmware issues. To find a model before it's on a hub, search by maker, model or description:

curl
curl "https://api.1keyplatform.dev/v1/products?q=yale+lock" \
  -H "Authorization: Bearer $ONEKEY_API_KEY"

fingerprint (manufacturer_id:product_type:product_id) and firmware return the one product a device with that fingerprint is. Any API key can read products.

Names and rooms

Name a device and set its room on the hub. They belong to the hub's device record, so they appear wherever the device does:

curl
curl -X PATCH https://api.1keyplatform.dev/v1/hubs/1key-xfy2-nmf4-5xwp/devices/7 \
  -H "Authorization: Bearer $ONEKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Main entrance", "room": "Entrance"}'

Send either or both; null clears one. The answer is the device, and a device.updated event follows. Needs hubs:write.

Adding a device

Open the hub's network, then put the device in pairing mode (usually three presses of its button, or as its manual says):

curl
curl -X POST https://api.1keyplatform.dev/v1/hubs/1key-xfy2-nmf4-5xwp/pairing \
  -H "Authorization: Bearer $ONEKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"setup_code": "12345"}'
json
{ "status": "open", "expires_in": 120 }

The hub listens for one device for two minutes. When it joins, a device.added event arrives with its device_id. setup_code is the QR text, DSK or 5-digit PIN printed on the device or its box. Give the whole code (QR or DSK) when there is one: then nobody is asked anything while the device joins. Locks need a code to join securely enough to be driven. A lock that can't join with S2 can be added with {"security": "legacy"} and no code, for the older security mode (S0). DELETE /hubs/{hub_id}/pairing closes the window early. Needs hubs:write.

Confirming the setup code

A device added with only its PIN, or no code, that asks for its most secure classes (what a lock or garage door needs to be driven) waits after joining for someone to check its code. The hub records network.setup_code_requested:

json
{ "window": "add", "code": "12345-67890-12345-67890-12345-67890-12345", "pin_needed": true, "expires_in_s": 240, "device_id": 21 }

Show code, the setup code's last seven groups as the device sent them, and ask someone to check them against the label:

pin_needed Ask for
true the label's first five digits, and that the seven groups match
false that the seven groups match; the PIN given when pairing stands

When they match, POST /hubs/{hub_id}/pairing/confirm, with {"setup_code": "12345"} when pin_needed is true. When they don't, DELETE /hubs/{hub_id}/pairing refuses it. A device not confirmed within expires_in_s seconds, refused, or given the wrong digits joins without those classes: its security is reduced or none, with reason timeout or wrong_code. Remove it and add it again. A device whose SmartStart code the hub holds is trusted on that code, and nobody is asked.

{"security": "without_code"} adds a device with no setup code, and nobody is asked: a device that asks for its most secure classes joins without them, and a lock or garage door added this way isn't driven. Offer it with a warning.

S0

{"security": "legacy"} admits a device with the older security mode, S0, for a device whose S2 join failed, a lock above all. The hub drives a lock, keypad or garage door on S0. S0 has one network key for every S0 device, and it reaches each device in a way that can be recorded: under a temporary key of all zeros to a device that supports only S0, and over an exchange with no authentication to one that supports S2. Whoever records the first, or sits in the middle of the second, holds the key and can open every S0 lock until the device network is started over. While any lock or garage door is on S0, the hub's health lists the ZWaveS0Door alarm, naming each.

A device added this way reports security {"result": "reduced"} with a reason:

reason Setup
not_supported It supports only S0, the most it can have Accepted, with a warning that S0 is weaker than S2
downgraded It supports S2 and fell back to S0 Offers removing it and adding it again with its setup code, to get S2

Setting a device up

A device that joins needs setting up before it's in service: a name and room, and proof it works. Its needs_setup is true until its setup is marked complete; GET /hubs/{hub_id}/devices?needs_setup=true lists the ones still to do. The hub runs the checks and keeps the mark, so every client sees the same.

curl
curl https://api.1keyplatform.dev/v1/hubs/1key-xfy2-nmf4-5xwp/devices/7/setup \
  -H "Authorization: Bearer $ONEKEY_API_KEY"
Check Required Passes when
name, room yes set
interview yes the hub has learned what the device is
reporting yes the device sends its reports to the hub
security devices with a lock, credential or barrier channel it joined securely enough for the hub to drive it (on Z-Wave, S2 Access Control or S0)
reachable yes it answered a ping, or reported something, in the last hour
works yes its test passed in the last hour
signal, battery, wakeup, firmware no advisory: weak signal, low battery, a battery device's wake-up interval, newer firmware

Each check says what it found in detail, a sentence for people. An advisory check also has a summary of a few words, such as Battery 100%, for a one-line overview: Signal good · Battery 100% · Wakes every 8 hours.

POST /hubs/{hub_id}/devices/{device_id}/setup/{action} runs what each check offers in actions: ping, identify, interview, repair_reporting, rebuild_routes, and test. The test runs on the hub: it sends a writable channel to another value and back, and each must come back as the device's report; a sensor or remote must report something within two minutes. A lock or barrier is unlocked and locked, or opened and closed, only when you send {"person_present": true}, after the person confirms they're at the device; without it the hub asks the device to report its state, and that report passes the test. Either way the device ends as it began. complete marks setup complete, and is refused until every required check passes; reopen puts the device back. Needs hubs:write, and hubs:command for test.

SmartStart

A device with a SmartStart QR code joins on its own whenever it's powered on: nobody presses anything, and nobody has to be there. Put its code on the hub's list with the name and room it takes when it joins:

curl
curl -X POST https://api.1keyplatform.dev/v1/hubs/1key-xfy2-nmf4-5xwp/setup-codes \
  -H "Authorization: Bearer $ONEKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code": "9001...", "name": "Kitchen dimmer", "room": "Kitchen"}'
json
{
  "id": "sc_3f2a9c0d1e4b5a67",
  "state": "waiting",
  "name": "Kitchen dimmer",
  "room": "Kitchen",
  "network": "long_range",
  "pin": "43448",
  "fingerprint": "0x027a:0x7000:0xe002",
  "firmware": "1.2",
  "product": { "id": "0x027a-zen77", "manufacturer": "Zooz", "label": "ZEN77", "…": "…" },
  "device_id": null,
  "reason": null,
  "added_at": "2026-10-06T15:02:11Z",
  "added_by": "[email protected]",
  "synced_at": "2026-10-06T15:02:11Z"
}

code is the QR code's text, 90 followed by its digits; it's never returned. A hub that is offline, or has never connected (one set up at a warehouse before it's installed), keeps nothing yet: the code is held and sent when the hub connects, and the answer is 202 with state queued. A device that can join over Long Range does; "network": "mesh" keeps it on the mesh, for one that has to reach the hub through repeaters.

The device joins within about 10 minutes of being powered on; power-cycle one that hasn't. A device still in another network never asks to join: remove it from that network, or reset it. When it joins, a device.added event arrives and the code's state becomes joined, with its device_id. The two stay linked: the device carries setup_code_id and the code's pin for as long as the code is on the hub's list.

Removing or forgetting a device that joined from a code leaves the code on the hub's list with state disabled: it admits nothing, so the device can't rejoin on its own once it's reset. Adding the same code again enables it; deleting it removes it.

Request
GET /hubs/{hub_id}/setup-codes The hub's codes and their state
PATCH /hubs/{hub_id}/setup-codes/{id} Rename a code, or change its room, before its device joins
DELETE /hubs/{hub_id}/setup-codes/{id} Stop admitting the device. One that already joined stays on the network until it's removed or reset
POST /hubs/{hub_id}/setup-codes/{id}/restore Put a missing code back: one dropped by a network reset, or removed at the hub

A code is on one hub of an organization at a time: adding one already on another hub is refused, naming it. Only SmartStart codes (QR version 01) can be listed. A device whose QR code is S2-only is added with POST /hubs/{hub_id}/pairing and its code as setup_code. Needs hubs:write; listing needs hubs:read.

Removing a device

A device still on the hub's network leaves it with a hand on the device: open the removal window, then press the device's button.

curl
curl -X POST https://api.1keyplatform.dev/v1/hubs/1key-xfy2-nmf4-5xwp/removal \
  -H "Authorization: Bearer $ONEKEY_API_KEY"

A device.forgotten event confirms it. DELETE /hubs/{hub_id}/removal closes the window.

The same window takes a device that is still joined to another network, so it can then be added here. No event follows for a device this hub never had: the window closes once the device has left.

A device the hub can no longer reach (its channels show available: false) can't press a button. Forget it instead:

curl
curl -X DELETE https://api.1keyplatform.dev/v1/hubs/1key-xfy2-nmf4-5xwp/devices/8 \
  -H "Authorization: Bearer $ONEKEY_API_KEY"

The hub refuses to forget a device still on its network (400): remove that one with the removal window. Both need hubs:write.

Force removal

A device that's gone but that the hub's radio hasn't given up on yet, such as one pulled off the wall or one whose battery died, is refused by a plain forget. Force it:

curl
curl -X DELETE "https://api.1keyplatform.dev/v1/hubs/1key-xfy2-nmf4-5xwp/devices/8?force=true" \
  -H "Authorization: Bearer $ONEKEY_API_KEY"

The hub decides whether the device is gone, then removes it from its network with no exclusion: 204, then device.forgotten with "reason": "forced".

Device Gone when
Listening (mains-powered), or a lock that wakes on demand It doesn't answer a ping within 10 seconds
Sleeping (on battery, waking on an interval) It has been silent for two of its wake-up intervals (its wakeup_interval setting, else what it reports, else 24 hours). Silence counts from the latest of when it was last heard, when the hub's clock was set, and when the hub's radio started, so right after the hub restarts a sleeping device can't be forced out until two intervals have passed. Needs the hub's clock: without it, 503 hub_unavailable

The radio then removes it as a failed node, and the hub deletes its record only once the radio confirms. A device that answers, one heard too recently, or a removal the radio doesn't confirm is refused with 409 device_responding, and nothing is removed: exclude it with the removal window, or power it off and try again. The hub never drops its own record of a device that's still on its network. Takes up to about 70 seconds. If the radio confirms the removal after the hub has answered 409, the device is still removed: device.forgotten with "reason": "forced" is the final word.

Replacing a failed device

A device the hub can no longer reach can be replaced without losing its place: open the replace window, then put the new device in pairing mode.

curl
curl -X POST https://api.1keyplatform.dev/v1/hubs/1key-xfy2-nmf4-5xwp/devices/7/replace \
  -H "Authorization: Bearer $ONEKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"setup_code": "43448"}'

The new device arrives as device.added, takes the failed device's name and room, and goes through setup itself; the failed one is forgotten. The hub refuses a device it hasn't marked failed: remove a working device instead. Needs hubs:write.

Pinging a device

POST /hubs/{hub_id}/devices/{device_id}/ping sends the device a Z-Wave no-op and waits up to 30 seconds for its acknowledgement:

json
{ "device_id": 7, "delivered": true, "ms": 42 }

An answer clears the hub's failed mark on the device. A sleeping device answers only while awake, and a battery lock spends a little battery on each ping. Needs hubs:command.

Describing a device

POST /hubs/{hub_id}/devices/{device_id}/describe asks the device what it says about itself over Z-Wave: its fingerprint, configuration parameters and association groups. The answer has the hub's describe and a draft, a Z-Wave JS device file (path, json) to review before adding the product to the registry; incomplete lists the sections the hub hadn't finished reading. draft is null until the device has said which product it is. Needs hubs:read.

Starting the device network over

POST /hubs/{hub_id}/devices/reset with {"confirm": "<hub_id>"} forgets every device on the hub and drops every setup code. The devices aren't told: each needs its own reset before it can be added again. Needs hubs:write.

Trying it in the portal

Everything in the portal runs through this API, and its API console, beside every page, shows each request with its response and a link to its reference. On a hub's Devices tab it also shows the hub's events as they arrive. The console copies any request as curl, and can act with one of your API keys instead of your session to show its permission errors.

When the hub can't answer

Status type Meaning
503 hub_offline The hub is not connected. Sent nothing
503 hub_unavailable The hub is connected but can't do it now: its radio is down, or it doesn't know the time yet
504 hub_timeout The hub did not answer within 10 seconds

To track state over time, follow events rather than polling devices.