1KEY Developers
API reference

Commands

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.

Commands

Actions sent to a hub's devices.

POST /hubs/{hub_id}/devices/{device_id}/commands

Command a device

Needs the hubs:command scope.

Asks the hub to set one of the device's writable channels: lock or unlock, set a setpoint, turn a switch on; or to move or stop a level, shade or fan. Several commands go as one batch under commands. 202 means the hub accepted it and handed it to the device: the channel's desired is set and its status is pending. The outcome is the channel's next reading: synchronized once the device reports the value, failed or diverged otherwise. Follow channel.observed events, or get the device.

How it ends: the channel's status on the device

  • synchronized Done. The device reports what you asked for.
  • diverged The device reported something else, such as a jammed lock.
  • failed The hub or radio gave up. No channel.observed follows.

Parameters

Name In Type Description
hub_id required path string The hub ID printed on the hub (lowercase).
device_id required path integer
Idempotency-Key optional header string, up to 255 characters Any unique string, up to 255 characters. A retry with the same key within 24 hours returns the first response instead of sending the command again.

Body

key string · required
action "set" | "move" | "stop" · optional move starts a level, lift, tilt or fan_speed moving towards one end; stop stops it. Neither sets desired: where it stops is the device's report.
direction "up" | "down" · optional Required for a move. up raises a level and opens a shade.
endpoint integer, 0–255 · optional Left out: the device's one channel with that key, decided by the hub. A device with several refuses it with 400.
for integer, 1–86400 · optional For a set: seconds after which the hub puts the channel back (a lock to locked, a garage door to closed, anything else to its previous value). Durable across restarts.
transition number, 0–7620 · optional Seconds a level, lift or colour takes to get there, or a full move.
value any · optional Required for a set; fits the channel's type (the channel reference): true/false for lock, switch and barrier; 0–100 % for level; % closed for lift; °C for setpoints; an option name for mode and fan_mode. Anything else is refused with 400.

Or a body of

commands array of ChannelCommand · required Sent to the hub as one batch, checked whole before anything is sent.

Responses

202 Accepted by the hub. · returns a Command
202 · example
{
  "channel": {
    "available": true,
    "category": "primary",
    "desired": false,
    "desired_at": "2026-10-03T14:03:10.000000Z",
    "endpoint": 0,
    "key": "lock",
    "label": null,
    "observable": true,
    "observed_at": "2026-10-03T14:00:00.000000Z",
    "readable": true,
    "schema": {
      "type": "boolean"
    },
    "stateful": true,
    "status": "pending",
    "value": true,
    "writable": true
  },
  "device_id": 7,
  "hub_id": "1key-xfy2-nmf4-5xwp"
}

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 The Idempotency-Key was used with a different request body: use a new key. Or a request with it is still running: retry shortly with the same key.
422 command_refused The hub refused the command, for example a lock that did not join securely enough to be driven.
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.