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 https://api.1keyplatform.dev/v1/hubs/1key-xfy2-nmf4-5xwp/devices/7 \
  -H "Authorization: Bearer $ONEKEY_API_KEY"

{
  "id": 7,
  "name": "Front door",
  "manufacturer": "Yale",
  "model": "YRD256",
  "channels": [
    { "key": "battery", "endpoint": 0, "kind": "battery", "unit": "%", "readable": true, "writable": false, "capabilities": {}, "available": true,
      "value": 82, "observed_at": "2026-10-03T13:58:00.000000Z", "desired": null, "desired_at": null, "status": "synchronized" },
    { "key": "lock", "endpoint": 0, "kind": "lock", "unit": null, "readable": true, "writable": true, "capabilities": {}, "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, set by you (below).

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

Channel keys

A device has only the channels it reported supporting. Check writable before sending a command.

Names and rooms

A device's name is what the hub reports unless you set one; room is yours alone. 1key keeps both in the cloud, so they survive a hub restart:

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. 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 -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"}'

{ "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 optional: the 5-digit PIN, DSK or QR text printed on the device or its box. Locks need it to join securely enough to be driven. DELETE /hubs/{hub_id}/pairing closes the window early. Needs hubs:write.

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

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

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.

Trying it in the portal

Each hub's Devices tab in the portal is built on these endpoints. Its console shows every request, response and event, can copy any request as curl, and can act with one of your API keys' scopes to see permission errors.

When the hub can't answer

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