Commands
Commands
A command sets one writable channel on a device: lock or unlock a door, set a temperature, turn on a switch. A level, shade or fan can also be moved and stopped, and several commands can go as one batch.
Sending a command
curl -X POST https://api.1keyplatform.dev/v1/hubs/1key-xfy2-nmf4-5xwp/devices/7/commands \
-H "Authorization: Bearer $ONEKEY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 6f1c2a1e-1b7d-4a3e-9c51-0f1d2b8e7a44" \
-d '{"key": "lock", "value": false}'
{
"hub_id": "1key-xfy2-nmf4-5xwp",
"device_id": 7,
"channel": {
"key": "lock", "endpoint": 0, "label": null, "category": "primary",
"readable": true, "writable": true, "observable": true, "stateful": true,
"schema": {"type": "boolean"},
"value": true, "observed_at": "2026-10-03T14:00:00.000000Z",
"desired": false, "desired_at": "2026-10-03T14:03:10.000000Z",
"status": "pending", "available": true
}
}
Needs hubs:command. Leave out endpoint and the command goes to the device's one channel with that key; set it for a device with several, such as a two-gang switch.
| Field | |
|---|---|
key |
The channel. Required. |
endpoint |
Which of several channels with that key. |
action |
set (the default), move or stop. |
value |
Required for a set: of the channel's type. |
direction |
Required for a move: up or down. |
transition |
Seconds, 0–7620: how long a level, lift or colour takes to get there, or a full move. A device that can't fade goes at its own pace. |
for |
Whole seconds, 1–86400, for a set: the hub puts the channel back afterwards. A lock goes back to locked, a garage door to closed, anything else to its value before the command. The hub keeps the timer through a restart. |
202 means the hub accepted the command and handed it to the device. It does not mean the door is unlocked yet: value is still what the device last reported, and status is pending.
Values
Each channel takes one type, in one unit, whatever the device: the channel reference lists them. A value that doesn't fit is refused with 400 invalid_request naming the channel and what it takes, before anything is sent to the hub.
| Channel | value |
|---|---|
lock |
false unlocks, true locks |
barrier |
true opens, false closes |
switch |
true on, false off |
level, fan_speed |
0–100 % |
lift, tilt |
0–100 % closed: 0 is fully open |
heating_setpoint, cooling_setpoint |
°C, such as 21.5 |
mode |
off, auto, cool, heat, emergency_heat, precooling, fan_only, dry, sleep |
fan_mode |
off, low, medium, high, on, auto, smart |
color |
{"hue": 0–360, "saturation": 0–100} |
color_temperature |
kelvin |
lock_mode |
normal, vacation, privacy, no_remote, passage |
For a while
{ "key": "lock", "value": false, "for": 30 }
Unlocks the door, and the hub locks it again after 30 seconds, even if it restarts or loses the cloud in between. A light set {"key": "switch", "value": true, "for": 600} goes back to how it was after ten minutes.
Putting it back is a put-back, as an automation's relock and a schedule's lock or close are. The hub writes it before the command goes out, so it survives a restart. When it falls due, each attempt is a new request with its own 30 seconds, confirmed by the device reporting the value:
| Channel | Attempts | Not confirmed |
|---|---|---|
lock |
Three, a minute apart | device.not_secured, and the hub's health lists NotSecured until the lock reports locked |
barrier |
One, confirmed within 90 seconds | As a lock, until it reports closed |
| Anything else | One | Nothing more |
A put-back ends early only on what happened at the device: a person changing the channel there (put_back.intervened), or another command to it that the device acknowledged, the same caller's included. A command that was refused or never delivered doesn't end it. No attempt is spent while the hub's radio is down; the put-back waits for it. Taken up after a restart on an untrusted clock, or due further off than it was set for, it is due at once. Forgetting the device ends its put-backs, and the hub's health stops listing it as NotSecured. A set that was refused puts nothing back, except to a lock or garage door, which may have moved. An unlock or open is never retried.
Each step is an event on the device: put_back.armed, put_back.commanded, put_back.attempted and put_back.ended, which says why it ended. A for put-back's cause is its command's, {"source": "remote", "actor": "cloud"}.
Moving and stopping
move starts a level, lift, tilt or fan_speed moving towards one end, as holding a button does; stop stops it. up raises a level and opens a shade.
{ "key": "lift", "action": "move", "direction": "up" }
{ "key": "lift", "action": "stop" }
Neither sets desired, and the answer's channel is null: where it stops arrives as the channel's next reading.
Batches
Several commands to one device go under commands, up to 32, in order:
{
"commands": [
{ "key": "level", "value": 80, "transition": 3 },
{ "key": "color_temperature", "value": 2700 }
]
}
Every command is checked before any is sent; one that doesn't fit refuses the batch with 400, naming it (commands[1].value: …). The answer has results in the same order, each with the channel a single command would have.
By device
Each device lists the channels it has; send the one you want. A device with several of one thing (a two-gang switch, a power strip) has the same key on each endpoint.
Locks
curl -X POST https://api.1keyplatform.dev/v1/hubs/1key-xfy2-nmf4-5xwp/devices/7/commands \
-H "Authorization: Bearer $ONEKEY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"key": "lock", "value": false}'
false unlocks, true locks. A lock moves within 30 seconds of the command or not at all: one it hasn't taken by then is reported failed and never sent again. A battery lock that only listens when woken is refused at once with 503 hub_unavailable. A lock that did not join securely enough to be driven is refused with 422 command_refused. Lock users and their PINs and cards are their own resource: see Access; auto-lock is a setting.
Garage doors and gates
{ "key": "barrier", "value": true }
true opens, false closes, with the same 30-second rule as locks.
Switches and plugs
{ "key": "switch", "value": true }
A plug that meters what it powers also reports power (W) and energy (kWh).
Dimmers
{ "key": "level", "value": 60 }
0–100 %; 0 is off.
Shades and blinds
{ "key": "lift", "value": 25 }
% closed: 0 fully open, 100 fully closed. A blind with slats also has tilt, the same way. Move and stop work as a wall button does: see Moving and stopping.
Thermostats
Set the mode, then the setpoint the mode uses:
{ "key": "mode", "value": "heat" }
{ "key": "heating_setpoint", "value": 21.5 }
mode's schema.options lists the modes this thermostat has.
Setpoints are always °C, whatever the thermostat shows. Each setpoint's schema says what this one takes:
| Field | |
|---|---|
minimum, maximum |
its range, in °C. A value outside it is refused |
step |
the smallest change it takes, in °C: exactly 5/9 (0.5555555555555556) for a thermostat set in whole °F, 0.5 for one in half degrees. Step from 0 by this exact value and round only for display |
display_unit |
°C or °F, the unit the thermostat shows; for displaying values to people |
A value between steps goes to the nearest one, and the reading's desired says which: 17.7 on a thermostat set in whole °F is 17.8 (64 °F). A setpoint the thermostat reports is rounded to 0.1 °C, so each °F value has exactly one °C value.
fan_mode sets the fan. temperature, humidity, operating_state (idle, heating, cooling, fan_only, pending_heat, pending_cool, vent) and fan_state are read-only.
Colour lights
{ "key": "color", "value": {"hue": 30, "saturation": 90} }
{ "key": "color_temperature", "value": 2700 }
Hue in degrees, saturation in %. A white bulb takes color_temperature in kelvin. Brightness is level. color_components sets a device's raw components (red, green, blue, warm_white, cold_white, …, each 0–255) for one that needs it.
Valves
{ "key": "valve", "value": false }
true opens a water or gas valve, false closes it.
Sensors and meters
Sensors take no commands; read them or follow their events. GET /hubs/{hub_id}/devices/{device_id} returns each channel with its value:
| Channel | Value |
|---|---|
contact |
true when closed |
motion, leak, heat, tamper |
true while detected |
binary |
a general-purpose sensor's state |
smoke, co |
normal, warning or critical |
temperature, water_temperature, dew_point |
°C |
humidity, absolute_humidity |
%, g/m³ |
illuminance, light_level |
lx, or % from a sensor that reports no lux |
pressure |
kPa |
co2, co_level, voc, pm25 |
ppm, ppm, ppm, µg/m³ |
uv_index, noise |
index, dB |
power, energy, voltage, current |
W (negative while exporting), kWh, V, A |
gas, water |
m³, cumulative |
battery |
% |
Each change arrives as a channel.observed event. How often a sensor or meter reports is often a setting.
Getting the outcome
The device reports back after it acts. Its report updates the channel, and status becomes:
status |
Meaning |
|---|---|
synchronized |
The device reports the value asked for: done |
diverged |
The device reported something else, for example a lock that jammed |
failed |
The hub or radio gave up |
Two ways to learn it:
- Events. A
channel.observedevent arrives when the device reports. Follow the hub's events. - Read.
GET /hubs/{hub_id}/devices/{device_id}returns the channel's currentstatus.
When the hub refuses
| Status | type |
Meaning |
|---|---|---|
| 400 | invalid_request |
The hub refused the arguments: a read-only channel, a value the channel doesn't take, or no endpoint for a device with several channels of that key. The message says which |
| 404 | not_found |
No such device or channel on the hub |
| 409 | conflict |
A newer command to the same lock or garage door replaced this one while it waited for a busy radio. It was not sent |
| 422 | command_refused |
The hub won't drive it, for example a lock that did not join securely enough |
| 503 | hub_offline, hub_unavailable |
The hub is not connected, or can't act now. Nothing was done |
| 504 | hub_timeout |
The hub did not answer within 10 seconds. It may still act; retry with the same Idempotency-Key |
Retrying safely
Send an Idempotency-Key header with every command: a new UUID per command, reused on retries. A retry with the same key within 24 hours returns the first response instead of sending the command again, and the hub runs it once even if two retries race. Reusing a key with a different body returns 409 idempotency_conflict; use a new key. A retry that arrives while the first request with its key is still running also gets 409 idempotency_conflict, saying so: retry it shortly with the same key.
Retry on network errors, 429, 500, 502, 503 and 504. Do not retry 400, 401, 403, 404 or 422: the same request fails the same way.
Commands are not queued for an offline hub: they fail at once with 503 hub_offline.