AtomBerg Fan Sleep API

🔍

Discovery

no device_id

Lists all fans with IDs and names. Use this first to find your device_id.

📊

Query

no speed

Returns the current power + speed of a specific fan. Read-only, no changes made.

⚡

Control

speed set

Send a speed command: off, set 1–6, increment, or decrement. Auto power-on included.

✅

Validate

validate: true

Checks if your api_key and refresh_token are valid. No device interaction.

Value	Behaviour
omit	Query mode — read only
-1	Decrement by 1 — turns off if already at speed 1
0	Turn fan off
1 – 6	Set absolute speed (auto power-on if off)
7	Increment by 1 (starts at 1 if fan is off)

📖 API Reference

Endpoint

        POST
        /api/fan-sleep
      

Field	Type	Required	Description
`api_key`	string	required	Your Atomberg developer API key
`refresh_token`	string	required	Long-lived Atomberg refresh token
`device_id`	string	optional	Target fan MAC. Omit → Discovery mode
`speed`	number	optional	Speed command. Omit → Query mode (read only)
`validate`	boolean	optional	`true` → Check credentials only, no device calls

🔍

Discovery mode — find all your fans

no device_id

Request

{ "api_key": "YOUR_API_KEY", "refresh_token": "YOUR_REFRESH_TOKEN" }

Response

{ "aabbccddeeff": "Living Room Fan", "112233445566": "Bedroom Fan" }

📊

Query mode — read current state

no speed

Request

{ "api_key": "YOUR_API_KEY", "refresh_token": "YOUR_REFRESH_TOKEN", "device_id": "aabbccddeeff" }

Response

{ "status": "query", "power": true, "current_speed": 4, "device_id": "aabbccddeeff", "name": "Living Room Fan" }

⚡

Control mode — send a command

speed provided

Request (set speed 3)

{ "api_key": "YOUR_API_KEY", "refresh_token": "YOUR_REFRESH_TOKEN", "device_id": "aabbccddeeff", "speed": 3 }

Response

{ "status": "success", "action_taken": "speed_set", "power": true, "current_speed": 3, "device_id": "aabbccddeeff", "name": "Living Room Fan" }

✅

Validate mode — check credentials only

validate: true

Request

{ "api_key": "YOUR_API_KEY", "refresh_token": "YOUR_REFRESH_TOKEN", "validate": true }

Response

// Valid credentials: { "status": "valid", "message": "API key and refresh token are valid." } // Invalid / expired: { "status": "invalid", "message": "API key or refresh token is invalid or has expired." }

💡 Getting credentials: Open the Atomberg Home app → Settings → Developer Mode → Enable. This generates your api_key and refresh_token. Quota: 100 calls/day, 5 calls/sec.

AtomBerg Fan Sleep API

Discovery

Query

Control

Validate

⚙️ Speed Values

📖 API Reference

Discovery mode — find all your fans

Query mode — read current state

Control mode — send a command

Validate mode — check credentials only

🧪 Test the API