Control You Device

On_off

devices.capabilities.on_off

In this capability you can control the device power on/off

instance	overview
powerSwitch	powerSwitch

description of this capability

the parameters object defines how to pass parameters to control device

{
  "sku": "H713B",
  "device": "AC:3B:D4:AD:FC:B5:BA:CC",
  "capabilities": [
    ...
    {
      "type": "devices.capabilities.on_off",
      "instance": "powerSwitch",
      "parameters": {
        "dataType": "ENUM",
        "options": [
          {
            "name": "on",
            "value": 1
          },
          {
            "name": "off",
            "value": 0
          }
        ]
      }
    }
    ...
  ]
}

example of request

POST /router/api/v1/device/control HTTP/1.1
Host: https://openapi.api.govee.com
Content-Type: application/json
Govee-API-Key: xxxx

{
  "requestId": "uuid",
  "payload": {
    "sku": "H605C",
    "device": "64:09:C5:32:37:36:2D:13",
    "capability": {
      "type": "devices.capabilities.on_off",
      "instance": "powerSwitch",
      "value": 0
    }
  }
}

parameters

field	type	required	overview
requestId	String	Yes	unique id in this request, will be carried back in response body
payload	Object	--	request payload
payload.sku	String	Yes	the product model
payload.device	String	Yes	the device id
payload.capability	Object	--	the device capability to be controlled
capability.type	String	Yes	the type of this capability
capability.instance	String	Yes	the instance of this capability e.g. powerSwitch,
capability.value	String	Yes	the control value of this instance, defin in '/router/api/v1/user/devices', see the parameters

Toggle

devices.capabilities.toggle

In this capability you can control the device small switch like oscillation ,nightlight

instance	overview
oscillationToggle	used for Fan,Heater,Thermostat
nightlightToggle	used for appliances with night light
airDeflectorToggle	used for Fan Heater Air Condition
gradientToggle	used for Light color gradient
thermostatToggle	used for Heater
warmMistToggle	used for Humidifier

description of this capability

provided two command value 0 is off ,1 is on

{
  "sku": "H713B",
  "device": "AC:3B:D4:AD:FC:B5:BA:CC",
  "capabilities": [
    ...
    {
      "type": "devices.capabilities.toggle",
      "instance": "oscillationToggle",
      "parameters": {
        "dataType": "ENUM",
        "options": [
          {
            "name": "on",
            "value": 1
          },
          {
            "name": "off",
            "value": 0
          }
        ]
      }
    }
    ...
  ]
}

example of request

POST /router/api/v1/device/control HTTP/1.1
Host: https://openapi.api.govee.com
Content-Type: application/json
Govee-API-Key: xxxx

{
  "requestId": "uuid",
  "payload": {
    "sku": "H605C",
    "device": "64:09:C5:32:37:36:2D:13",
    "capability": {
      "type": "devices.capabilities.toggle",
      "instance": "oscillationToggle",
      "value": 0
    }
  }
}

Color_setting

devices.capabilities.color_setting

list of instance

instance	overview
colorRgb	setting the light color
colorTemperatureK	setting the color temperature in Kelvin，

{
  "sku": "H713B",
  "device": "AC:3B:D4:AD:FC:B5:BA:CC",
  "capabilities": [
    ...
    {
        "type": "devices.capabilities.color_setting",
        "instance": "colorTemperatureK",
        "parameters": {
          "dataType": "INTEGER",
          "range": {
            "min": 2000,
            "max": 9000,
            "precision": 1
          }
        }
      },
    ...
  ]
}

{
  "sku": "H713B",
  "device": "AC:3B:D4:AD:FC:B5:BA:CC",
  "capabilities": [
    ...
    {
        "type": "devices.capabilities.color_setting",
        "instance": "colorRgb",
        "parameters": {
          "dataType": "INTEGER",
          "range": {
            "min": 0,
            "max": 16777215,
            "precision": 1
          }
        }
    },
    ...
  ]
}

example of request

The instance colorRgb can change light color，you can get RGB number follow this formula ((r & 0xFF) << 16) | ((g & 0xFF) << 8) | ((b & 0xFF) << 0)

POST /router/api/v1/device/control HTTP/1.1
Host: https://openapi.api.govee.com
Content-Type: application/json
Govee-API-Key: xxxx

{
  "requestId": "uuid",
  "payload": {
    "sku": "H605C",
    "device": "64:09:C5:32:37:36:2D:13",
    "capability": {
      "type": "devices.capabilities.color_setting",
      "instance": "colorRgb",
      "value": 0
    }
  }
}

POST /router/api/v1/device/control HTTP/1.1
Host: https://openapi.api.govee.com
Content-Type: application/json
Govee-API-Key: xxxx

{
  "requestId": "uuid",
  "payload": {
    "sku": "H605C",
    "device": "64:09:C5:32:37:36:2D:13",
    "capability": {
      "type": "devices.capabilities.color_setting",
      "instance": "colorTemperatureK",
      "value": 0
    }
  }
}

Mode

devices.capabilities.mode

In this capability you can switch the mode, such as the night light scene

list of instance

instance	overview
nightlightScene	switch the night scene, used for appliance with night light
presetScene	used for `devices.types.aroma_diffuser`, preset scenes

example description of this capability

provided value options

{
  "sku": "H713B",
  "device": "AC:3B:D4:AD:FC:B5:BA:CC",
  "capabilities": [
    ...
    {
        "type": "devices.capabilities.mode",
        "instance": "nightlightScene",
        "parameters": {
          "dataType": "ENUM",
          "options": [
            {
              "name": "Forest",
              "value": 1
            },
            {
              "name": "Ocean",
              "value": 2
            },
            {
              "name": "Wetland",
              "value": 3
            },
            {
              "name": "Leisurely",
              "value": 4
            },
            {
              "name": "ASleep",
              "value": 5
            }
          ]
        }
      },
    ...
  ]
}

example of request

POST /router/api/v1/device/control HTTP/1.1
Host: https://openapi.api.govee.com
Content-Type: application/json
Govee-API-Key: xxxx

{
  "requestId": "1",
  "payload": {
    "sku": "H7131",
    "device": "64:09:C5:32:37:36:2D:13",
    "capability": {
      "type": "devices.capabilities.mode",
      "instance": "nightlightScene",
      "value": 1
    }
  }
}

Range

devices.capabilities.range

Manage device parameters that have a range. For example, lamp brightness, sound volume, heater temperature, humidifier humidity

list of instance

instance	overview
brightness	setting the brightness, used for 'devices.types.light'
humidity	setting humidity, used for 'devices.types.humidifier'

example description of this capability

parameters object defines how to pass parameters to change adjust the range of brightness

{
  "sku": "H605C",
  "device": "64:09:C5:32:37:36:2D:13",
  "capabilities": [
    ...
    {
        "type": "devices.capabilities.range",
        "instance": "brightness",
        "parameters": {
          "dataType": "INTEGER",
          "range": {
            "min": 1,
            "max": 100,
            "precision": 1
          }
        }
      },
    ...
  ]
}

example of request

POST /router/api/v1/device/control HTTP/1.1
Host: https://openapi.api.govee.com
Content-Type: application/json
Govee-API-Key: xxxx

{
  "requestId": "1",
  "payload": {
    "sku": "H605C",
    "device": "64:09:C5:32:37:36:2D:13",
    "capability": {
      "type": "devices.capabilities.range",
      "instance": "brightness",
      "value": 50
    }
  }
}

POST /router/api/v1/device/control HTTP/1.1
Host: https://test-openapi.api.govee.com
Content-Type: application/json
Govee-API-Key: xxxx

{
  "requestId": "1",
  "payload": {
    "sku": "H7143",
    "device": "BA:82:D4:AD:FC:94:A1:D8",
    "capability": {
      "type": "devices.capabilities.range",
      "instance": "humidity",
      "value": 50
    }
  }
}

Work_mode

devices.capabilities.work_mode

In this capability, you can set the working mode of the device and set its working values.

list of instance

instance	overview
workMode	device work mode

example of this capability

{
  "sku": "H713B",
  "device": "AC:3B:D4:AD:FC:B5:BA:CC",
  "capabilities": [
    ...
    {
        "type": "devices.capabilities.work_mode",
        "instance": "workMode",
        "parameters": {
          "dataType": "STRUCT",
          "fields": [
            {
              "fieldName": "workMode",
              "dataType": "ENUM",
              "options": [
                {
                  "name": "gearMode",
                  "value": 1
                },
                {
                  "name": "Fan",
                  "value": 9
                },
                {
                  "name": "Auto",
                  "value": 3
                }
              ],
              "required": true
            },
            {
              "fieldName": "modeValue",
              "dataType": "ENUM",
              "options": [
                {
                  "name": "gearMode",
                  "options": [
                    {
                      "name": "Low",
                      "value": 1
                    },
                    {
                      "name": "Medium",
                      "value": 2
                    },
                    {
                      "name": "High",
                      "value": 3
                    }
                  ]
                },
                {
                  "defaultValue": 0,
                  "name": "Fan"
                },
                {
                  "defaultValue": 22,
                  "name": "Auto"
                }
              ],
              "required": true
            }
          ]
        }
      }
    ...
  ]
}

example of request

POST /router/api/v1/device/control HTTP/1.1
Host: https://openapi.api.govee.com
Content-Type: application/json
Govee-API-Key: xxxx

{
  "requestId": "1",
  "payload": {
    "sku": "H713B",
    "device": "AC:3B:D4:AD:FC:B5:BA:CC",
    "capability": {
      "type": "devices.capabilities.work_mode",
      "instance": "workMode",
      "value": {
      	"workMode":1
        "modeValue":1
      }
    }
  }
}

value object parameters

field	type	required	overview
workMode	Integer	Yes	the temperature Whether to maintain or auto stop. 1. autoStop,0.maintain ,default 0
modeValue	Integer	No	the target temperature to set

Segment_color_setting

devices.capabilities.segment_color_setting

In this capability, you can set color on several segment, when you light strip support segmented color

list of instance

instance	overview
segmentedColorRgb	setting the segmentedColorRgb,
segmentedBrightness	setting the segmentedBrightness

example of this capability

{
  "sku": "H713B",
  "device": "AC:3B:D4:AD:FC:B5:BA:CC",
  "capabilities": [
    ...
    {
        "type": "devices.capabilities.segment_color_setting",
        "instance": "segmentedBrightness",
        "parameters": {
          "dataType": "STRUCT",
          "fields": [
            {
              "fieldName": "segment",
              "size": {
                "min": 1,
                "max": 15
              },
              "dataType": "Array",
              "elementRange": {
                "min": 0,
                "max": 14
              },
              "elementType": "INTEGER",
              "required": true
            },
            {
              "fieldName": "brightness",
              "dataType": "INTEGER",
              "range": {
                "min": 0,
                "max": 100,
                "precision": 1
              },
              "required": true
            }
          ]
        }
      },
    ...
  ]
}

example of request

value is a structure, segment is an array, pointing to the segment of the light strip.

POST /router/api/v1/device/control HTTP/1.1
Host: https://openapi.api.govee.com
Content-Type: application/json
Govee-API-Key: xxxx

{
  "requestId": "1",
  "payload": {
    "sku": "H605C",
    "device": "64:09:C5:32:37:36:2D:13",
    "capability": {
      "type": "devices.capabilities.segment_color_setting",
      "instance": "segmentedColorRgb",
      "value": {
      	"segment":[0,1,2,3,4,5,6,7,8],
        "rgb":0x0000ff
      }
    }
  }
}

POST /router/api/v1/device/control HTTP/1.1
Host: https://test-openapi.api.govee.com
Content-Type: application/json
Govee-API-Key: xxxx

{
  "requestId": "1",
  "payload": {
    "sku": "H605C",
    "device": "64:09:C5:32:37:36:2D:13",
    "capability": {
      "type": "devices.capabilities.segment_color_setting",
      "instance": "segmentedBrightness",
      "value": {
      	"segment":[0,1,2,3,4,5,6,7,8],
        "brightness":50
      }
    }
  }
}

parameters

field	type	required	overview
segment	Array	Yes	the segment of the light strip, see govee app
brightness	Integer	No	set brightness when instance is segmentedBrightness
rgb	Integer	No	set color when instance is segmentedColorRgb, you can get RGB number follow this formula `((r & 0xFF) << 16) \| ((g & 0xFF) << 8) \| ((b & 0xFF) << 0)`

Dynamic_scene

devices.capabilities.dynamic_scene

dynamic_scene means you should edit in govee app such as Scene DIY Snapshot ,then get these options from the interface

list of instance

instance	overview
lightScene	light scene in govee app, used for `devices.types.light`,if the scene options is empty, you need to get these scene options dynamically, see Get Dynamic Scene /router/api/v1/device/scenes,
diyScene	diy in govee app ,used for `devices.types.light`, if the diy options is empty , you need get these dynamically, see Get Dynamic Scene /router/api/v1/device/diy-scenes
snapshot	snapshot list in govee app,used for `devices.types.light`,if the diy options is empty, you should create a snapshot first in govee app

{
    "sku": "H605C",
    "device": "64:09:C5:32:37:36:2D:13",
    "category": "devices.types.light",
    "capabilities": [
			{
        "type": "devices.capabilities.dynamic_scene",
        "instance": "lightScene",
        "parameters": {
          "dataType": "ENUM",
          "options": [
            {
              "name": "Sunrise",
              "value": 0
            },
            {
              "name": "Sunset",
              "value": 1
            },
            {
              "name": "Movie",
              "value": 4
            },
            {
              "name": "Dating",
              "value": 5
            },
            {
              "name": "Romantic",
              "value": 7
            },
            {
              "name": "Flash",
              "value": 8
            },
            {
              "name": "Candle",
              "value": 9
            }
            
          ]
        }
      },
     ]
} you

example of request

POST /router/api/v1/device/control HTTP/1.1
Host: https://openapi.api.govee.com
Content-Type: application/json
Govee-API-Key: xxxx

{
  "requestId": "1",
  "payload": {
    "sku": "H605C",
    "device": "64:09:C5:32:37:36:2D:13",
    "capability": {
      "type": "devices.capabilities.dynamic_scene",
      "instance": "lightScene",
      "value": 4
    }
  }
}

Music_setting

devices.capabilities.music_setting

You can use this capability to switch music modes，and you can pass sensitivity and autoColor field

list of instance

instance	overview
musicMode	light music in govee app

example of this capability

{
  "sku": "H605C",
  "device": "AC:3B:D4:AD:FC:B5:BA:CC",
  "capabilities": [
    ...
    {
        "type": "devices.capabilities.music_setting",
        "instance": "musicMode",
        "parameters": {
          "dataType": "STRUCT",
          "fields": [
            {
              "fieldName": "musicMode",
              "dataType": "ENUM",
              "options": [
                {
                  "name": "Energic",
                  "value": 5
                },
                {
                  "name": "Rhythm",
                  "value": 3
                },
                {
                  "name": "Spectrum",
                  "value": 4
                },
                {
                  "name": "Rolling",
                  "value": 6
                }
              ],
              "required": true
            },
            {
              "fieldName": "sensitivity",
              "dataType": "INTEGER",
              "range": {
                "min": 0,
                "max": 100,
                "precision": 1
              },
              "required": true
            },
            {
              "fieldName": "autoColor",
              "dataType": "ENUM",
              "options": [
                {
                  "name": "on",
                  "value": 1
                },
                {
                  "name": "off",
                  "value": 0
                }
              ],
              "required": false
            },
            {
              "fieldName": "rgb",
              "dataType": "INTEGER",
              "range": {
                "min": 0,
                "max": 16777215,
                "precision": 1
              },
              "required": true
            }
          ]
        }
      },
    ...
  ]
}

example of request

POST /router/api/v1/device/control HTTP/1.1
Host: https://openapi.api.govee.com
Content-Type: application/json
Govee-API-Key: xxxx

{
  "requestId": "1",
  "payload": {
    "sku": "H605C",
    "device": "AC:3B:D4:AD:FC:B5:BA:CC",
    "capability": {
      "type": "devices.capabilities.music_setting",
      "instance": "musicMode",
      "value": {
      	"musicMode":25,
        "sensitivity":50
      }
    }
  }
}

POST /router/api/v1/device/control HTTP/1.1
Host: https://openapi.api.govee.com
Content-Type: application/json
Govee-API-Key: xxxx

{
  "requestId": "1",
  "payload": {
    "sku": "H7175",
    "device": "93:5D:D4:AD:FC:F5:5A:1F",
    "capability": {
      "type": "devices.capabilities.temperature_range",
      "instance": "silderTemperature",
      "value": {
      	"autoStop":1
      	"temperature":25
        "unit":"Celsius"
      }
    }
  }
}

parameters

field	type	required	overview
musicMode	Integer	Yes	the music code or music number
sensitivity	Integer	No	the sensitivity of
autoColor	Integer	No	auto color
rgb		No	the rgb color `((r & 0xFF) << 16) \| ((g & 0xFF) << 8) \| ((b & 0xFF) << 0)`

Temperature_setting

You can set the temperature and choose whether to stop automatically. In addition, you can also choose the temperature unit.

devices.capabilities.temperature_setting

list of instance

instance	overview
targetTemperature	setting the thermostat temperature, used for 'devices.types.heater' or 'devices.types.thermostat'
sliderTemperature	setting temperature , used for 'devices.types.kettle'

example of this capability

You will pass an structure type value，which describes the parameters required to set the temperature

{
  "sku": "H713B",
  "device": "AC:3B:D4:AD:FC:B5:BA:CC",
  "capabilities": [
    ...
    {
        "type": "devices.capabilities.temperature_setting",
        "instance": "targetTemperature",
        "parameters": {
          "dataType": "STRUCT",
          "fields": [
            {
              "fieldName": "autoStop",
              "defaultValue": 0,
              "dataType": "ENUM",
              "options": [
                {
                  "name": "Auto Stop",
                  "value": 1
                },
                {
                  "name": "Maintain",
                  "value": 0
                }
              ],
              "required": false
            },
            {
              "fieldName": "temperature",
              "dataType": "INTEGER",
              "range": {
                "min": 5,
                "max": 30,
                "precision": 1
              },
              "required": true
            },
            {
              "fieldName": "unit",
              "defaultValue": "Celsius",
              "dataType": "ENUM",
              "options": [
                {
                  "name": "Celsius",
                  "value": "Celsius"
                },
                {
                  "name": "Fahrenheit",
                  "value": "Fahrenheit"
                }
              ],
              "required": true
            }
          ]
        }
      },
    ...
  ]
}

example of request

POST /router/api/v1/device/control HTTP/1.1
Host: https://openapi.api.govee.com
Content-Type: application/json
Govee-API-Key: xxxx

{
  "requestId": "1",
  "payload": {
    "sku": "H713B",
    "device": "AC:3B:D4:AD:FC:B5:BA:CC",
    "capability": {
      "type": "devices.capabilities.temperature_setting",
      "instance": "teargetTemperature",
      "value": {
      	"temperature":25
        "unit":"Celsius"
      }
    }
  }
}

POST /router/api/v1/device/control HTTP/1.1
Host: https://test-openapi.api.govee.com
Content-Type: application/json
Govee-API-Key: xxxx

{
  "requestId": "1",
  "payload": {
    "sku": "H7175",
    "device": "93:5D:D4:AD:FC:F5:5A:1F",
    "capability": {
      "type": "devices.capabilities.temperature_range",
      "instance": "silderTemperature",
      "value": {
      	"autoStop":1
      	"temperature":25
        "unit":"Celsius"
      }
    }
  }
}

value object parameters

field	type	required	overview
autoStop	Integer	No	the temperature Whether to maintain or auto stop. 1. autoStop,0.maintain ,default 0
temperature	Integer	Yes	the target temperature to set
unit	String	No	the temperature unit , Celsius or Fahrenheit ,default Celsius

failure response

example of response

failure reason

code	overview
400	Missing Parameter
400	Parameter value cannot be empty
400	Invalid parameter format
400	Invalid parameter type
400	Parameter value out of range
400	Parameter length does not meet requirements
400	Duplicate parameter value
404	Instance Not Fund
404	device not found
429	too many request ,the limits

Friendly Reminder

if the request response 429, means request limits happens, 10000/Account/Day