Skip to content

OpenWonderLabs/SwitchBotAPI

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

123 Commits
.github/workflows
.github/workflows
 
 
devices
devices
 
 
.gitignore
.gitignore
 
 
README-v1.0.md
README-v1.0.md
 
 
README.md
README.md
 
 

Repository files navigation

SwitchBot API v1.1

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.

Note: This API is limited to personal uses. It is prohibited for commercial uses or for large-scale applications. There is a daily call limit to all users to ensure resources are evenly distributed to each API user. For commercial uses, please do consult SwitchBot via this form.

日本でご利用の皆さまへ: 弊社はAPIインターフェイスを通じて、より柔軟でパーソナルな利用体験を提供できることを願っております。 すべてのユーザーの皆様の公平な利用とサービス品質を保証するため、APIの利用範囲についてご説明いたします。 ①個人ユーザーの利用 弊社は、個人のプロジェクト、学習研究、および日常生活におけるクリエイティブなシーンでのAPI利用を歓迎し、奨励いたします。 これらの目的で利用する場合は追加の申請なしにAPIを自由に呼び出すことができます。 ➁商用利用 SwitchBot APIを商業製品やサービスに統合する予定がある場合、または大規模な呼び出し（例：数千回以上のリクエスト）を行う場合は、まず弊社にご連絡ください、別途EnterpriseAPIをご用意しております。 • 貴社の製品/サービスの動作がより安定します。 • 専門的な技術サポートと割り当ての保証を提供できます。 • 貴社の利用が弊社のサービス利用規約およびブランドガイドラインに準拠していることを確認できます。 お問い合わせ方法 商用利用に関するご要望やご質問がございましたら、いつでもお気軽にお問い合わせください。 📧 メール：biz@switchbot.jp

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

  1. 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)
}

Go example code

package main

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/base64"
    "fmt"
    "io"
    "log"
    "net/http"
    "strings"
    "time"
)

func main() {
    token := "XXXXXXXXXXXXXXXXXXX"      // copy and paste from the SwitchBot app V6.14 or later
    secret := "YYYYYYYYYYY"             // copy and paste from the SwitchBot app V6.14 or later
    nonce := UUID()                     // generate random UUID v4
    timestamp := time.Now().UnixMilli() // 13-digit milliseconds Unix timestamp

    data := fmt.Sprintf("%s%d%s", token, timestamp, nonce)

    mac := hmac.New(sha256.New, []byte(secret))
    if _, err := mac.Write([]byte(data)); err != nil {
        log.Fatalf("Error generating signature: %v", err)
    }

    signature := mac.Sum(nil)
    signatureB64 := strings.ToUpper(base64.StdEncoding.EncodeToString(signature))

    url := "https://api.switch-bot.com/v1.1/devices"
    req, err := http.NewRequest("GET", url, nil)
    if err != nil {
        log.Fatalf("Error creating request: %v", err)
    }

    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("Authorization", token)
    req.Header.Set("sign", signatureB64)
    req.Header.Set("nonce", nonce)
    req.Header.Set("t", fmt.Sprintf("%d", timestamp))

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        log.Fatalf("Error sending request: %v", err)
    }
    defer resp.Body.Close()

    body, err := io.ReadAll(resp.Body)
    if err != nil {
        log.Fatalf("Error reading response: %v", err)
    }

    fmt.Println(string(body)) // Response in JSON format
}

// UUID returns an RFC 4122/9562–compliant random UUIDv4 string.
func UUID() string {
    var uuid [16]byte                 // 128-bit long array
    rand.Read(uuid[:])                // Use cryptographically secure random source
    uuid[6] = (uuid[6] & 0x0F) | 0x40 // Version (UUIDv4 = 0100)
    uuid[8] = (uuid[8] & 0x3F) | 0x80 // Variant (RFC9562 / RFC4122 = 10xxxxxx)

    return fmt.Sprintf("%08x-%04x-%04x-%04x-%012x",
        uuid[0:4],  // 4 bytes
        uuid[4:6],  // 2 bytes
        uuid[6:8],  // 2 bytes (version included)
        uuid[8:10], // 2 bytes (variant included)
        uuid[10:])  // 6 bytes
}

Glossary

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

Term Description Model No. Availability
Hub Mini Short for SwitchBot Hub Mini W0202200
Hub Plus Short for SwitchBot Hub Plus SwitchBot Hub S1
Hub 2 Short for SwitchBot Hub 2 W3202100
Hub 3 Short for SwitchBot Hub 3 W7202100
Bot Short for SwitchBot Bot SwitchBot S1
Curtain Short for SwitchBot Curtain W0701600
Curtain 3 Short for SwitchBot Curtain 3 W2400000
Plug Short for SwitchBot Plug SP11 Currently only available in Japan
Meter Short for SwitchBot Thermometer and Hygrometer SwitchBot MeterTH S1
Meter Plus (JP) Short for SwitchBot Thermometer and Hygrometer Plus (JP). W2201500 Only available in Japan
Meter Plus (US) Short for SwitchBot Thermometer and Hygrometer Plus (US) W2301500 Only available in US
Outdoor Meter Short for Indoor/Outdoor Thermo-Hygrometer W3400010
Weather Station Short for SwitchBot Weather Station W3400010
Meter Pro Short for SwitchBot Meter Pro W4900000
Meter Pro (CO2 Monitor) Short for SwitchBot Meter Pro (CO2 Monitor) W4900010
Motion Sensor Short for SwitchBot Motion Sensor W1101500
Contact Sensor Short for SwitchBot Contact Sensor W1201500
Prensence Sensor Short for SwitchBot Prensence Sensor W8200000
Water Leak Detector Short for SwitchBot Water Leak Detector W4402000
Color Bulb Short for SwitchBot Color Bulb W1401400
Strip Light Short for SwitchBot LED Strip Light W1701100
Plug Mini (US) Short for SwitchBot Plug Mini (US) W1901400 and W1901401 Only available in US
Plug Mini (JP) Short for SwitchBot Plug Mini (JP) W2001400 and W2001401 Only available in Japan
Plug Mini (EU) Short for SwitchBot Plug Mini (EU) W7732300 Only available in Europe
Lock Short for SwitchBot Lock W1601700
Lock Pro Short for SwitchBot Lock Pro W3500000
Lock Pro Matter Enabled Short for SwitchBot Lock Pro Matter Enabled W8102000
Lock Vision Short for SwitchBot Lock Vision W1141000
Lock Vision Pro Short for SwitchBot Lock Vision Pro W1141001
Keypad Short for SwitchBot Lock W2500010
Keypad Touch Short for SwitchBot Lock W2500020
S1 Short for SwitchBot Robot Vacuum Cleaner S1 W3011000
S1 Plus Short for SwitchBot Robot Vacuum Cleaner S1 Plus W3011010
K10+ Short for SwitchBot Mini Robot Vacuum K10+ W3011020
K10+ Pro Short for SwitchBot Mini Robot Vacuum K10+ Pro W3011026
S10 Short for SwitchBot Floor Cleaning Robot S10 W3211800
S20 Short for SwitchBot Floor Cleaning Robot S20 W6602310
K10+ Pro Combo Short for SwitchBot Robot Vacuum K10+ Pro Combo W3002500
K20+ Pro Short for SwitchBot Multitasking Household Robot K20+ Pro W3002520
K11+ Short for Robot Vacuum K11+ W3003100
Ceiling Light Short for SwitchBot Ceiling Light W2612230 and W2612240 Currently only available in Japan
Ceiling Light Pro Short for SwitchBot Ceiling Light Pro W2612210 and W2612220 Currently only available in Japan
RGBICWW Strip Light Short for SwitchBot RGBICWW Strip Light W1702109
RGBICWW Floor Lamp Short for SwitchBot RGBICWW Floor Lamp W1702101
RGBIC Neon Rope Light Short for SwitchBot RGBIC Neon Rope Light W1702107
RGBIC Neon Wire Rope Light Short for SwitchBot RGBIC Neon Wire Rope Light W1702108
Indoor Cam Short for SwitchBot Indoor Cam W1301200
Pan/Tilt Cam Short for SwitchBot Pan/Tilt Cam W1801200
Pan/Tilt Cam 2K Short for SwitchBot Pan/Tilt Cam 2K W3101100
Blind Tilt Short for SwitchBot Blind Tilt W2701600
Battery Circulator Fan Short for SwitchBot Battery Circulator Fan W3800510
Circulator Fan Short for SwitchBot Circulator Fan W3800511
Evaporative Humidifier Short for SwitchBot Evaporative Humidifier W3902300
Evaporative Humidifier (Auto-refill) Short for SwitchBot Evaporative Humidifier (Auto-refill) W3902310
Air Purifier PM2.5 Short for SwitchBot Air Purifier W5302300
Air Purifier Table PM2.5 Short for SwitchBot Air Purifier Table W5302310
Air Purifier VOC Short for SwitchBot Air Purifier W5302300 Currently only available in Japan
Air Purifier Table VOC Short for SwitchBot Air Purifier Table W5302310 Currently only available in Japan
Roller Shade Short for SwitchBot Roller Shade W5000000
Relay Switch 1PM Short for SwitchBot Relay Switch 1PM W5502310
Relay Switch 1 Short for SwitchBot Relay Switch 1 W5502300
Relay Switch 2PM Short for SwitchBot Relay Switch 2PM W5502320
Garage Door Opener Short for SwitchBot Garage Door Opener W5502330
Floor Lamp Short for SwitchBot RGBWW Floor Lamp W1702100
Strip Light 3 Short for SwitchBot RGBWW Strip Light 3 W1702110
Lock Lite Short for SwitchBot Lock Lite W5110000
Video Doorbell Short for SwitchBot Video Doorbell W6702000
Keypad Vision Short for SwitchBot Keypad Vision W5600003
Keypad Vision Pro Short for SwitchBot Keypad Vision Pro W5600009
Lock Ultra Short for SwitchBot Lock Ultra W5600000
Standing Circulator Fan Short for SwitchBot Standing Circulator Fan W3800520
Pan/Tilt Cam Plus 2K Short for SwitchBot Pan/Tilt Cam Plus 2K W3101102
Pan/Tilt Cam Plus 3K Short for SwitchBot Pan/Tilt Cam Plus 3K W4001100
AI Hub Short for SwitchBot AI Hub W8002100
Candle Warmer Lamp Short for SwitchBot Candle Warmer Lamp W8302100 and W8302101
Home Climate Panel Short for SwitchBot Home Climate Panel W7400000
Smart Radiator Thermostat Short for SwitchBot Smart Radiator Thermostat W7830000
AI Art Frame Short for SwitchBot AI Art Frame W8402000 and W8402010 and W8402020
Permanent Outdoor Lights Short for SwitchBot Permanent Outdoor Lights W1702120
RGBICWW Ceiling Light Short for SwitchBot RGBICWW Ceiling Light W10802300 and W10802310
Battery Circulator Fan 2 Pro Short for SwitchBot Battery Circulator Fan 2 Pro W9502500, W9502501, W9502502, and W9502503
Kata Friends Short for SwitchBot Kata Friends W7912300
AI MindClip Short for SwitchBot AI MindClip W6902000 and W6902003

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,

Parameter Type Location Required Description
Authorization String header Yes Open Token acquired
sign String header Yes A signature generated from the token and secret key using a specific algorithm.
t Long header Yes A 13 digit timestamp (standard time).
nonce Long header Yes A random UUID generated by developers themselves to blend into the string to sign.

Standard HTTP Error Codes

The following table lists the most common HTTP error response,

Code Name Description
400 Bad Request The client has issued an invalid request. This is commonly used to specify validation errors in a request payload.
401 Unauthorized Authorization for the API is required, but the request has not been authenticated.
403 Forbidden The request has been authenticated but does not have appropriate permissions, or a requested resource is not found.
404 Not Found Specifies the requested path does not exist.
406 Not Acceptable The client has requested a MIME type via the Accept header for a value not supported by the server.
415 Unsupported Media Type The client has defined a contentType header that is not supported by the server.
422 Unprocessable Entity The client has made a valid request, but the server cannot process it. This is often used for APIs for which certain limits have been exceeded.
429 Too Many Requests The client has exceeded the number of requests allowed for a given time window.
500 Internal Server Error An unexpected error on the SmartThings servers has occurred. These errors should be rare.

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
  • Hub 3
  • 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
  • Meter Pro
  • Meter Pro CO2
  • Circulator Fan
  • Evaporative Humidifier
  • Evaporative Humidifier (Auto-refill)
  • K10+ Pro Combo
  • Air Purifier VOC
  • Air Purifier Table VOC
  • Air Purifier PM2.5
  • Air Purifier Table PM2.5
  • Roller Shade
  • Relay Switch 1PM
  • Relay Switch 1
  • Hub 3
  • Relay Switch 2PM
  • S20
  • Floor Lamp
  • Strip Light 3
  • Garage Door Opener
  • Lock Lite
  • Video Doorbell
  • Keypad Vision
  • Lock Ultra
  • K20+ Pro
  • K11+
  • Plug Mini (EU)
  • RGBICWW Strip Light
  • RGBICWW Floor Lamp
  • RGBIC Neon Wire Rope Light
  • Smart Radiator Thermostat
  • Pan/Tilt Cam Plus 2K
  • Pan/Tilt Cam Plus 3K
  • Standing Circulator Fan
  • AI Hub
  • Keypad Vision Pro
  • Candle Warmer Lamp
  • Presence Sensor
  • Home Climate Panel
  • RGBIC Neon Rope Light
  • AI Art Frame
  • new Permanent Outdoor Lights
  • new RGBICWW Ceiling Light
  • new Battery Circulator Fan 2 Pro
  • new Kata Friends
  • new AI MindClip

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, Hub 3 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,

Key Name Value Type
statusCode Integer
message String
body Object

The body object contains the following properties,

Key Name Value Type Description
deviceList Array a list of physical devices
infraredRemoteList Array a list of virtual infrared remote devices

The response may contain the following codes and messages,

Status Code Body Content Message Description
100 Device list object success Returns an object that contains two device lists
n/a n/a Unauthorized Http 401 Error. User permission is denied due to invalid token.
190 n/a System error Device internal error due to device states not synchronized with server

The deviceList array contains a list of objects with the following key-value attributes. For detailed device properties, refer to the individual device documentation files in the devices folder.

Sample request

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. The response contains device-specific properties such as power state, temperature, battery level, lock state, position values, and other operational parameters depending on the device type.

Path parameters

Name Type Required Description
deviceId String Yes device ID

Response structure

Key Name Value Type
statusCode Integer
message String
body Object

Response codes

Status Code Body Content Message Description
100 Device list object success Returns an object that contains two device lists
n/a n/a Unauthorized Http 401 Error. User permission is denied due to invalid token.
190 n/a System error Device internal error due to device states not synchronized with server

Sample requests

Get Meter status
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"
}
Get Curtain status
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 to control their behavior, such as turning on/off, changing settings, or triggering actions.

Path parameters

Name Type Required Description
deviceId String Yes device ID

Request body parameters

Name Type Required Description
command String Yes the name of the command
parameter String/Object No some commands require parameters, such as SetChannel or position values
commandType String No for customized buttons on virtual devices, set to customize

Response

Key Name Value Type
statusCode Integer
message String
body Object

Error codes

Error code/message Description
{"message": "Unauthorized"} Http 401 Error. User permission is denied due to invalid token.
151 device type error
152 device not found
160 command is not supported
161 device offline
171 hub device is offline
190 Device internal error due to device states not synchronized with server. Or command format is invalid.

Sample request

Control Floor Cleaning Robot S10

Start cleaning with vacuum and mop:

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

Request body:

{
    "commandType": "command",
    "command": "startClean",
    "parameter": {
        "action": "sweep_mop",
        "param": {
            "fanLevel": 1,
            "waterLevel": 1,
            "times": 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 allows you to access smart scenes created by users and execute manual scenes for home automation workflows.

Get scene list

GET /v1.1/scenes

Description

Get a list of all manual scenes created by the current user's account.

Response structure

Key Name Value Type
statusCode Integer
message String
body Array

Response body schema

The body contains an array of scene objects. Each scene object has:

Key Type Description
sceneId String a scene's ID
sceneName String a scene's name

Error codes

Code/Message Description
100 success
{"message": "Unauthorized"} Http 401 Error. User permission is denied due to invalid token.
190 Device internal error due to device states not synchronized with server

Sample 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"
        }
    ],
    "message": "success"
}

Execute manual scenes

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

Description

Execute a manual scene from the user's list of scenes. This triggers all actions configured in the scene.

Path parameters

Name Type Required Description
sceneId String Yes scene ID

Response structure

Key Name Value Type
statusCode Integer
message String
body Object

Error codes

Code/Message Description
100 success
{"message": "Unauthorized"} Http 401 Error. User permission is denied due to invalid token.
190 Device internal error due to device states not synchronized with server

Sample request

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

Response:

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

Webhook

Configure webhook

POST /v1.1/webhook/setupWebhook

Description

Configure the URL where webhook events will be sent. All device and scene events will be delivered to this endpoint.

Request body parameters

Key Name Type Description
action String required; value: setupWebhook
url String the URL endpoint where events will be sent
deviceList String the list of devices; currently supports "ALL"

Example request

{
    "action": "setupWebhook",
    "url": "https://your-domain.com/switchbot-webhook",
    "deviceList": "ALL"
}

Response

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

Query webhook configuration

POST /v1.1/webhook/queryWebhook

Description

Get current webhook configuration details.

Request body parameters

Key Name Value Type Description
action String the type of actions, currently supports "queryUrl", "queryDetails"
url String the url where all the events are sent to. you need to specify the url when using queryDetails

Request types

Query Webhook URL:

{
    "action": "queryUrl"
}

Query Webhook Details:

{
    "action": "queryDetails",
    "urls": ["https://your-domain.com/switchbot-webhook"]
}

Response examples

queryUrl Response:

{
    "statusCode": 100,
    "body": {
        "urls": ["https://your-domain.com/switchbot-webhook"]
    },
    "message": "success"
}

queryDetails Response:

{
    "statusCode": 100,
    "body": [
        {
            "url": "https://your-domain.com/switchbot-webhook",
            "createTime": 1634567890,
            "lastUpdateTime": 1634567890,
            "deviceList": "ALL",
            "enable": true
        }
    ],
    "message": "success"
}

Update webhook configuration

POST /v1.1/webhook/updateWebhook

Description

Update webhook configuration such as URL, enable/disable status, or device list.

Request body parameters

Key Name Type Description
action String value: updateWebhook
config Object the configuration details you want to update. you can change the current url or enable/disable the webhook. refer to the example below

Example request

{
    "action": "updateWebhook",
    "config": {
        "url": "https://your-domain.com/new-webhook-url",
        "enable": true
    }
}

Response

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

Delete webhook

POST /v1.1/webhook/deleteWebhook

Description

Delete the webhook configuration. After deletion, no events will be sent to the webhook URL.

Request body parameters

Key Name Type Description
action String value: deleteWebhook
url String the webhook URL to delete

Example request

{
    "action": "deleteWebhook",
    "url": "https://your-domain.com/switchbot-webhook"
}

Response

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

Webhook event structure

Webhook events are sent as POST requests in JSON format. The structure varies by device type and event.

Common webhook event properties

Property Type Description
eventType String the type of events
eventVersion String the current event version
context Object the detail info of the event

Bot event example

{
    "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 event example

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

Device Specifications and Supported Features List

Hubs

Device List Status Command Webhook
AI Hub ✓ ✓ - -
Hub 2 ✓ ✓ - ✓
Hub 3 ✓ ✓ - ✓
Hub/Hub Plus/Hub Mini/Hub 2/Hub 3 ✓ - - -

Locks & Security

Device List Status Command Webhook
Keypad ✓ ✓ ✓ ✓
Keypad Touch ✓ ✓ ✓ ✓
Keypad Vision ✓ ✓ ✓ ✓
Keypad Vision Pro ✓ ✓ ✓ ✓
Lock ✓ ✓ ✓ ✓
Lock Lite ✓ ✓ ✓ ✓
Lock Pro ✓ ✓ ✓ ✓
Lock Pro Matter Enabled ✓ ✓ ✓ ✓
Lock Ultra ✓ ✓ ✓ ✓
Lock Vision ✓ ✓ ✓ ✓
Lock Vision Pro ✓ ✓ ✓ ✓
Video Doorbell ✓ ✓ ✓ ✓

Curtains & Blinds

Device List Status Command Webhook
Blind Tilt ✓ ✓ ✓ -
Curtain ✓ ✓ ✓ ✓
Curtain 3 ✓ ✓ ✓ ✓
Roller Shade ✓ ✓ ✓ ✓

Sensors

Device List Status Command Webhook
Contact Sensor ✓ ✓ - ✓
Meter ✓ ✓ - ✓
Meter Plus ✓ ✓ - ✓
Meter Pro ✓ ✓ - ✓
Meter Pro CO2 ✓ ✓ - ✓
Motion Sensor ✓ ✓ - ✓
Outdoor Meter ✓ ✓ - ✓
Presence Sensor ✓ ✓ - ✓
Water Leak Detector ✓ ✓ - ✓

Lighting

Device List Status Command Webhook
Candle Warmer Lamp ✓ ✓ ✓ ✓
Ceiling Light ✓ ✓ ✓ ✓
Ceiling Light Pro ✓ ✓ ✓ ✓
Color Bulb ✓ ✓ ✓ ✓
Floor Lamp ✓ ✓ ✓ ✓
RGBIC Neon Rope Light ✓ ✓ ✓ ✓
RGBIC Neon Wire Rope Light ✓ ✓ ✓ ✓
RGBICWW Floor Lamp ✓ ✓ ✓ ✓
RGBICWW Strip Light ✓ ✓ ✓ ✓
Strip Light ✓ ✓ ✓ ✓
Strip Light 3 ✓ ✓ ✓ ✓
Permanent Outdoor Lights ✓ ✓ ✓ ✓
RGBICWW Ceiling Light ✓ ✓ ✓ ✓

Robot Vacuum

Device List Status Command Webhook
Floor Cleaning Robot S10 ✓ ✓ ✓ ✓
Floor Cleaning Robot S20 ✓ ✓ ✓ ✓
K10+ Pro Combo ✓ ✓ ✓ ✓
K20+ Pro ✓ ✓ ✓ ✓
Mini Robot Vacuum K10+ ✓ ✓ ✓ ✓
Mini Robot Vacuum K10+ Pro ✓ ✓ ✓ ✓
Robot Vacuum Cleaner S1 ✓ ✓ ✓ ✓
Robot Vacuum Cleaner S1 Plus ✓ ✓ ✓ ✓
Robot Vacuum K11+ ✓ ✓ ✓ ✓

Climate Control

Device List Status Command Webhook
Air Purifier PM2.5 ✓ ✓ ✓ ✓
Air Purifier Table PM2.5 ✓ ✓ ✓ ✓
Air Purifier Table VOC ✓ ✓ ✓ ✓
Air Purifier VOC ✓ ✓ ✓ ✓
Battery Circulator Fan ✓ ✓ ✓ ✓
Circulator Fan ✓ ✓ ✓ ✓
Evaporative Humidifier ✓ ✓ ✓ ✓
Evaporative Humidifier (Auto-refill) ✓ ✓ ✓ ✓
Home Climate Panel ✓ ✓ - ✓
Humidifier ✓ ✓ ✓ -
Smart Radiator Thermostat ✓ ✓ ✓ ✓
Standing Circulator Fan ✓ ✓ ✓ ✓
Battery Circulator Fan 2 Pro ✓ ✓ ✓ ✓

Plugs & Switches

Device List Status Command Webhook
Garage Door Opener ✓ ✓ ✓ ✓
Plug ✓ ✓ ✓ -
Plug Mini (EU) ✓ ✓ ✓ ✓
Plug Mini (JP) ✓ ✓ ✓ ✓
Plug Mini (US) ✓ ✓ ✓ ✓
Relay Switch 1 ✓ ✓ ✓ ✓
Relay Switch 1PM ✓ ✓ ✓ ✓
Relay Switch 2PM ✓ ✓ ✓ ✓

Cameras

Device List Status Command Webhook
Indoor Cam ✓ - - ✓
Pan/Tilt Cam ✓ - - ✓
Pan/Tilt Cam 2K ✓ - - -
Pan/Tilt Cam Plus 2K ✓ - - -
Pan/Tilt Cam Plus 3K ✓ - - -

Others

Device List Status Command Webhook
Bot ✓ ✓ ✓ ✓
Remote ✓ - - -
AI Art Frame ✓ ✓ ✓ ✓
Weather Station ✓ ✓ ✓ ✓
Virtual infrared remote devices ✓ - ✓ -
Kata Friends ✓ ✓ ✓ ✓
AI MindClip ✓ ✓ - ✓

About

SwitchBot Open API Documents

Resources

Readme
Activity
Custom properties

Stars

1.2k stars

Watchers

36 watching

Forks

83 forks
Report repository

Releases

Packages

Used by

Contributors