/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 -
diverged -
failed
Parameters
| Name | In | Type | Description |
|---|---|---|---|
hub_id
|
path |
string
|
The hub ID printed on the hub (lowercase). |
device_id
|
path |
integer
|
|
Idempotency-Key
|
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
{
"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
invalid_request
The request is malformed or a field is invalid.
unauthenticated
Missing, malformed, revoked or unknown API key.
insufficient_scope
The key lacks the scope this operation needs.
not_found
No such resource, or it is not your organization's.
command_refused
The hub refused the command, for example a lock that did not join securely enough to be driven.
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.