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
swingLeafToggle	used for Fan or Air Condition
reverseAirflowToggle	used for
mainLightToggle	This is for ceiling lights with backlighting.
backgroundLightToggle	This is for ceiling lights with backlighting
gradientToggle	used for light effect
dreamViewToggle	used for turn on/off dream view effect
precoolToggle	used for ice maker
iceMakingToggle	used for ice maker
socketToggle1	socketToggle1,socketToggle2 used for Multi-slot socke
leftLightToggle,rightLightToggle	backLightToggle, Backlight for monitors with left and right light pillars
pillarLightToggle, baseLightToggle	used for floor lamps

used 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 by combining red, green, and blue values.

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, RGB value from 0 to 16777215

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

Temperature_setting

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

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