Govee API Reference: Integrate Smart Devices with Govee API 1.0

Getting Started with the Govee API

The Govee API 1.0 allows control and querying of Govee smart device states.

Supported Device Models

The current version supports the following device models: H6160, H6163, H6104, H6109, H6110, H6117, H6159, H7021, H7022, H6086, H6089, H6182, H6085, H7014, H5081, H6188, H6135, H6137, H6141, H6142, H6195, H6196, H7005, H6083, H6002, H6003, H6148.

Before starting, it is important to understand:

How to use the Govee API key.
Rate limiting policies.

How to Use Govee API Key

The Govee API Key is essential for authentication. Requests requiring authentication will return a 401 Unauthorized HTTP status code if the key is missing or invalid.

To send the Govee API Key, use the HTTP header 'Govee-API-Key'. Examples of its usage are provided in the API documentation.

Rate limiting

All requests are subject to a rate limit of up to 100 requests per minute, associated with the originating IP address.

The current rate limit status is indicated by specific HTTP headers in any API response:

curl -i https://developer-api.govee.com/pingHTTP/1.1 200 OKDate: Tue, 30 Jun 2020 08:05:06 GMTContent-Type: text/plain; charset=utf-8Content-Length: 4Connection: keep-aliveRate-Limit-Remaining: 97Rate-Limit-Reset: 1593504314.634753Rate-Limit-Total: 100Vary: OriginAccess-Control-Allow-Origin: *X-Response-Time: 0msX-traceId: 68e7b870-baa8-11ea-8227-87bfa7a49d9e

Header Name	Description
X-RateLimit-Limit	The maximum number of requests permitted per minute.
X-RateLimit-Remaining	The number of requests remaining in the current rate limit window.
X-RateLimit-Reset	The time (in UTC epoch seconds) at which the current rate limit window resets.

Govee APIs

Ping

GET /ping

This is a health check endpoint for the API that does not return any account-specific information.

Response Body

Content Type: text/plain

Returns: Pong

Errors

InternalError: Indicates an internal service error. HTTP Status Code: 500.

Example

Sample Request

Request URL: https://developer-api.govee.com/pingRequest Method: GET

Sample Response

Pong

DeviceList

GET /v1/devices

Retrieves information about all supported devices associated with the account.

Request Headers

Content-Type: application/json
Govee-API-Key : {your_Govee_API_KEY}

Response Body parameters

`code`

Type: number
Required: Yes
Description: The value is 200 for a successful request.

`message`

Type: string
Required: Yes
Description: The value is "success" for a successful request, otherwise it contains an error message.

`data`

Type: object
Required: Yes
Description: The response data.

`data.devices`

Type: array
Required: Yes
Description: A list of devices supported by the Govee API.

`data.devices.model`

Type: string
Required: Yes
Description: The product model of the device.

`data.devices.device`

Type: string
Required: Yes
Description: The MAC address of the device. Used with the model to identify a specific device.

`data.devices.controllable`

Type: bool
Required: Yes
Valid Values: true, false
Description: Indicates if the device supports control commands.

`data.devices.retrievable`

Type: bool
Required: Yes
Valid Values: true, false
Description: Indicates if the device supports querying its current state.

`data.devices.supportCmds`

Type: array
Required: Yes
Valid Values: "turn", "brightness", "color", "colorTem"
Description: Commands supported by the device.

Errors

AuthorizationError: Indicates that the Govee API key is invalid. HTTP Status Code: 403.

InternalError: Indicates an internal service error. HTTP Status Code: 500.

Example

Sample Request

Request URL: https://developer-api.govee.com/v1/devicesRequest Method: GETRequest Header:Govee-API-Key: 00000000-729c-4b82-b536-000000000

Sample Response

{"data": {"devices": [{"device": "99:E5:A4:C1:38:29:DA:7B","model": "H6159","deviceName": "test light","controllable": true,"retrievable": true,"supportCmds": ["turn","brightness","color","colorTem"]},{"device": "C6:EA:B8:56:C8:C6:89:BE","model": "H6188","deviceName": "H6188_89BE","controllable": true,"retrievable": true,"supportCmds": ["turn","brightness","color","colorTem"]},{"device": "34:20:03:2e:30:2b","model": "H5081","deviceName": "Smart Plug","controllable": true,"retrievable": true,"supportCmds": ["turn"]}]},"message": "Success","code": 200}

DeviceControl

Allows sending supported commands to control a device.

Request Headers

Content-Type: application/json
Govee-API-Key : {your_Govee_API_KEY}

Request Body parameters

`device`

Type: String
Required: Yes
Description: The MAC address of the device to control.

`model`

Type: String
Required: Yes
Valid values: H6160, H6163, H6104, H6109, H6110, H6117, H6159, H7021, H7022, H6086, H6089, H6182, H6085, H7014, H5081, H6188, H6135, H6137, H6141, H6142, H6195, H6196, H7005, H6083, H6002, H6003, H6148
Description: The model of the device to control.

`cmd`

Type: object
Required: Yes
Description: Device commands.

`cmd.name`

Type: object
Required: Yes
Valid values: "turn", "brightness", "color", "colorTem"
Description: The name of the device command, used with cmd.value.

`cmd.value`

Type: Varies (string, number, object)
Required: Yes
Description: The value associated with the cmd.name.

Demos for `cmd.value`:

For cmd.name is "turn": {"name": "turn", value: "off"}. Valid values are "on" and "off". Type: string.
For cmd.name is "brightness": {"name": "brightness", value: 10}. Valid values are between 0 and 100. Type: number.
For cmd.name is "color": {"name": "color", value: {"r": 255, "g": 255, "b": 255}}. Type: object.
- cmd.value.r: Red value. Valid range is 0~255. Type: number.
- cmd.value.g: Green value. Valid range is 0~255. Type: number.
- cmd.value.b: Blue value. Valid range is 0~255. Type: number.
For cmd.name is "colorTem": {"name": "colorTem", value: 7000}. Valid values are between 2000 and 9000. Type: number.

Response Body parameters

`code`

Type: number
Required: Yes
Description: The value is 200 for a successful request.

`message`

Type: string
Required: Yes
Description: The value is "success" for a successful request, otherwise it contains an error message.

`data`

Type: object
Required: Yes
Description: The response data.

Errors

AuthorizationError: Indicates that the Govee API key is invalid. HTTP Status Code: 403.

InternalError: Indicates an internal service error. HTTP Status Code: 500.

InvalidParameter: Indicates that a request parameter does not comply with the associated constraints. HTTP Status Code: 400.

Example

Sample Request 1 (Turn On)

Request URL: https://developer-api.govee.com/v1/devices/controlRequest Method: PUTRequest Header:Content-Type: application/jsonGovee-API-Key : 00000000-729c-4b82-b536-000000000Request body:{"device": "34:20:03:15:82:ae","model": "H6089","cmd": {"name": "turn","value": "on"}}

Sample Request 2 (Set Brightness)

Request URL: https://developer-api.govee.com/v1/devices/controlRequest Method: PUTRequest Header:Content-Type: application/jsonGovee-API-Key : 00000000-729c-4b82-b536-000000000Request body:{"device": "34:20:03:15:82:ae","model": "H6089","cmd": {"name": "brightness","value": 50}}

Sample Request 3 (Set Color)

Request URL: https://developer-api.govee.com/v1/devices/controlRequest Method: PUTRequest Header:Content-Type: application/jsonGovee-API-Key : 00000000-729c-4b82-b536-000000000Request body:{"device": "34:20:03:15:82:ae","model": "H6089","cmd": {"name": "color","value": {"r": 255,"g": 255,"b": 255}}}

Sample Request 4 (Set Color Temperature)

Request URL: https://developer-api.govee.com/v1/devices/controlRequest Method: PUTRequest Header:Content-Type: application/jsonGovee-API-Key : 00000000-729c-4b82-b536-000000000Request body:{"device": "34:20:03:15:82:ae","model": "H6089","cmd": {"name": "colorTem","value": 7000}}

Sample Response

{"code": 200,"message": "Success","data": {}}

DeviceState

Allows querying the current state of a device.

Request Headers

Content-Type: application/json
Govee-API-Key : {your_Govee_API_KEY}

Request Query parameters

`device`

Type: String
Required: Yes
Description: The MAC address of the device to query.

`model`

Type: String
Required: Yes
Valid values: H6160, H6163, H6104, H6109, H6110, H6117, H6159, H7021, H7022, H6086, H6089, H6182, H6085, H7014, H5081, H6188, H6135, H6137, H6141, H6142, H6195, H6196, H7005, H6083, H6002, H6003, H6148
Description: The model of the device to query.

Response Body parameters

`code`

Type: number
Required: Yes
Description: The value is 200 for a successful request.

`message`

Type: string
Required: Yes
Description: The value is "success" for a successful request, otherwise it contains an error message.

`data`

Type: object
Required: Yes
Description: The response data.

`data.model`

Type: array
Required: Yes
Description: The product model of the device.

`data.device`

Type: string
Required: Yes
Description: The MAC address of the device.

`data.name`

Type: string
Required: Yes
Description: The device name.

`data.properties`

Type: array
Required: Yes
Description: The device states.

Demos for `data.properties`:

{"online": "false"}
{"powerState" : "off"}
{"brightness" : 60}
{"color": {"r": 255, "g" : 255, "b", 255}}
{"colorTem": 5000}

Errors

AuthorizationError: Indicates that the Govee API key is invalid. HTTP Status Code: 403.

InternalError: Indicates an internal service error. HTTP Status Code: 500.

InvalidParameter: Indicates that a request parameter does not comply with the associated constraints. HTTP Status Code: 400.

Example

Sample Request

Request URL: https://developer-api.govee.com/v1/devices/state?device=06%3A7A%3AA4%3AC1%3A38%3A5A%3A2A%3A8D&model=H6148Request Method: GETRequest Header:Govee-API-Key : 00000000-729c-4b82-b536-000000000Request Query Parameters:device: 06:7A:A4:C1:38:5A:2A:8Dmodel: H6148

Sample Response

{"data": {"device": "C6:EA:B8:56:C8:C6:89:BE","model": "H6188","properties": [{"online": "false"},{"powerState": "off"},{"brightness": 82},{"color": {"r": 0,"b": 0,"g": 0}}]},"message": "Success","code": 200}

	Govee Developer API Reference Guide Comprehensive guide to the Govee Developer API, detailing endpoints for device control, state querying, rate limiting, and setup. Includes supported device models and API usage examples.
	Govee Developer API Reference Version 1.5 Comprehensive reference guide for the Govee Developer API Version 1.5, detailing API key usage, rate limiting, supported device models, and endpoints for device listing, control, and state querying. Includes request/response examples and error handling.
	Govee Developer API Reference Version 2.0 Comprehensive reference for the Govee Developer API, detailing how to control and query Govee smart devices including lights, plugs, switches, and appliances. Covers API key usage, rate limiting, device listing, device control, and device state queries with example requests and responses. Includes supported model numbers and version history.
	Signify v. Shenzhen Intellirocks: Patent Infringement Complaint for LED Lighting Products Details of a patent infringement lawsuit filed by Signify North America Corporation and Signify Holding B.V. against Shenzhen Intellirocks Tech Co., LTD. concerning LED lighting products and technologies.
	Govee LED Strip Lights Integration Guide for Control4 Comprehensive guide for installing and using Govee LED strip lights with Control4 smart home systems, covering driver setup, licensing, features, and troubleshooting.
	How to Obtain Your Govee Home App API Key Learn how to get an API key from the Govee Home app. Follow the steps to request your API key via email for integration with other services.
	Declaration of Conformity for Govee LED Light Strips This Declaration of Conformity from Shenzhen Intellirocks Tech. Co., Ltd. certifies that Govee LED Light Strip models H6159, H6109, H6110, and H6160 comply with EU directives and harmonized standards for Low Voltage, CE-RED, RoHS, and REACH.
	Govee RGB LED Strip Light Model Similarity Declaration This document from Shenzhen Qianyan Technology LTD declares the differences in rated input, strip length, and number of strips among various Govee RGB LED Strip Light models (H615E, H615A, H615B, H615C, H615D, H6159, H6110, H614B, H614E) while confirming other specifications are identical to the tested model.

Getting Started with the Govee API

Supported Device Models

How to Use Govee API Key

Rate limiting

Govee APIs

Ping

GET /ping

Response Body

Errors

Example

Sample Request

Sample Response

DeviceList

GET /v1/devices

Request Headers

Response Body parameters

code

message

data

data.devices

data.devices.model

data.devices.device

data.devices.controllable

data.devices.retrievable

data.devices.supportCmds

Errors

Example

Sample Request

Sample Response

DeviceControl

Request Headers

Request Body parameters

device

model

cmd

cmd.name

cmd.value

Demos for cmd.value:

Response Body parameters

code

message

data

Errors

Example

Sample Request 1 (Turn On)

Sample Request 2 (Set Brightness)

Sample Request 3 (Set Color)

Sample Request 4 (Set Color Temperature)

Sample Response

DeviceState

Request Headers

Request Query parameters

device

model

Response Body parameters

code

message

data

data.model

data.device

data.name

data.properties

Demos for data.properties:

Errors

Example

Sample Request

Sample Response

Related Documents

`code`

`message`

`data`

`data.devices`

`data.devices.model`

`data.devices.device`

`data.devices.controllable`

`data.devices.retrievable`

`data.devices.supportCmds`

`device`

`model`

`cmd`

`cmd.name`

`cmd.value`

Demos for `cmd.value`:

`code`

`message`

`data`

`device`

`model`

`code`

`message`

`data`

`data.model`

`data.device`

`data.name`

`data.properties`

Demos for `data.properties`: