Awesome

SwitchBot API v1.1

• Introduction
• About the New Version
• Getting Started
• Authentication
  • Open Token and Secret Key
  • How to Sign?
    • Python 2 example code
    • Python 3 example code
    • JavaScript example code
    • C# example code
    • Java 11+ example code
    • PHP example code
• Glossary
• API Usage
  • Host Domain
  • Sending a Request
    • Content-Type
    • Request limit
  • Request Header
  • Standard HTTP Error Codes
• Devices
  • Get device list
    • Description
    • Responses
      • Bot
      • Curtain
      • Curtain 3
      • Hub/Hub Plus/Hub Mini/Hub 2
      • Meter
      • Meter Plus
      • Outdoor Meter
      • Meter Pro
      • Meter Pro CO2
      • Lock
      • Lock Pro
      • Keypad
      • Keypad Touch
      • Remote
      • Motion Sensor
      • Contact Sensor
      • Water Leak Detector
      • Ceiling Light
      • Ceiling Light Pro
      • Plug Mini (US)
      • Plug Mini (JP)
      • Plug
      • Strip Light
      • Color Bulb
      • Robot Vacuum Cleaner S1
      • Robot Vacuum Cleaner S1 Plus
      • Mini Robot Vacuum K10+
      • Mini Robot Vacuum K10+ Pro
      • K10+ Pro Combo
      • Floor Cleaning Robot S10
      • Humidifier
      • Evaporative Humidifier
      • Evaporative Humidifier (Auto-refill)
      • Air Purifier VOC
      • Air Purifier Table VOC
      • Air Purifier PM2.5
      • Air Purifier Table PM2.5
      • Indoor Cam
      • Pan/Tilt Cam
      • Pan/Tilt Cam 2K
      • Blind Tilt
      • Battery Circulator Fan
      • Circulator Fan
      • Roller Shade
      • Relay Switch 1PM
      • Relay Switch 1
      • Virtual infrared remote devices
    • Sample
      • Get all devices
  • Get device status
    • Description
    • Path parameters
    • Responses
      • Bot
      • Curtain
      • Curtain 3
      • Meter
      • Meter Plus
      • Outdoor Meter
      • Meter Pro
      • Meter Pro CO2 Monitor
      • Lock
      • Lock Pro
      • Keypad
      • Keypad Touch
      • Motion Sensor
      • Contact Sensor
      • Water Leak Detector
      • Ceiling Light
      • Ceiling Light Pro
      • Plug Mini (US)
      • Plug Mini (JP)
      • Plug
      • Strip Light
      • Color Bulb
      • Robot Vacuum Cleaner S1
      • Robot Vacuum Cleaner S1 Plus
      • Mini Robot Vacuum K10+
      • Mini Robot Vacuum K10+ Pro
      • K10+ Pro Combo
      • Floor Cleaning Robot S10
      • Humidifier
      • Evaporative Humidifier
      • Evaporative Humidifier (Auto-refill)
      • Air Purifier VOC
      • Air Purifier Table VOC
      • Air Purifier PM2.5
      • Air Purifier Table PM2.5
      • Blind Tilt
      • Hub 2
      • Battery Circulator Fan
      • Circulator Fan
      • Roller Shade
      • Relay Switch 1PM
      • Relay Switch 1
    • Sample
      • SwitchBot Meter example
      • SwitchBot Curtain example
  • Send device control commands
    • Description
    • Command set for physical devices
      • Bot
      • Curtain
      • Curtain 3
      • Lock
      • Lock Pro
      • Humidifier
      • Evaporative Humidifier
      • Evaporative Humidifier (Auto-refill)
      • Air Purifier VOC
      • Air Purifier Table VOC
      • Air Purifier PM2.5
      • Air Purifier Table PM2.5
      • Plug
      • Plug Mini (US)
      • Plug Mini (JP)
      • Color Bulb
      • Strip Light
      • Robot Vacuum Cleaner S1
      • Robot Vacuum Cleaner S1 Plus
      • Mini Robot Vacuum K10+
      • Mini Robot Vacuum K10+ Pro
      • K10+ Pro Combo
      • Floor Cleaning Robot S10
      • Ceiling Light
      • Ceiling Light Pro
      • Keypad
      • Keypad Touch
      • Blind Tilt
      • Battery Circulator Fan
      • Circulator Fan
      • Roller Shade
      • Relay Switch 1PM
      • Relay Switch 1
    • Command set for virtual infrared remote devices
    • Path parameters
    • Request body parameters
    • Response
    • Errors
    • Sample
      • Floor Cleaning Robot S10 example
      • Keypad example
      • Bot example
      • Infrared remote device example
• Scenes
  • Get scene list
    • Description
    • Response
    • Errors
    • Sample
      • Get all scenes
  • Execute manual scenes
    • Description
    • Path parameters
    • Errors
    • Sample
      • Execute a scene
• Webhook
  • Configure webhook
    • Description
    • Request
      • Request body parameters
    • Response
  • Get webhook configuration
    • Description
    • Request
      • Request body parameters
      • queryUrl
      • queryDetails
    • Response
      • queryUrl
      • queryDetails
  • Update webhook configuration
    • Description
    • Request
      • Request body parameters
    • Response
  • Delete webhook
    • Description
    • Request
      • Request body parameters
    • Response
  • Receive events from webhook
    • Bot
    • Curtain
    • Curtain 3
    • Motion Sensor
    • Contact Sensor
    • Water Leak Detector
    • Meter
    • Meter Plus
    • Outdoor Meter
    • Meter Pro
    • Meter Pro CO2 Monitor
    • Lock
    • Lock Pro
    • Indoor Cam
    • Pan/Tilt Cam
    • Color Bulb
    • LED Strip Light
    • Plug Mini (US)
    • Plug Mini (JP)
    • Robot Vacuum Cleaner S1
    • Robot Vacuum Cleaner S1 Plus
    • Mini Robot Vacuum K10+
    • Mini Robot Vacuum K10+ Pro
    • K10+ Pro Combo
    • Floor Cleaning Robot S10
    • Ceiling Light
    • Ceiling Light Pro
    • Keypad
      • Create a passcode
      • Delete a passcode
    • Keypad Touch
      • Create a passcode
      • Delete a passcode
    • Hub 2
    • Battery Circulator Fan
    • Circulator Fan
    • Roller Shade
    • Relay Switch 1PM
    • Relay Switch 1
    • Evaporative Humidifier
    • Evaporative Humidifier (Auto-refill)
    • Air Purifier VOC
    • Air Purifier Table VOC
    • Air Purifier PM2.5
    • Air Purifier Table PM2.5

Introduction

This document describes a collection of SwitchBot API methods, examples, and best practices for, but not limited to, IoT hobbyists, developers, and gurus to make their own smart home programs or applications.

About the New Version

We will stop adding support for new products on v1.0 as we release v1.1.

Hence, we strongly recommend all SwitchBot users to migrate to the new API version because we have improved the authentication method. This will make the communication between your server and the SwitchBot server more secure.

Getting Started

Please follow these steps,

1. Download the SwitchBot app on App Store or Google Play Store

2. Register a SwitchBot account and log in into your account

3. Generate an Open Token within the app For app version ≥ V9.0, a) Go to Profile > Preferences > About b) Tap App Version 10 times. Developer Options will show up c) Tap Developer Options d) Tap Get Token

For app version < V9.0, a) Go to Profile > Preferences b) Tap App Version 10 times. Developer Options will show up c) Tap Developer Options d) Tap Get Token

4. Roll up your sleeves and get your hands dirty with SwitchBot OpenAPI!

Authentication

Open Token and Secret Key

Note: You must update the app to the latest version, V6.14 or later, in order to get the secret key.

In SwitchBot API v1.1, the authentication method has been improved. In order to gain access to private data through the API, you must generate a unique signature using a token and a secret key. When you make a request, the Authorization token and signature will be validated simultaneously.

You as a developer will then be able to add, delete, edit, and look up your data including profile data and data associated with the devices that have been added to your SwitchBot account.

To continue to use SwitchBot API v1.0, refer to the legacy document.

How to Sign?

We have attached some scripts for you to quickly generate a sign. If you prefer to write your own script or routine, here is the procedure.

1. Print the 13 digit timestamp and concatenate it with your token
2. Create a signature using your secret and the string produced in the previous step
3. Convert the signature to upper case

For instance,

# secret key
secret = "" # copy and paste from the SwitchBot app V6.14 or later
# open token
token = "" # copy and paste from the SwitchBot app V6.14 or later
t = 1661927531000
sign = HMAC-SHA256(token + t, secret).toUpperCase()

Python 2 example code

import time
import hashlib
import hmac
import base64

# open token
token = '' # copy and paste from the SwitchBot app V6.14 or later
# secret key
secret = '' # copy and paste from the SwitchBot app V6.14 or later
nonce = ''
t = int(round(time.time() * 1000))
string_to_sign = '{}{}{}'.format(token, t, nonce)

sign = base64.b64encode(hmac.new(secret, msg=string_to_sign, digestmod=hashlib.sha256).digest())
print ('Authorization: {}'.format(token))
print ('t: {}'.format(t))
print ('sign: {}'.format(sign))
print ('nonce: {}'.format(nonce))

Python 3 example code

import json
import time
import hashlib
import hmac
import base64
import uuid

# Declare empty header dictionary
apiHeader = {}
# open token
token = '' # copy and paste from the SwitchBot app V6.14 or later
# secret key
secret = '' # copy and paste from the SwitchBot app V6.14 or later
nonce = uuid.uuid4()
t = int(round(time.time() * 1000))
string_to_sign = '{}{}{}'.format(token, t, nonce)

string_to_sign = bytes(string_to_sign, 'utf-8')
secret = bytes(secret, 'utf-8')

sign = base64.b64encode(hmac.new(secret, msg=string_to_sign, digestmod=hashlib.sha256).digest())
print ('Authorization: {}'.format(token))
print ('t: {}'.format(t))
print ('sign: {}'.format(str(sign, 'utf-8')))
print ('nonce: {}'.format(nonce))

#Build api header JSON
apiHeader['Authorization']=token
apiHeader['Content-Type']='application/json'
apiHeader['charset']='utf8'
apiHeader['t']=str(t)
apiHeader['sign']=str(sign, 'utf-8')
apiHeader['nonce']=str(nonce)

JavaScript example code

const crypto = require('crypto');
const https = require('https');

const token = "yourToken";
const secret = "yourSecret";
const t = Date.now();
const nonce = "requestID";
const data = token + t + nonce;
const sign = crypto
    .createHmac('sha256', secret)
    .update(data)
    .digest('base64');
console.log(sign);

const body = JSON.stringify({
    "command": "turnOn",
    "parameter": "default",
    "commandType": "command"
});
const deviceId = "MAC";
const options = {
    hostname: 'api.switch-bot.com',
    port: 443,
    path: `/v1.1/devices/${deviceId}/commands`,
    method: 'POST',
    headers: {
        "Authorization": token,
        "sign": sign,
        "nonce": nonce,
        "t": t,
        'Content-Type': 'application/json',
        'Content-Length': body.length,
    },
};

const req = https.request(options, res => {
    console.log(`statusCode: ${res.statusCode}`);
    res.on('data', d => {
        process.stdout.write(d);
    });
});

req.on('error', error => {
    console.error(error);
});

req.write(body);
req.end();

C# example code

using System;
using System.Diagnostics;
using System.Text;
using System.Security.Cryptography;
using System.Net.Http;

string token = "My Token";
string secret = "My Secret Key";
DateTime dt1970 = new DateTime(1970, 1, 1);
DateTime current = DateTime.Now;
TimeSpan span = current - dt1970;
long time = Convert.ToInt64(span.TotalMilliseconds);
string nonce = Guid.NewGuid().ToString();
string data = token + time.ToString() + nonce;
Encoding utf8 = Encoding.UTF8;
HMACSHA256 hmac = new HMACSHA256(utf8.GetBytes(secret));
string signature = Convert.ToBase64String(hmac.ComputeHash(utf8.GetBytes(data)));

//Create http client
HttpClient client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Get, @"https://api.switch-bot.com/v1.1/devices");
request.Headers.TryAddWithoutValidation(@"Authorization", token);
request.Headers.TryAddWithoutValidation(@"sign", signature);
request.Headers.TryAddWithoutValidation(@"nonce", nonce);
request.Headers.TryAddWithoutValidation(@"t", time.ToString());

var response = await client.SendAsync(request);

Console.WriteLine(await response.Content.ReadAsStringAsync());

Java 11+ example code

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.http.HttpResponse.BodyHandlers;
import java.time.Instant;
import java.util.Base64;
import java.util.UUID;

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

public class Main {
    public static void main(String[] args) throws Exception {
    	
      String token = args[0];
      String secret = args[1];
      String nonce = UUID.randomUUID().toString();
      String time= "" + Instant.now().toEpochMilli();
      String data = token + time + nonce;
      
      SecretKeySpec secretKeySpec = new SecretKeySpec(secret.getBytes("UTF-8"), "HmacSHA256");
      Mac mac = Mac.getInstance("HmacSHA256");
      mac.init(secretKeySpec);
      String signature = new String(Base64.getEncoder().encode(mac.doFinal(data.getBytes("UTF-8"))));      
      
      HttpRequest getDevices = HttpRequest.newBuilder()
      .uri(new URI("https://api.switch-bot.com/v1.1/devices"))
      .header("Authorization", token)
      .header("sign", signature)
      .header("nonce", nonce)
      .header("t", time)
      .GET()
      .build();
      
      HttpResponse<String> response = HttpClient.newBuilder().build().send(getDevices, BodyHandlers.ofString());
      
      System.out.println(response.body());
    }
}

PHP example code

<?php
$token = 'XXXXXXXXXXXXXXXXXXX';
$secret = 'YYYYYYYYYYY';
$nonce = guidv4();
$t = time() * 1000;
$data = utf8_encode($token . $t . $nonce);
$sign = hash_hmac('sha256', $data, $secret,true);
$sign = strtoupper(base64_encode($sign));

$url = "https://api.switch-bot.com/v1.1/devices";

$curl = curl_init($url);
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);

$headers = array(
    "Content-Type:application/json",
    "Authorization:" . $token,
    "sign:" . $sign,
    "nonce:" . $nonce,
    "t:" . $t
);

curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($curl);
curl_close($curl);

function guidv4($data = null) {
    // Generate 16 bytes (128 bits) of random data or use the data passed into the function.
    $data = $data ?? random_bytes(16);
    assert(strlen($data) == 16);
    $data[6] = chr(ord($data[6]) & 0x0f | 0x40);
    $data[8] = chr(ord($data[8]) & 0x3f | 0x80);

    // Output the 36 character UUID.
    return vsprintf('%s%s-%s-%s-%s-%s%s%s', str_split(bin2hex($data), 4));
}

Swift example code

import CryptoKit 

let token = 'TTTTTTT'
let secret = 'SSSS'

func getDevices() async throws -> Any {
    let hostname = "https://api.switch-bot.com"
    
    var components = URLComponents(string: hostname)!
    components.path = "/v1.1/devices"
    components.port = 443
    
    var request = URLRequest(url: components.url!)
    
    request.setValue("application/json", forHTTPHeaderField: "Content-Type")
    request.setValue("utf-8", forHTTPHeaderField: "charset")
    let timestamp = Int(Date().timeIntervalSince1970.rounded() * 1000) // Date().timeInterval returns seconds, not milliseconds, since1970
    let nonce =  UUID().uuidString
    
    let timeAdjustedToken = token + "\(timestamp)" + nonce
    let key = SymmetricKey(data: Data(secret.utf8))
    let authenticationCode = HMAC<SHA256>.authenticationCode(for: Data(timeAdjustedToken.utf8), using: key)
    let signatureToken = Data(authenticationCode).base64EncodedString()

    request.setValue(token, forHTTPHeaderField: "Authorization")
    request.setValue(signatureToken, forHTTPHeaderField: "sign")
    request.setValue(nonce, forHTTPHeaderField: "nonce")
    request.setValue("\(timestamp)", forHTTPHeaderField: "t")
    
    let (data, response) = try await URLSession.shared.data(for: request)
    return try JSONSerialization.jsonObject(with: data)
}

Glossary

The following table provides definitions to the terms to be frequently mentioned in the subsequent sections.

Legacy Cloud Services

Important note: Beyond V9.0, there will NOT be a Cloud Services option in the app. You will see Third-party Services instead. Please read this article for more information, https://support.switch-bot.com/hc/en-us/articles/7257579858455

A SwitchBot app feature, which appears in the app <V9.0 that

1. Enables SwitchBot products to be discovered and communicated with third-party services such as Home Assistant, Alexa, Google Home, IFTTT, SmartThings, and so forth
2. Allows users to create customized smart scenes and widgets. For BLE-based devices such as Bot and Curtain
3. You MUST first add a SwitchBot Hub such as Hub 2, Hub Mini with Matter Enabled, or Hub Mini
4. Then enable Cloud Services on the Settings page in order to make use of the web API!

API Usage

Host Domain

https://api.switch-bot.com

Sending a Request

The following request types are supported,

• GET
• PUT
• POST
• DELETE

Content-Type

For POST requests, use application/json; charset=utf8 as the Content-Type

Request limit

The amount of API calls per day is limited to 10000 times. Going over that limit will return "Unauthorized."

Request Header

The following parameters need to be included into the header,

Standard HTTP Error Codes

The following table lists the most common HTTP error response,

Devices

The devices API is used to access the properties and states of SwitchBot devices and to send control commands to those devices.

Get device list

GET /v1.1/devices

Description

Get a list of devices, which include physical devices and virtual infrared remote devices that have been added to the current user's account.

Note: For devices that communicate via BLE, please enable Cloud Services on SwitchBot app first.

Physical devices refer to the following SwitchBot products,

• Hub
• Hub Plus
• Hub Mini
• Bot
• Curtain
• Plug
• Meter
• Motion Sensor
• Contact Sensor
• Color Bulb
• Humidifier
• Smart Fan
• Strip Light
• Plug Mini (US)
• Plug Mini (JP)
• Lock
• Meter Plus (JP)
• Meter Plus (US)
• Robot Vacuum Cleaner S1
• Robot Vacuum Cleaner S1 Plus
• Keypad
• Keypad Touch
• Ceiling Light
• Ceiling Light Pro
• Blind Tilt
• Hub 2
• Outdoor Meter
• Battery Circulator Fan
• Curtain 3
• Lock Pro
• Floor Cleaning Robot S10
• Water Leak Detector
• Mini Robot Vacuum K10+
• Mini Robot Vacuum K10+ Pro
• new Meter Pro
• new Meter Pro CO2
• new Circulator Fan
• new Evaporative Humidifier
• new Evaporative Humidifier (Auto-refill)
• new K10+ Pro Combo
• new Air Purifier VOC
• new Air Purifier Table VOC
• new Air Purifier PM2.5
• new Air Purifier Table PM2.5
• new Roller Shade
• new Relay Switch 1PM
• new Relay Switch 1

Virtual infrared remote devices refer to virtual devices that are used to simulate infrared signals of a home appliance remote control. A SwitchBot Hub Plus, Hub Mini, Hub 2, or Ceiling Light is required in order to be able to create these virtual devices within the app. The types of appliances supported include,

• Air Conditioner
• TV
• Light
• Streamer
• Set Top Box
• DVD Player
• Fan
• Projector
• Camera
• Air Purifier
• Speaker
• Water Heater
• Robot Vacuum Cleaner
• Others

Responses

The response is basically a JSON object, which contains the following properties,

The body object contains the following properties,

The response may contain the following codes and messages,

The deviceList array contains a list of objects with the following key-value attributes,

Bot

Curtain

Curtain 3

Hub/Hub Plus/Hub Mini/Hub 2

Meter

Meter Plus

Outdoor Meter

Meter Pro

Meter Pro CO2

Lock

Lock Pro

Keypad

keyList maintains a list of passcodes,

Keypad Touch

keyList maintains a list of passcodes,

Remote

Motion Sensor

Contact Sensor

Water Leak Detector

Ceiling Light

Ceiling Light Pro

Plug Mini (US)

Plug Mini (JP)

Plug

Strip Light

Color Bulb

Robot Vacuum Cleaner S1

Robot Vacuum Cleaner S1 Plus

Mini Robot Vacuum K10+

Mini Robot Vacuum K10+ Pro

K10+ Pro Combo

Floor Cleaning Robot S10

Humidifier

Evaporative Humidifier

Evaporative Humidifier (Auto-refill)

Air Purifier VOC

Air Purifier Table VOC

Air Purifier PM2.5

Air Purifier Table PM2.5

Indoor Cam

Pan/Tilt Cam

Pan/Tilt Cam 2K

Blind Tilt

Battery Circulator Fan

Circulator Fan

Roller Shade

Relay Switch 1PM

Relay Switch 1

Virtual infrared remote devices

The infraredRemoteList array contains a list of objects with the following key-value attributes,

Sample

Get all devices

Request

GET https://api.switch-bot.com/v1.1/devices

Response

{
    "statusCode": 100,
    "body": {
        "deviceList": [
            {
                "deviceId": "500291B269BE",
                "deviceName": "Living Room Humidifier",
                "deviceType": "Humidifier",
                "enableCloudService": true,
                "hubDeviceId": "000000000000"
            }
        ],
        "infraredRemoteList": [
            {
                "deviceId": "02-202008110034-13",
                "deviceName": "Living Room TV",
                "remoteType": "TV",
                "hubDeviceId": "FA7310762361"
            }
        ]
    },
    "message": "success"
}

Get device status

GET /v1.1/devices/{deviceId}/status

Description

Get the status of a physical device that has been added to the current user's account.

Physical devices refer to the following SwitchBot products,

• Bot
• Plug
• Curtain
• Meter
• Motion Sensor
• Contact Sensor
• Color Bulb
• Humidifier
• Smart Fan
• Strip Light
• Plug Mini (US)
• Plug Mini (JP)
• Lock
• Meter Plus (JP)
• Meter Plus (US)
• Robot Vacuum Cleaner S1
• Robot Vacuum Cleaner S1 Plus
• Keypad (MUST enable Cloud Service first)
• Keypad Touch (MUST enable Cloud Service first)
• Ceiling Light
• Ceiling Light Pro
• Hub 2
• Outdoor Meter
• Battery Circulator Fan
• Lock Pro
• Floor Cleaning Robot S10
• Water Leak Detector
• Mini Robot Vacuum K10+
• Mini Robot Vacuum K10+ Pro
• new Meter Pro
• new Meter Pro CO2
• new Circulator Fan
• new Evaporative Humidifier
• new Evaporative Humidifier (Auto-refill)
• new K10+ Pro Combo
• new Air Purifier VOC
• new Air Purifier Table VOC
• new Air Purifier PM2.5
• new Air Purifier Table PM2.5
• new Roller Shade
• new Relay Switch 1PM
• new Relay Switch 1

Path parameters

Responses

The response is basically a JSON object, which contains the following properties,

The reponses may contain the following codes and message,

The body object contains the following properties,

Bot

Curtain

Curtain 3

Meter

Meter Plus

Outdoor Meter

Meter Pro

Meter Pro CO2

Lock

Lock Pro

Keypad

Keypad Touch

Motion Sensor

Contact Sensor

Water Leak Detector

Ceiling Light

Ceiling Light Pro

Plug Mini (US)

Plug Mini (JP)

Plug

Strip Light

Color Bulb

Robot Vacuum Cleaner S1

Robot Vacuum Cleaner S1 Plus

Mini Robot Vacuum K10+

Mini Robot Vacuum K10+ Pro

K10+ Pro Combo

Floor Cleaning Robot S10

Humidifier

Evaporative Humidifier

Evaporative Humidifier (Auto-refill)

Air Purifier VOC

Air Purifier Table VOC

Air Purifier PM2.5

Air Purifier Table PM2.5

Blind Tilt

Roller Shade

Hub 2

Battery Circulator Fan

Circulator Fan

Relay Switch 1PM

Relay Switch 1

Sample

SwitchBot Meter example

Request the status of a SwitchBot Thermometer and Hygrometer

Request

GET https://api.switch-bot.com/v1.1/devices/C271111EC0AB/status

Response

{
    "statusCode": 100,
    "body": {
        "deviceId": "C271111EC0AB",
        "deviceType": "Meter",
        "hubDeviceId": "FA7310762361",
        "humidity": 52,
        "temperature": 26.1
    },
    "message": "success"
}

SwitchBot Curtain example

Request the status of a SwitchBot Curtain

Request

GET https://api.switch-bot.com/v1.1/devices/E2F6032048AB/status

Response

{
    "statusCode": 100,
    "body": {
        "deviceId": "E2F6032048AB",
        "deviceType": "Curtain",
        "hubDeviceId": "FA7310762361",
        "calibrate": true,
        "group": false,
        "moving": false,
        "slidePosition": 0
    },
    "message": "success"
}

Send device control commands

POST /v1.1/devices/{deviceId}/commands

Description

Send control commands to physical devices and virtual infrared remote devices.

Command set for physical devices

Bot

Curtain

Curtain 3

Lock

Lock Pro

Humidifier

Evaporative Humidifier

Evaporative Humidifier (Auto-refill)

Air Purifier VOC

Air Purifier Table VOC

Air Purifier PM2.5

Air Purifier Table PM2.5

Plug

Plug Mini (US)

Plug Mini (JP)

Relay Switch 1PM

Relay Switch 1

Color Bulb

Strip Light

Robot Vacuum Cleaner S1

Robot Vacuum Cleaner S1 Plus

Mini Robot Vacuum K10+

Mini Robot Vacuum K10+ Pro

K10+ Pro Combo

Floor Cleaning Robot S10

Ceiling Light

Ceiling Light Pro

Keypad

The control commands for this product work differently than the other products. Due to security concerns, the passcodes are stored locally. This mechanism dramatically prolongs the time needed to successfully create a passcode and get the correct result through the Web API. Hence, the actual results of the following commands are returned from the SwitchBot server asynchronously and are delivered through a webhook.

You need to configure a webhook to receive the correct result. Refer to this product's webhook definition.

The following table describes the parameter object for createKey,

The following table describes the parameter object for deleteKey,

Keypad Touch

The control commands for this product work differently than the other products. Due to security concerns, the passcodes are stored locally. This mechanism dramatically prolongs the time needed to successfully create a passcode and get the correct result through the Web API. Hence, the actual results of the following commands are returned from the SwitchBot server asynchronously and are delivered through a webhook.

You need to configure a webhook to receive the correct result. Refer to this product's webhook definition.

The following table describes the parameter object for createKey,

The following table describes the parameter object for deleteKey,

Blind Tilt

Roller Shade

Battery Circulator Fan

Circulator Fan

Command set for virtual infrared remote devices

The table below describes all the available commands for virtual infrared remote devices,

Note: Most of the devices support turnOn or turnOff, which are case-sensitive. For infrared remote devices, when you have created customized buttons, you must set commandType to customize, otherwise the command will not work. command needs to be set to the name of the customized button.

Path parameters

Request body parameters

Response

The response is basically a JSON object, which contains the following properties,

Errors

Sample

Floor Cleaning Robot S10 example

Clean with vacuum mode

Request

POST https://api.switch-bot.com/v1.1/devices/F7538E1ABC23/commands

{
    "commandType": "command",
    "command": "startClean", // start cleaning
    "parameter": {
        "action": "sweep", // clean with vacuum mode
        "param": {
            "fanLevel": 1, // vacuum level set to 1
            "waterLevel": 1, // mop moisture level set to 1
            "times": 1 // number of cyclyes to clean set to 1
        }
    }
}

Response

{
    "statusCode": 100,
    "body": {
        "commandId": "CMD166444044923602"
    },
    "message": "success"
}

Change the cleaning settings

Request

POST https://api.switch-bot.com/v1.1/devices/F7538E1ABC23/commands

{
    "commandType": "command",
    "command": "changeParam",
    "parameter": {
      	"fanLevel": 2, // vacuum level set to 1
        "waterLevel": 1, // mop moisture level set to 1
        "times": 1 // number of times to clean set to 2
    }
}

Response

{
    "statusCode": 100,
    "body": {
        "commandId": "CMD166444044923602"
    },
    "message": "success"
}

Keypad example

Create a temporary passcode

Request

POST https://api.switch-bot.com/v1.1/devices/F7538E1ABCEB/commands

{
    "commandType": "command",
    "command": "createKey",
    "parameter": {
        "name": "Guest Code",
        "type": "timeLimit",
        "password": "12345678",
        "startTime": 1664640056,
        "endTime": 1665331432
    }
}

Response

{
    "statusCode": 100,
    "body": {
        "commandId": "CMD166444044923602"
    },
    "message": "success"
}

Bot example

Turn a Bot on

Request

POST https://api.switch-bot.com/v1.1/devices/210/commands

{
    "command": "turnOn",
    "parameter": "default",
    "commandType": "command"
}

Response

{
    "statusCode": 100,
    "body": {},
    "message": "success"
}

Set the color value of a Color Bulb Request

POST https://api.switch-bot.com/v1.1/devices/84F70353A411/commands

{
    "command": "setColor",
    "parameter": "122:80:20", // yellow
    "commandType": "command"
}

Response

{
    "statusCode": 100,
    "body": {},
    "message": "success"
}

Infrared remote device example

Set an Air Conditioner

Request

POST https://api.switch-bot.com/v1.1/devices/02-202007201626-70/commands

{
    "command": "setAll",
    "parameter": "26,1,3,on",
    "commandType": "command"
}

Response

{
    "statusCode": 100,
    "body": {},
    "message": "success"
}

Trigger a customized button

Request

POST https://api.switch-bot.com/v1.1/devices/02-202007201626-10/commands

{
    "command": "ボタン", // the name of the customized button
    "parameter": "default",
    "commandType": "customize"
}

Response

{
    "statusCode": 100,
    "body": {},
    "message": "success"
}

Scenes

The scenes API is used to access the smart scenes created by a user and to execute manual scenes.

Get scene list

GET /v1.1/scenes

Description

Get a list of manual scenes created by the current user.

Response

The response is basically a JSON object, which contains the following properties,

The body object contains a list of objects, which has the following properties,

Errors

Sample

Get all scenes

Request

GET https://api.switch-bot.com/v1.1/scenes

Response

{
    "statusCode": 100,
    "body": [
        {
            "sceneId": "T02-20200804130110",
            "sceneName": "Close Office Devices"
        },
        {
            "sceneId": "T02-202009221414-48924101",
            "sceneName": "Set Office AC to 25"
        },
        {
            "sceneId": "T02-202011051830-39363561",
            "sceneName": "Set Bedroom to 24"
        },
        {
            "sceneId": "T02-202011051831-82928991",
            "sceneName": "Turn off home devices"
        },
        {
            "sceneId": "T02-202011062059-26364981",
            "sceneName": "Set Bedroom to 26 degree"
        }
    ],
    "message": "success"
}

Execute manual scenes

POST /v1.1/scenes/{sceneId}/execute

Description

Sends a request to execute a manual scene.

Path parameters

The response is basically a JSON object, which contains the following properties,

Errors

Sample

Execute a scene

Request

POST https://api.switch-bot.com/v1.1/scenes/T02-202009221414-48924101/execute

Response

{
    "statusCode": 100,
    "body": {},
    "message": "success"
}

Webhook

Configure webhook

Description

Configure the url that all the webhook events will be sent to

Request

POST https://api.switch-bot.com/v1.1/webhook/setupWebhook

Request body parameters

Head

{
    "Content-type":"application/json",
    "Authorization":your_token // enter your API token
}

Body

{
    "action":"setupWebhook",
    "url":url1, // enter your url
    "deviceList":"ALL"
}

Response

Sample

{
    "statusCode": 100,
    "body": {},
    "message": ""
}

Get webhook configuration

Description

Get the current configuration info of the webhook

Request

POST https://api.switch-bot.com/v1.1/webhook/queryWebhook

Request body parameters

queryUrl

Head

{
    "Content-type":"application/json",
    "Authorization":your_token // enter your API token
}

Body

{
    "action": "queryUrl"
}

queryDetails

Head

{
    "Content-type":"application/json",
    "Authorization":your_token // enter your API token
}

Body

{
    "action": "queryDetails",
    "urls":[url1] // get infos of a url
}

Response

queryUrl

{
    "statusCode": 100,
    "body": {
        "urls": [url1] // the target url
    },
    "message": ""
}

queryDetails

{
    "statusCode": 100,
    "body": [
        {
            "url":url1,
            "createTime":123456,
            "lastUpdateTime":123456,
            "deviceList": "ALL",
            "enable":true
        }
    ],
    "message": ""
}

Update webhook configuration

Description

Update the configuration of the webhook

Request

POST https://api.switch-bot.com/v1.1/webhook/updateWebhook

Request body parameters

Head

{
    "Content-type":"application/json",
    "Authorization":your_token // enter your API token
}

Body

{
    "action": "updateWebhook",
    "config":{
        "url":url1,
        "enable":true
    }
}

Response

{
    "statusCode": 100,
    "body": {},
    "message": ""
}

Delete webhook

Description

Delete the configuration of the webhook

Request

POST https://api.switch-bot.com/v1.1/webhook/deleteWebhook

Request body parameters

Head

{
    "Content-type":"application/json",
    "Authorization":your_token // enter your API token
}

Body

{
    "action": "deleteWebhook",
    "url":url1
}

Response

{
    "statusCode": 100,
    "body": {},
    "message": ""
}

Receive events from webhook

When an event gets triggered, SwitchBot server will send a POST request to the url you have configured. Refer to the table below for a list of products that support webhook.

Bot

{
    "eventType": "changeReport",
    "eventVersion": "1",
    "context": {
        "deviceType": "WoHand",
        "deviceMac": DEVICE_MAC_ADDR,
        "power": "on",//"on"or"off"
        "battery": 10,
        "deviceMode": "pressMode",//pressMode,switchMode,customizeMode
        "timeOfSample": 123456789
    }
}

Curtain

{
    "eventType": "changeReport",
    "eventVersion": "1",
    "context": {
        "deviceType": "WoCurtain",
        "deviceMac": DEVICE_MAC_ADDR,
        "calibrate":false,
        "group":false,
        "slidePosition":50, //0~100
        "battery":100,
        "timeOfSample": 123456789
    }
}

Curtain 3

{
    "eventType": "changeReport",
    "eventVersion": "1",
    "context": {
        "deviceType": "WoCurtain3",
        "deviceMac": DEVICE_MAC_ADDR,
        "calibrate":false,
        "group":false,
        "slidePosition":50, //0~100
        "battery":100,
        "timeOfSample": 123456789
    }
}

Motion Sensor

{
    "eventType": "changeReport",
    "eventVersion": "1",
    "context": {
        "deviceType": "WoPresence",
        "deviceMac": DEVICE_MAC_ADDR,
        "detectionState": "NOT_DETECTED",
        "battery":100,
        "timeOfSample": 123456789
    }
}

Contact Sensor

{
    "eventType": "changeReport",
    "eventVersion": "1",
    "context": {
        "deviceType": "WoContact",
        "deviceMac": DEVICE_MAC_ADDR,
        "detectionState": "NOT_DETECTED",
        "doorMode":"OUT_DOOR",
        "brightness": "dim",
        "openState": "open",
        "battery":100,
        "timeOfSample": 123456789
    }
}

Water Leak Detector

{
    "eventType": "changeReport",
    "eventVersion": "1",
    "context": {
        "deviceType": "Water Detector",
        "deviceMac": DEVICE_MAC_ADDR,
        "detectionState": 0,
        "battery":100,
        "timeOfSample": 123456789
    }
}

Meter

{
    "eventType": "changeReport",
    "eventVersion": "1",
    "context": {
        "deviceType": "WoMeter",
        "deviceMac": DEVICE_MAC_ADDR,
        "temperature": 22.5,
        "scale": "CELSIUS",
        "humidity": 31,
        "battery":100,
        "timeOfSample": 123456789
    }
}

Meter Plus

{
    "eventType": "changeReport",
    "eventVersion": "1",
    "context": {
        "deviceType": "WoMeter",
        "deviceMac": DEVICE_MAC_ADDR,
        "temperature": 22.5,
        "scale": "CELSIUS",
        "humidity": 31,
        "battery":100,
        "timeOfSample": 123456789
    }
}

Outdoor Meter

{
    "eventType": "changeReport",
    "eventVersion": "1",
    "context": {
        "deviceType": "WoIOSensor",
        "deviceMac": DEVICE_MAC_ADDR,
        "temperature": 22.5,
        "scale": "CELSIUS",
        "humidity": 31,
        "battery":100,
        "timeOfSample": 123456789
    }
}

Meter Pro

{
    "eventType": "changeReport",
    "eventVersion": "1",
    "context": {
        "deviceType": "MeterPro",
        "deviceMac": DEVICE_MAC_ADDR,
        "temperature": 22.5,
        "scale": "CELSIUS",
        "humidity": 31,
        "battery":100,
        "timeOfSample": 123456789
    }
}

Meter Pro CO2

{
    "eventType": "changeReport",
    "eventVersion": "1",
    "context": {
        "deviceType": "MeterPro(CO2)",
        "deviceMac": DEVICE_MAC_ADDR,
        "temperature": 22.5,
        "scale": "CELSIUS",
        "humidity": 31,
        "CO2": 1203,
        "battery":100,
        "timeOfSample": 123456789
    }
}

Lock

{
    "eventType": "changeReport",
    "eventVersion": "1",
    "context": {
        "deviceType": "WoLock",
        "deviceMac": DEVICE_MAC_ADDR,
        "lockState": "LOCKED",
        "battery":100,
        "timeOfSample": 123456789
    }
}

Lock Pro

{
    "eventType": "changeReport",
    "eventVersion": "1",
    "context": {
        "deviceType": "WoLockPro",
        "deviceMac": DEVICE_MAC_ADDR,
        "lockState": "LOCKED",
        "battery":100,
        "timeOfSample": 123456789
    }
}

Indoor Cam

{
    "eventType": "changeReport",
    "eventVersion": "1",
    "context": {
        "deviceType": "WoCamera",
        "deviceMac": DEVICE_MAC_ADDR,
        "detectionState": "DETECTED",
        "timeOfSample": 123456789
    }
}

Pan/Tilt Cam

{
    "eventType": "changeReport",
    "eventVersion": "1",
    "context": {
        "deviceType": "WoPanTiltCam",
        "deviceMac": DEVICE_MAC_ADDR,
        "detectionState": "DETECTED",
        "timeOfSample": 123456789
    }
}

Color Bulb

{
    "eventType": "changeReport",
    "eventVersion": "1",
    "context": {
        "deviceType": "WoBulb",
        "deviceMac": DEVICE_MAC_ADDR,
        "powerState": "ON",
        "brightness": 10,
        "color":"255:245:235",
        "colorTemperature":3500,
        "timeOfSample": 123456789
    }
}

LED Strip Light

{
    "eventType": "changeReport",
    "eventVersion": "1",
    "context": {
        "deviceType": "WoStrip",
        "deviceMac": DEVICE_MAC_ADDR,
        "powerState": "ON",
        "brightness": 10,
        "color": "255:245:235",
        "timeOfSample": 123456789
    }
}

Plug Mini (US)

{
    "eventType": "changeReport",
    "eventVersion": "1",
    "context": {
        "deviceType": "WoPlugUS",
        "deviceMac": DEVICE_MAC_ADDR,
        "powerState": "ON",
        "timeOfSample": 123456789
    }
}

Plug Mini (JP)

{
    "eventType": "changeReport",
    "eventVersion": "1",
    "context": {
        "deviceType": "WoPlugJP",
        "deviceMac": DEVICE_MAC_ADDR,
        "powerState": "ON",
        "timeOfSample": 123456789
    }
}

Robot Vacuum Cleaner S1

{
    "eventType": "changeReport",
    "eventVersion": "1",
    "context": {
        "deviceType": "WoSweeper",
        "deviceMac": DEVICE_MAC_ADDR,
        "workingStatus"："StandBy",
        "onlineStatus": "online",
        "battery": 100,
        "timeOfSample": 123456789
    }
}

Robot Vacuum Cleaner S1 Plus

{
    "eventType": "changeReport",
    "eventVersion": "1",
    "context": {
        "deviceType": "WoSweeperPlus",
        "deviceMac": DEVICE_MAC_ADDR,
        "workingStatus"："StandBy",
        "onlineStatus": "online",
        "battery": 100,
        "timeOfSample": 123456789
    }
}

Mini Robot Vacuum K10+

{
    "eventType": "changeReport",
    "eventVersion": "1",
    "context": {
        "deviceType": "WoSweeperMini",
        "deviceMac": DEVICE_MAC_ADDR,
        "workingStatus"："StandBy",
        "onlineStatus": "online",
        "battery": 100,
        "timeOfSample": 123456789
    }
}

Mini Robot Vacuum K10+ Pro

{
    "eventType": "changeReport",
    "eventVersion": "1",
    "context": {
        "deviceType": "WoSweeperMiniPro",
        "deviceMac": DEVICE_MAC_ADDR,
        "workingStatus"："StandBy",
        "onlineStatus": "online",
        "battery": 100,
        "timeOfSample": 123456789
    }
}

K10+ Pro Combo

{
    "eventType": "changeReport",
    "eventVersion": "1",
    "context": {
        "deviceType": "Robot Vacuum Cleaner K10+ Pro Combo",
        "deviceMac": DEVICE_MAC_ADDR,
        "workingStatus"："StandBy",
        "onlineStatus": "online",
        "battery": 100,
        "taskType": "explore",
        "timeOfSample": 123456789
    }
}

Floor Cleaning Robot S10