1KEY Developers
API reference

Devices

Base URL https://api.1keyplatform.dev/v1. Every endpoint below is generated from the OpenAPI contract, which you can download as openapi.yaml.

Log in to send these requests to your organization from this page.

Devices

Devices connected to a hub and their channels, read live from the hub.

POST /hubs/{hub_id}/pairing/confirm

Confirm a joining device's setup code

Needs the hubs:write scope.

Answers a network.setup_code_requested event: a device added with only its PIN, or none, that asks for its most secure classes. Show the event's code and have someone check it against the device's label. When it matches, send this, with setup_code the label's first five digits if pin_needed is true. When it doesn't, close the window (DELETE /hubs/{hub_id}/pairing). Unanswered within expires_in_s seconds, or with the wrong digits, the device joins without those classes and has to be removed and added again. 404 when no device is waiting: none asked, it was answered, or its time ran out.

Parameters

Name In Type Description
hub_id required path string The hub ID printed on the hub (lowercase).

Body

setup_code string · optional The setup code's first five digits, from the label. Only when pin_needed is true.

Responses

204 Confirmed.

Errors

400 invalid_request The request is malformed or a field is invalid.
401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
404 not_found No such resource, or it is not your organization's.
503 hub_offline hub_offline: the hub is not connected. hub_unavailable: it is connected but cannot do it now, for example its radio is down or it does not know the time yet.
504 The hub did not answer in time.
POST /hubs/{hub_id}/devices/{device_id}/ping

Ping a device

Needs the hubs:command scope.

Sends the device a Z-Wave no-op and waits up to 30 seconds for its acknowledgement. An answer clears the hub's failed mark on it. A sleeping device answers only while awake; a battery lock spends a little battery. See pinging a device.

Parameters

Name In Type Description
hub_id required path string The hub ID printed on the hub (lowercase).
device_id required path integer

Responses

200 Whether the device answered.

Errors

401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
404 not_found No such resource, or it is not your organization's.
502 The hub failed, or the request could not be sent to it.
503 hub_offline hub_offline: the hub is not connected. hub_unavailable: it is connected but cannot do it now, for example its radio is down or it does not know the time yet.
504 The hub did not answer in time.
POST /hubs/{hub_id}/devices/reset

Start the hub's device network over

Needs the hubs:write scope.

Every device on the hub is forgotten, its network keys are new, and every setup code is dropped (setup_code.dropped). The devices aren't told: each needs its own reset before it can be added again. confirm must repeat the hub's ID.

Only an owner or admin may: a key whose creator is a member gets 403 forbidden.

Parameters

Name In Type Description
hub_id required path string The hub ID printed on the hub (lowercase).

Body

confirm string · required The hub's ID.

Responses

204 Started.

Errors

400 invalid_request The request is malformed or a field is invalid.
401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
404 not_found No such resource, or it is not your organization's.
503 hub_offline hub_offline: the hub is not connected. hub_unavailable: it is connected but cannot do it now, for example its radio is down or it does not know the time yet.
DELETE /hubs/{hub_id}/removal

Close the removal window

Needs the hubs:write scope.

Parameters

Name In Type Description
hub_id required path string The hub ID printed on the hub (lowercase).

Responses

204 Closed.

Errors

401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
404 not_found No such resource, or it is not your organization's.
503 hub_offline hub_offline: the hub is not connected. hub_unavailable: it is connected but cannot do it now, for example its radio is down or it does not know the time yet.
POST /hubs/{hub_id}/removal

Open the hub's network for a device to leave

Needs the hubs:write scope.

Press the device's button within two minutes. It leaves as a device.forgotten event.

Parameters

Name In Type Description
hub_id required path string The hub ID printed on the hub (lowercase).

Responses

202 The window is open.

Errors

401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
404 not_found No such resource, or it is not your organization's.
503 hub_offline hub_offline: the hub is not connected. hub_unavailable: it is connected but cannot do it now, for example its radio is down or it does not know the time yet.
504 The hub did not answer in time.
GET /hubs/{hub_id}/devices/{device_id}/zwave

Read a device's Z-Wave node

Needs the hubs:read scope.

The device's Z-Wave node as the hub's radio knows it, read live from the hub without asking the device. The fields follow the radio and may change with the hub's firmware; a value the radio can't give is null. A hop is a device_id, "hub", or null for a node the hub has no device for. 404 when the device isn't on the Z-Wave network. See Z-Wave diagnostics.

Parameters

Name In Type Description
hub_id required path string The hub ID printed on the hub (lowercase).
device_id required path integer

Responses

200 The node.

Errors

401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
404 not_found No such resource, or it is not your organization's.
502 The hub failed, or the request could not be sent to it.
503 hub_offline hub_offline: the hub is not connected. hub_unavailable: it is connected but cannot do it now, for example its radio is down or it does not know the time yet.
504 The hub did not answer in time.
POST /hubs/{hub_id}/devices/{device_id}/replace

Replace a failed device with a new one

Needs the hubs:write scope.

Opens the hub's network for two minutes for a new device to take the place of one the hub can no longer reach; put the new device in pairing mode. It arrives as device.added, takes the failed device's name and room, and goes through setup itself. The failed device is forgotten. 400 for a device the hub hasn't marked failed.

Parameters

Name In Type Description
hub_id required path string The hub ID printed on the hub (lowercase).
device_id required path integer

Body

setup_code string · optional The new device's 5-digit PIN, DSK or QR text.

Responses

202 The window is open.

Errors

400 invalid_request The request is malformed or a field is invalid.
401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
404 not_found No such resource, or it is not your organization's.
503 hub_offline hub_offline: the hub is not connected. hub_unavailable: it is connected but cannot do it now, for example its radio is down or it does not know the time yet.
504 The hub did not answer in time.
GET /hubs/{hub_id}/devices

List a hub's devices

Needs the hubs:read scope.

Asked of the hub live, so it fails with 503 hub_offline while the hub is disconnected and 504 hub_timeout if it does not answer within 10 seconds. Channels are listed without their values; get a device for those.

Parameters

Name In Type Description
hub_id required path string The hub ID printed on the hub (lowercase).
needs_setup optional query boolean true for only the devices whose setup isn't complete; false for only those whose is.

Responses

200 The hub's devices.

Errors

401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
404 not_found No such resource, or it is not your organization's.
502 The hub failed, or the request could not be sent to it.
503 hub_offline hub_offline: the hub is not connected. hub_unavailable: it is connected but cannot do it now, for example its radio is down or it does not know the time yet.
504 The hub did not answer in time.
DELETE /hubs/{hub_id}/pairing

Close the pairing window

Needs the hubs:write scope.

Closes the window, and refuses a device waiting for its setup code to be confirmed: it joins without its most secure classes.

Parameters

Name In Type Description
hub_id required path string The hub ID printed on the hub (lowercase).

Responses

204 Closed.

Errors

401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
404 not_found No such resource, or it is not your organization's.
503 hub_offline hub_offline: the hub is not connected. hub_unavailable: it is connected but cannot do it now, for example its radio is down or it does not know the time yet.
POST /hubs/{hub_id}/pairing

Open the hub's network for a device to join

Needs the hubs:write scope.

The hub listens for one device for two minutes; put the device in pairing mode. It arrives as a device.added event. Give its whole setup code (the QR text or the DSK) when it has one. With only the PIN, or none, a device that asks for its most secure classes waits after joining for its code to be confirmed: see POST /hubs/{hub_id}/pairing/confirm.

Parameters

Name In Type Description
hub_id required path string The hub ID printed on the hub (lowercase).

Body

security "legacy" | "without_code" · optional legacy adds a lock that can't join with S2, with the older security mode (S0). without_code adds a device with no setup code and without its most secure classes: a lock or garage door added this way isn't driven. Neither takes a setup_code; sending both is refused with 400.
setup_code string · optional The device's QR text, DSK, or 5-digit PIN. Locks need it to be driven.

Responses

202 The window is open.

Errors

400 invalid_request The request is malformed or a field is invalid.
401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
404 not_found No such resource, or it is not your organization's.
503 hub_offline hub_offline: the hub is not connected. hub_unavailable: it is connected but cannot do it now, for example its radio is down or it does not know the time yet.
504 The hub did not answer in time.
POST /hubs/{hub_id}/devices/{device_id}/describe

Describe a device for the registry

Needs the hubs:read scope.

What the device says about itself over Z-Wave (its fingerprint, configuration parameters and association groups), read by the hub, and a draft registry product from it: a Z-Wave JS device file to review before adding it to the registry. draft is null until the device has said which product it is. Takes a few seconds; asks the device itself. See describing a device.

Parameters

Name In Type Description
hub_id required path string The hub ID printed on the hub (lowercase).
device_id required path integer

Responses

200 The description and the draft.

Errors

401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
404 not_found No such resource, or it is not your organization's.
502 The hub failed, or the request could not be sent to it.
503 hub_offline hub_offline: the hub is not connected. hub_unavailable: it is connected but cannot do it now, for example its radio is down or it does not know the time yet.
504 The hub did not answer in time.
GET /channel-types

Every channel type, as JSON Schema

Each channel key with its one type and unit. Commands are validated against these.

Responses

200 The channel types.

Errors

401 unauthenticated Missing, malformed, revoked or unknown API key.
DELETE /hubs/{hub_id}/devices/{device_id}

Forget a device the hub can't reach

Needs the hubs:write scope.

A device still on the hub's network is refused with 400; remove it with the removal window. With force=true the hub pings the device first and removes it, without exclusion, only if it doesn't answer; one that answers is refused with 409 device_responding.

Parameters

Name In Type Description
hub_id required path string The hub ID printed on the hub (lowercase).
device_id required path integer
force optional query boolean, default false Ping the device and remove it if it doesn't answer, without exclusion.

Responses

204 Forgotten; a device.forgotten event follows, with reason: forced when forced.

Errors

400 invalid_request The request is malformed or a field is invalid.
401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
404 not_found No such resource, or it is not your organization's.
409 device_responding: with force, the device answered its ping; nothing is removed.
503 hub_offline hub_offline: the hub is not connected. hub_unavailable: it is connected but cannot do it now, for example its radio is down or it does not know the time yet.
GET /hubs/{hub_id}/devices/{device_id}

Get a device and its current state

Needs the hubs:read scope.

Each channel with the value the device last reported, asked of the hub live.

Parameters

Name In Type Description
hub_id required path string The hub ID printed on the hub (lowercase).
device_id required path integer

Responses

200 The device, with each channel's state. · returns a Device
200 · example
{
  "channels": [
    {
      "available": true,
      "category": "diagnostic",
      "desired": null,
      "desired_at": null,
      "endpoint": 0,
      "key": "battery",
      "label": null,
      "observable": true,
      "observed_at": "2026-10-03T13:58:00.000000Z",
      "readable": true,
      "schema": {
        "maximum": 100,
        "minimum": 0,
        "type": "number",
        "unit": "%"
      },
      "stateful": true,
      "status": "synchronized",
      "value": 82,
      "writable": false
    },
    {
      "available": true,
      "category": "primary",
      "desired": null,
      "desired_at": null,
      "endpoint": 0,
      "key": "lock",
      "label": null,
      "observable": true,
      "observed_at": "2026-10-03T14:00:00.000000Z",
      "readable": true,
      "schema": {
        "type": "boolean"
      },
      "stateful": true,
      "status": "synchronized",
      "value": true,
      "writable": true
    }
  ],
  "id": 7,
  "manufacturer": "Yale",
  "model": "YRD256",
  "name": "Front door"
}

Errors

401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
404 not_found No such resource, or it is not your organization's.
502 The hub failed, or the request could not be sent to it.
503 hub_offline hub_offline: the hub is not connected. hub_unavailable: it is connected but cannot do it now, for example its radio is down or it does not know the time yet.
504 The hub did not answer in time.
PATCH /hubs/{hub_id}/devices/{device_id}

Name a device and set its room

Needs the hubs:write scope.

Kept on the hub. Send name, room or both; null clears one. A device.updated event follows.

Parameters

Name In Type Description
hub_id required path string The hub ID printed on the hub (lowercase).
device_id required path integer

Body

name string or null · optional
room string or null · optional

Responses

200 The device. · returns a Device

Errors

400 invalid_request The request is malformed or a field is invalid.
401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
404 not_found No such resource, or it is not your organization's.
502 The hub failed, or the request could not be sent to it.
503 hub_offline hub_offline: the hub is not connected. hub_unavailable: it is connected but cannot do it now, for example its radio is down or it does not know the time yet.
504 The hub did not answer in time.