Guides

Commands

A command sets one writable channel on a device: lock or unlock a door, set a temperature, turn on a switch.

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, "kind": "lock", "unit": null,
    "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. endpoint defaults to 0; set it for a device with several of one channel, such as a two-gang switch.

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

Channel	`value`
`lock`	`false` unlocks, `true` locks
`barrier`	`true` opens, `false` closes
`switch`	`true` on, `false` off
`level`, `position`	0–99
`heating_setpoint`, `cooling_setpoint`	degrees C, such as `21.5`
`mode`	a mode name, such as `"heat"`
`fan_mode`	a fan mode name
`color`	`{"red": 255, "green": 80, "blue": 0}`

The devices guide lists every channel.

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.observed event arrives when the device reports. Follow the hub's events.
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, or a value the channel doesn't take. The message says which
404	`not_found`	No such device or channel on the hub
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.

Retry on network errors, 429, 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.