Govee Developer API Reference

Important Note

Version V1.7 will be online after May 4, 2022, and the flow of some high-frequency API calls will be limited. Users are advised to complete any needed modifications to their API applications before this date. Specific rules are available in the Version V1.7 document:

Govee Developer API Reference (document of Version V1.7)

Example HTTP Response by Postman

An example of an HTTP response from Postman, an HTTP test tool, is shown below:

Status: 200 OK, Time: 2.50 s

Rate Limiting

The returned HTTP headers show the current rate limit status:

There are two levels of limits working together. Users should ensure their design does not reach any level of the limits, otherwise, the HTTP response status will be 429 (Too Many Requests).

1. X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset: This level of limit works on all APIs, meaning total requests from one user cannot exceed 1000 per day.

   Works on All APIs	10000 per day

2. API-RateLimit-Limit, API-RateLimit-Remaining, API-RateLimit-Reset:

   DeviceList	10 per minute
   DeviceControl	10 per minute per device
   DeviceState	10 per minute per device

F&Q (Frequently Asked Questions)

1. I have a Bluetooth device. Does it support Wi-Fi API?

   No, only Wi-Fi devices support the API.

2. When using the Govee Home APP to control device brightness, the API does not display the changed status.

   The changed status can only be synchronized when the lights are controlled via Wi-Fi. This means the phone's Bluetooth needs to be turned off. Users should recheck if their phone's Bluetooth is off.

3. I have a problem using third-party software. I am not a developer. Can Govee solve the problem with third-party software?

   Govee does not support third-party software that uses their API for integration. Since Govee is not involved in such integrations, they cannot diagnose or solve problems related to them. It is advised to contact the third-party support directly to resolve the issue.

4. How to refresh the API key?

   The Govee Developer API Key can be applied through the Govee Home App. The key is refreshed every time it is applied and will be sent to the email address.

5. What can I do if the response status is not 200?

   Users should first read the "message" in the Response Body. If questions persist, users should send their Request Params and the values of "Date" and "X-traceId" shown in the Response Header, as these are helpful for debugging.

Getting Started with the Govee Developer API

The Govee Developer API allows control of devices and querying of device states.

The device models supported by the current version include: H6160, H6163, H6104, H6109, H6110, H6117, H6159, H7022, H6086, H6089, H6182, H6085, H7014, H5081, H6188, H6135, H6137, H6141, H6142, H6195, H7005, H6083, H6002, H6003, H6148, H6052, H6143, H6144, H6050, H6199, H6054, H5001, H6154, H6072, H6121, H611A, H5080, H6062, H614C, H615A, H615B, H7020, H7021, H614D, H611Z, H611B, H611C, H615C, H615D, H7006, H7007, H7008, H7012, H7013, H7050, H6051, H6056, H6061, H6058, H6073, H6076, H619A, H619C, H618A, H618C, H6008, H6071, H6075, H614A, H614B, H614E, H618E, H619E, H605B, H6087, H6172, H619B, H619D, H619Z, H61A0, H7060, H610A, H6059, H7028, H6198, H6049, H7031, H7032, H61A1, H61A2, H61B2, H7061, H6067, H6066, H6009, H7041, H7042, H604A, H6173, H615E, H604B, H6091, H7051, H7062, H618F, H605D.

Before starting, users should be familiar with:

1. How to use the Govee Developer API key
2. Rate limiting

How to Use Govee Developer API Key

The Govee Developer API Key is used for authentication. Requests requiring authentication will return a 401 Unauthorized status.

Users should use the HTTP header 'Govee-API-Key' to send the Govee Developer API Key. Examples are provided in the API documentation.

Govee Developer API Endpoints

DeviceList

GET /v1/devices

Retrieves information about all supported devices in the account.

Request Headers

Govee-API-Key : {your_Govee_API_KEY}

Response Body Parameters

Content Type: application/json

code

The code value will be 200 for a successful request, indicating success.

Type: number, Required: Yes

message

The message value will be "success" for a successful request, or an error message.

Type: string, Required: Yes

data

The response data.

Type: object, Required: Yes

data.devices

Returns devices supported by the Govee Developer API.

Type: array, Required: Yes

data.devices.model

Product Model of the device.

Type: string, Required: Yes

data.devices.device

Mac address of the device. Used with model to identify a target device.

Type: string, Required: Yes

data.devices.controllable

Indicates if the device supports control commands (true/false).

Type: bool, Required: Yes

data.devices.retrievable

Indicates if the device supports querying its current state (true/false).

Type: bool, Required: Yes

data.devices.supportCmds

Commands supported by the device. Valid values in the array: "turn", "brightness", "color", "colorTem".

Type: array, Required: Yes

Errors

AuthorizationError

Indicates an invalid Govee Developer API key. 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"],"properties": {"colorTem": {"range": {"min": 2000,"max": 9000}}}},{"device": "34:20:03:2e:30:2b","model": "H5081","deviceName": "Smart Plug","controllable": true,"retrievable": true,"supportCmds": ["turn"]}]},"message": "Success","code": 200}

DeviceControl

Uses supported commands to control the device.

Request Headers

Content-Type: application/json

Govee-API-Key : {your_Govee_API_KEY}

Request Body Parameters

device

The Mac address of the device to control.

Type: String, Required: Yes

model

The Model of the device to control.

Type: String, Required: Yes

cmd

Device commands.

Type: object, Required: Yes

cmd.name

Device command name. Used with cmd.value. Valid values: "turn", "brightness", "color", "colorTem".

Type: object, Required: Yes

cmd.value

Device command value. Used with cmd.name.

Type: number, Required: Yes

Demos:

{"name": "turn", value: "off"}{"name": "brightness", value: 10}{"name": "color", value: {"r": 255, "g": 255, "b": 255}}{"name": "colorTem", value: 7000}

When cmd.name is "turn":

Valid values are "on" and "off". Type: string.

When cmd.name is "brightness":

Valid values are between 0 and 100, where 0 turns off the device. Type: number.

When cmd.name is "color":

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.

When cmd.name is "colorTem":

Valid values are returned by DeviceList, with an additional "properties" field:

"properties": {"colorTem": {"range": {"min": 2000,"max": 9000}}}

Response Body Parameters

Content Type: application/json

code

The code value will be 200 for a successful request.

Type: number, Required: Yes

message

The message value will be "success" for a successful request, or an error message.

Type: string, Required: Yes

data

The response data.

Type: object, Required: Yes

Errors

AuthorizationError

Indicates an invalid Govee Developer API key. HTTP Status Code: 403.

InternalError

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

InvalidParameter

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

Example

Sample Request 1 (Turn On/Off)

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 (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 (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 (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

Queries the device state.

Request Headers

Content-Type: application/json

Govee-API-Key : {your_Govee_API_KEY}

Request Query Parameters

device

The Mac address of the device to control.

Type: String, Required: Yes

model

The Model of the device to control.

Type: String, Required: Yes

Response Body Parameters

Content Type: application/json

code

The code value will be 200 for a successful request.

Type: number, Required: Yes

message

The message value will be "success" for a successful request, or an error message.

Type: string, Required: Yes

data

The response data.

Type: object, Required: Yes

data.model

Product Model of your device.

Type: array, Required: Yes

data.device

Mac address of your device.

Type: string, Required: Yes

data.name

Device name.

Type: string, Required: Yes

data.properties

Device states.

Demos:

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

Type: arr, Required: Yes

Note: "online" status is implemented through the cache and may sometimes return a wrong state. Third-party developers should ensure that even if "online" returns "false", users are still allowed to send control commands, as the device may still be controllable if the cache is wrong.

Errors

AuthorizationError

Indicates an invalid Govee Developer API key. HTTP Status Code: 403.

InternalError

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

InvalidParameter

Indicates that a request parameter does not comply with 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:8D, model: 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}

Version History

Version 1.5

Supports models: H7031, H7032, H61A1, H61A2, H61B2, H7061, H6067, H6066, H6009, H7041, H7042, H604A, H6173, H615E, H604B, H6091, H7051, H7062, H618F, H605D.

Version 1.4

Supports models: H605B, H6087, H6172, H619B, H619D, H619Z, H61A0, H7060, H610A, H6059, H7028, H6198, H6049.

Version 1.3

Supports models: H7050, H6051, H6056, H6061, H6058, H6073, H6076, H619A, H619C, H618A, H618C, H6008, H6071, H6075, H614A, H614B, H614E, H618E, H619E.

Version 1.2

Supports models: H6050, H6154, H6143, H6144, H6072, H6121, H611A, H5080, H6062, H614C, H615A, H615B, H7020, H7021, H614D, H611Z, H611B, H611C, H615C, H615D, H7006, H7007, H7008, H7012, H7013.

Change in DeviceState: When cmd.name is "colorTem", valid values are returned by DeviceList, with an additional "properties" field:

"properties": {"colorTem": {"range": {"min": 2000,"max": 9000}}}