---
title: "Send Command"
method: POST
path: "/send_command"
tags: ["Device Interactions"]
---

# Send Command

`POST /send_command`

## Request

- Base URL: `https://api.developer.atomberg-iot.com/v2`
- URL: `https://api.developer.atomberg-iot.com/v2/send_command`
- Auth: API key in header `x-api-key` and HTTP bearer

Send a command to a device. You need the device_id of the device you want to control. You can get it from the 'Get List of Devices' API. The full list of commands is:

| Command | Description | JSON | Accepted values for val | Comments |
| --- | --- | --- | --- | --- |
| Power | Turn the fan ON or OFF | {"power":val} | true or false |  |
| Speed Absolute | Set the speed to an absolute value | {"speed":val} | an integer from 1 to 6 |  |
| Speed Relative | Increase/decrease the speed | {"speedDelta":val} | one of -5, -4, -3, -2, -1, 1, 2, 3, 4, 5 |  |
| Sleep mode | Enable or disable sleep mode | {"sleep":val} | true or false |  |
| Timer | Set a preset timer | {"timer":val} | one of 0, 1, 2, 3, 4 | 0: off <br>1: 1 hour <br>2: 2 hours <br>3: 3 hours <br>4: 6 hours |
| Lights ON/OFF | Turn the light ON or OFF | {"led":val} | true or false | On Aris Starlight it restores the last known colour and brightness |
| Reverse | Reverse the direction of rotation | {"rev_mode":val} | true or false |  |
| Brightness Absolute | Set brightness to an absolute value | {"brightness":val} | an integer from 10 to 100 | Percentage |
| Brightness Delta | Increase/decrease brightness | {"brightnessDelta":val} | an integer from -90 to 90 | Percentage |
| Colour | Change the colour of the light | {"light_mode":val} | one of "warm", "cool", "daylight" |  |
| Buzzer | Enable or disable audible feedback | {"buzzer_status":val} | true or false |  |

Every fan accepts the **Base** commands. The other columns add more commands:

| Column | Commands it adds |
| --- | --- |
| Base | power, speed, speedDelta, sleep, timer, led |
| Brightness | brightness, brightnessDelta |
| Colour | light_mode |
| Extras | rev_mode, buzzer_status |

If you send a command that a series does not support (`No` in its column), you get a `400` error. The message lists the commands that series accepts.

| Model | Series | Base | Brightness | Colour | Extras |
| --- | --- | --- | --- | --- | --- |
| Renesa / Renesa+ / Studio+ | R1, R2, R3, R4, R6 | Yes | No | No | No |
| Aris | I2 | Yes | No | No | No |
| Erica | K1 | Yes | No | No | No |
| Renesa Fusion | R5 | Yes | No | No | No |
| Aris Gladius | I3, I4 | Yes | No | No | No |
| Aris Contour | M1, M2, M3 | Yes | Yes | No | No |
| Renesa Elite / Studio Nexus | S1, S2, S3 | Yes | Yes | No | No |
| Aris Starlight | I1, I5 | Yes | Yes | Yes | No |
| Emperion Magna | O1 | Yes | Yes | Yes | Yes |
# Water purifier commands

Water purifiers have their own set of commands. **Send one command key per message.** A request with two commands is rejected. The only exception is the `sleep_mode` sub-keys (`start_utc` and `stop_utc`). They are sent with `sleep_mode` and do not count as separate commands.

| Command | Description | JSON | Accepted values for val | Comments |
| --- | --- | --- | --- | --- |
| Mode | Set the purification mode | {"mode":val} | 0, 1, 2, 3, 4, 10 | See the mode table below |
| Fallback mode | Mode used when the device falls back from the selected mode | {"fallback_mode":val} | 0, 2, 3, 4 | RO_ONLY or a TasteTune mode. ADAPTIVE and Vacay are not allowed |
| TDS threshold | Input TDS threshold that decides RO vs UF treatment | {"tds_threshold":val} | 100 to 300 | Parts per million |
| Idle sleep | Turn off the display and lights while the unit is idle | {"idle_sleep":val} | 0, 1 | 0: off, 1: on |
| Sleep window on | Turn on the daily sleep window | {"sleep_mode":1,<br>"start_utc":start,<br>"stop_utc":stop} | start and stop: uint32 epoch seconds | Send all three keys **together** in one message. See Sleep window sub-keys below |
| Sleep window off | Turn off the daily sleep window | {"sleep_mode":0} | - | Send it on its own. start_utc and stop_utc are not accepted with 0 |

## Purification modes

| Value | Mode | Meaning |
| --- | --- | --- |
| 0 | RO_ONLY | Always use RO treatment |
| 1 | ADAPTIVE | Bypass RO |
| 2 | TasteTune 50-100 | Keeps purified water TDS between 50 and 100 ppm |
| 3 | TasteTune 75-125 | Keeps purified water TDS between 75 and 125 ppm |
| 4 | TasteTune 100-150 | Keeps purified water TDS between 100 and 150 ppm |
| 10 | Vacay | Holiday mode |

## Sleep window sub-keys

`start_utc` and `stop_utc` are sub-keys of `sleep_mode`. Send them only with `sleep_mode` set to `1`, in the same message. They do not count as separate commands. In 'Get List of Devices', `sleep_mode` lists them under `requires`, and each one has `sub_key_of: "sleep_mode"`.

| Sub-key | Sent with | Accepted values | Meaning |
| --- | --- | --- | --- |
| start_utc | "sleep_mode": 1 | uint32 epoch seconds | Start of the daily sleep window |
| stop_utc | "sleep_mode": 1 | uint32 epoch seconds | End of the daily sleep window |

```json
{
  "device_id": "a0764ee4210c",
  "command": { "sleep_mode": 1, "start_utc": 1767304800, "stop_utc": 1767330000 }
}
```

Send `start_utc` and `stop_utc` as **numbers, not strings**. Only the time of day is used (epoch modulo 86400), so the window repeats every day. To turn the window off, send `{"sleep_mode":0}` on its own.

# Smart locks

Locks do not accept commands through this API. A command sent to a G1 Cypheo Elite or an Azhero Smart Door Lock / SL1 returns a `400`. This is also why `supported_commands` is empty for locks in 'Get List of Devices'. Use 'Get Device State' to read a lock and 'Get Lock Dynamic PIN' to create a guest PIN.

# Sending the command locally

**Local control over UDP is currently available for fans only.** To control water purifiers, use the 'Send Command' API.

You can control the fans locally over UDP, without having to rely on the cloud API. The steps involved are as follows:
## Step 1: Check if the device is available on the local network. 
Each device sends a beacon packet over UDP every one second on port 5625. This beacon packet contains the MAC address of the device, followed by the series (mac_series). You can have a background service that listens for the beacon packets and stores the mapping of MAC against the IP address.
A sample implementation in Python is given below:
```plaintext
import socket
import threading
import time

# Define the UDP port to listen on
UDP_IP = "0.0.0.0"  # Listen on all available interfaces
UDP_PORT = 5625
BUFFER_SIZE = 4096  # Adjust as needed
TIMEOUT = 2  # seconds

available_devices = {}
lock = threading.Lock()

def cleanup_inactive_devices():
    while True:
        now = time.time()
        with lock:
            inactive_devices = [mac for mac, (ip, ts) in available_devices.items() if now - ts > TIMEOUT]
            for mac in inactive_devices:
                print(f"Removing inactive device: {mac}")
                del available_devices[mac]
        time.sleep(1) 

def main():
    # Create a UDP socket
    sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)

    # Bind the socket to the IP and port
    sock.bind((UDP_IP, UDP_PORT))
    print(f"Listening for UDP packets on port {UDP_PORT}...")

    # Start background cleanup thread
    threading.Thread(target=cleanup_inactive_devices, daemon=True).start()

    try:
        while True:
            data, addr = sock.recvfrom(BUFFER_SIZE)  # Receive packet
            ip, port = addr
            content = data.decode(errors='replace')
            if len(content) <= 15:
                print("Beacon packet received")
                mac = content[:12]
                with lock:
                    available_devices[mac] = (ip,time.time())
            print(f"Received packet from {ip}:{port}")
            print(f"available device data: {available_devices}")
            # You can also store this in a file or database if needed
    except KeyboardInterrupt:
        print("\nStopped by user.")
    finally:
        sock.close()

if __name__ == "__main__":
    main()
```
## Step 2: Send the command to the device
If you have identified the MAC address of the device to which you wish to send the command, you can use the command JSONs (described above) to send the command to the intended device.
An example implementation in Python is given below:
```plaintext
import json
import socket 

TARGET_IP = "192.168.29.233"
TARGET_PORT = 5600

# JSON command to send command = {
    "led":False
}

# Convert to JSON string and encode to bytes
message = json.dumps(command).encode('utf-8')

# Create UDP socket
sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)

# Send the message
sock.sendto(message, (TARGET_IP, TARGET_PORT))
print(f"Sent JSON command to {TARGET_IP}:{TARGET_PORT}")

# Close the socket
sock.close()
```

## Request

| Where | Name | Required | Value |
| --- | --- | --- | --- |
| Header | `x-api-key` | Yes | Your developer API key. |
| Header | `Authorization` | Yes | `Bearer <access_token>` |
| Header | `Content-Type` | Yes | `application/json` |

```json
{
  "device_id": "6867258b9d78",
  "command": { "power": true, "speed": 4 }
}
```

| Field | Type | Required | Meaning |
| --- | --- | --- | --- |
| `device_id` | string | Yes | A device on your account. `all` is **not** accepted here. |
| `command` | object | Yes | One or more command keys, as a JSON object (not an array or a string). |

Every key in `command` is checked against the device's series before anything
is sent. If one key is invalid, the whole message is rejected and nothing is
applied. The `400` error names the wrong key and lists what that series
accepts.

## Response

```json
{
  "status": "Success",
  "message": "Command sent successfully"
}
```

### Accepted does not mean applied

`200` means the command was checked and sent to the device. It does **not**
mean the device has acted on it yet.

If the device is offline, you get a `503` error and the command is not
delivered. A device can still miss a command if it drops off Wi-Fi at that
moment. To confirm the change, call 'Get Device State' after a second or two
and compare the values.

## Request body

- object
  - `device_id` string, required: From 'Get List of Devices'.
  - `command` object, required: One or more command keys. Water purifiers accept only one key per message.

## Response `200`

OK

- CommandAcceptedResponse
  - `status` string: `Success` on a 2xx, `Error` otherwise.
  - `message` string: Confirms that the command was checked and sent. It does not mean the device has acted on it yet.

## Other responses

- `400`: The request is not valid, or the command is not supported by that device. The message names the wrong key and lists what the device accepts.
- `401`: The API key or token is missing, malformed or expired, or it is the wrong kind of token.
- `403`: Developer Mode is not enabled for this account, or the user does not exist. You also get a 403 when the URL path or HTTP method is wrong.
- `404`: The device is not on your account, or it has not reported any state yet.
- `429`: You have used up your API key's daily quota, or gone over the per-second limit. The daily quota resets at 00:00 UTC.
- `500`: Something failed on our side. Your request was fine. Try again after a short wait.
- `501`: This API does not support the device's series. The message lists the supported series.
- `502`: The Atomberg platform behind this API could not deliver the command or create the PIN. Try again after a short wait.
- `503`: The device is offline, so the command could not be delivered. Try again when the device is back online. 'Get Device State' shows is_online.
- `504`: The request took longer than 29 seconds. A command may still have reached the device, so check 'Get Device State' before you send it again.

## Changes

- **2026-10-06** `30e1ea1bdb73`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/atomberg-iot/apis/atomberg-home-public-apis/changes/send_command/post.md)

---

[API](https://skmtc.dev/atomberg-iot/apis/atomberg-home-public-apis.md) - [All operations](https://skmtc.dev/atomberg-iot/apis/atomberg-home-public-apis/llms.txt) - [OpenAPI document](https://skmtc.dev/atomberg-iot/apis/atomberg-home-public-apis/revisions/35290532bede?raw)
