1KEY Developers
Guides

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
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}'
json
{
  "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

json
{ "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.

json
{ "key": "lift", "action": "move", "direction": "up" }
json
{ "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:

json
{
  "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
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

json
{ "key": "barrier", "value": true }

true opens, false closes, with the same 30-second rule as locks.

Switches and plugs

json
{ "key": "switch", "value": true }

A plug that meters what it powers also reports power (W) and energy (kWh).

Dimmers

json
{ "key": "level", "value": 60 }

0–100 %; 0 is off.

Shades and blinds

json
{ "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:

json
{ "key": "mode", "value": "heat" }
json
{ "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

json
{ "key": "color", "value": {"hue": 30, "saturation": 90} }
json
{ "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

json
{ "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:

  1. Events. A channel.observed event arrives when the device reports. Follow the hub's events.
  2. Read. GET /hubs/{hub_id}/devices/{device_id} returns the channel's current status.

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.