{"openapi":"3.0.3","info":{"title":"GOVEE Developer API","description":"Use the Govee Developer API to control devices and query device state.","termsOfService":"https://app-h5.govee.com/common/api-service-item","version":"2.0.0","contact":{"name":"API Support","url":"https://www.govee.com/support","email":"api-support@govee.com"}},"tags":[{"name":"Devices","description":"APIs for Govee Devices such as lights, plugs, and switches."},{"name":"Appliances","description":"APIs for Govee Appliances such as humidifiers, dehumidifiers, fans, and heaters."}],"servers":[{"url":"https://developer-api.govee.com","description":"Govee Cloud API"}],"paths":{"/v1/devices":{"get":{"tags":["Devices"],"summary":"List Devices","description":"Use this API to retrieve a list of supported lights, plugs, and switches bound to the account.","operationId":"getLightDeviceInfo","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListDevicesResponse"}}}},"401":{"description":"Unauthorized\n\nIndicates that the Govee Developer API key is invalid.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too Many Requests\n\nRate limit exceeded, retry in # seconds.\n"},"500":{"description":"Internal Error"}}}},"/v1/devices/state":{"get":{"tags":["Devices"],"summary":"Get Device State","description":"Use this API to obtain the target device's current state information including if the device is powered on and online, the set color, and brightness.\n\n> 📘 Supported Device Models\n>\n> This API is for Govee devices such as lights, plugs, and switches. \n>\n> <details>\n>   <summary>Click here for a full list of supported device models.</summary>\n>   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, H6046, H601A, H61A3, H610B, H6047, H7065, H61E1, H6057, H604C, H6065, H605C, H705A, H705B, H7055, H61A5, H6078, H604D, H6168, H6601, H70B1, H61A8 \n> </details>\n\n> 🚧 Online Status is Cached\n>\n> `Online` functionality is provided through a cache system. However, it may occasionally provide incorrect information. To ensure smooth operation, it is recommended that third-party developers allow users to send control commands even when the online status is reported as `false`. This way, users can still control the device even if the cache is inaccurate.\n","operationId":"getDeviceState","parameters":[{"name":"device","in":"query","schema":{"$ref":"#/components/schemas/MACAddress"}},{"name":"model","in":"query","schema":{"$ref":"#/components/schemas/Model"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeviceStateResponse"}}}},"400":{"description":"Bad Request\n\nPossible Reasons for this Error: \n  - Device Not Found\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"message":"Device Not Found","status":400}}}},"401":{"description":"Unauthorized\n\nIndicates that the Govee Developer API key is invalid.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too Many Requests\n\nRate limit exceeded, retry in # seconds.\n"},"500":{"description":"Internal Error"}}}},"/v1/devices/control":{"put":{"tags":["Devices"],"summary":"Control Device","description":"Use this API to leverage supported commands to control lights, plugs, and switches. Use the [List Devices](/reference/getlightdeviceinfo) API to obtain the target device's MAC address (`device`) and `model` info which are needed to use this API.\n\n> 📘 Supported Device Models\n>\n> This API is for Govee devices such as lights, plugs, and switches. \n> \n> <details>\n>   <summary>Click here for a full list of supported device models.</summary>\n>   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, H6046, H601A, H61A3, H610B, H6047, H7065, H61E1, H6057, H604C, H6065, H605C, H705A, H705B, H7055, H61A5, H6078, H604D, H6168, H6601, H70B1, H61A8 \n> </details>\n","operationId":"controlLightDevice","requestBody":{"description":"Leverage supported commands to control devices.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ControlDevicesRequest"},"examples":{"turn":{"summary":"Turn Device On/Off","value":{"device":"0B:B2:CA:30:39:39:29:4F","model":"H7060","cmd":{"name":"turn","value":"on"}}},"brightness":{"summary":"Adjust Device's Brightness","value":{"device":"0B:B2:CA:30:39:39:29:4F","model":"H7060","cmd":{"name":"brightness","value":75}}},"color":{"summary":"Change Device Color","value":{"device":"0B:B2:CA:30:39:39:29:4F","model":"H7060","cmd":{"name":"color","value":{"r":255,"g":255,"b":255}}}},"colorTem":{"summary":"Adjust Device's Color Temperature","value":{"device":"0B:B2:CA:30:39:39:29:4F","model":"H7060","cmd":{"name":"colorTem","value":3000}}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/StatusResponse"},{"type":"object","properties":{"data":{"type":"object","description":"Additional response data","nullable":true}}}]}}}},"400":{"description":"Bad Request\n\nPossible Reasons for this Error: \n  - Device Not Found\n  - Command is not Supported\n  - Unsupported Command Value\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"message":"Unsupported cmd","status":400}}}},"401":{"description":"Unauthorized\n\nIndicates that the Govee Developer API key is invalid.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too Many Requests\n\nRate limit exceeded, retry in # seconds.\n"},"500":{"description":"Internal Error"}}}},"/v1/appliance/devices":{"get":{"tags":["Appliances"],"summary":"List Appliances","description":"Use this API to retrieve a list of supported humidifiers, dehumidifiers, heaters, fans, and so on that are bound to the account.","operationId":"getApplianceDeviceInfo","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListAppliancesResponse"}}}},"401":{"description":"Unauthorized\n\nIndicates that the Govee Developer API key is invalid.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too Many Requests\n\nRate limit exceeded, retry in # seconds.\n"},"500":{"description":"Internal Error"}}}},"/v1/appliance/devices/control":{"put":{"tags":["Appliances"],"summary":"Control Appliance","description":"Use this API to leverage supported commands to control appliances. Use the [List Appliances](/reference/getappliancedeviceinfo) API to obtain the target appliance's MAC address (`device`) and `model` info which are needed to use this API.\n\n> 📘 Supported Device Models\n>\n> This API is for Govee appliances such as humidifiers, dehumidifiers, heaters, fans, and so on. \n>\n> <details>\n>   <summary>Click here for a full list of supported device models.</summary>\n>   H7121, H7122, H7123, H7120, H7141, H7142, H7130, H7131, H7132, H7150, H7160, H7101, H7111\n> </details>\n","operationId":"controlApplianceDevice","requestBody":{"description":"Leverage supported commands to control appliances.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ControlApplianceRequest"},"examples":{"turn":{"summary":"Turn On/Off Appliance","value":{"device":"0B:B2:CA:30:39:39:29:4F","model":"H7121","cmd":{"name":"turn","value":"on"}}},"mode":{"summary":"Adjust the Appliance's Mode","value":{"device":"0B:B2:CA:30:39:39:29:4F","model":"H7121","cmd":{"name":"mode","value":1}}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/StatusResponse"},{"type":"object","properties":{"data":{"type":"object","description":"Additional response data","nullable":true}}}]}}}},"400":{"description":"Bad Request\n\nPossible Reasons for this Error: \n  - Device Not Found\n  - Command is not Supported\n  - Unsupported Command Value\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"message":"Unsupported cmd","status":400}}}},"401":{"description":"Unauthorized\n\nIndicates that the Govee Developer API key is invalid.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too Many Requests\n\nRate limit exceeded, retry in # seconds.\n"},"500":{"description":"Internal Error"}}}}},"components":{"schemas":{"ListDevicesResponse":{"type":"object","description":"Response device data and message","allOf":[{"$ref":"#/components/schemas/DeviceDataObject"},{"$ref":"#/components/schemas/StatusResponse"}]},"ListAppliancesResponse":{"type":"object","description":"Response appliance data and message","allOf":[{"$ref":"#/components/schemas/ApplianceDataObject"},{"$ref":"#/components/schemas/StatusResponse"}]},"ControlDevicesRequest":{"type":"object","required":["device","model","cmd"],"description":"Request parameters for controlling devices","allOf":[{"properties":{"device":{"$ref":"#/components/schemas/MACAddress"},"model":{"$ref":"#/components/schemas/Model"}}},{"$ref":"#/components/schemas/CMDObject"}]},"ControlApplianceRequest":{"type":"object","required":["device","model","cmd"],"description":"Request parameters for controlling devices","allOf":[{"properties":{"device":{"$ref":"#/components/schemas/MACAddress"},"model":{"$ref":"#/components/schemas/Model"}}},{"$ref":"#/components/schemas/CMDObjectAppliance"}]},"DeviceStateResponse":{"type":"object","allOf":[{"properties":{"data":{"type":"object","description":"The data response object.","required":["device","model","properties"],"properties":{"device":{"$ref":"#/components/schemas/MACAddress"},"model":{"$ref":"#/components/schemas/Model"},"properties":{"type":"array","description":"Provides additional details on the device's current state.","items":{"anyOf":[{"type":"object","properties":{"online":{"type":"string","example":false,"description":"An indicator to determine if the device is online e.g. connected to WiFi."}}},{"type":"object","properties":{"powerState":{"type":"string","enum":["on","off"],"description":"An indicator to determine if the device is `on` or `off`.","example":"off"}}},{"type":"object","properties":{"brightness":{"$ref":"#/components/schemas/Brightness"}}},{"type":"object","properties":{"color":{"$ref":"#/components/schemas/Color"}}}]}}}}}},{"$ref":"#/components/schemas/StatusResponse"}]},"ErrorResponse":{"type":"object","properties":{"message":{"type":"string","description":"The message value will be the error message.","example":"Invalid API Key"},"status":{"type":"integer","description":"The HTTP status code of the response.","example":401}}},"StatusResponse":{"type":"object","readOnly":true,"description":"The response message and code to provide additional status info.","properties":{"message":{"type":"string","description":"The message value will be `Success` when the request process successfully. Or it will be the error message.","example":"Success"},"code":{"type":"integer","description":"The HTTP status code of the response. The code value will be `200` when the request process successfully.","example":200}}},"DeviceDataObject":{"properties":{"data":{"type":"object","description":"The response body.","properties":{"devices":{"type":"array","description":"Returns your devices supported by the Govee Developer API.","items":{"$ref":"#/components/schemas/DeviceObject"}}}}}},"ApplianceDataObject":{"properties":{"data":{"type":"object","description":"The response body.","properties":{"devices":{"type":"array","description":"Returns your appliances supported by the Govee Developer API.","items":{"$ref":"#/components/schemas/ApplianceObject"}}}}}},"ApplianceObject":{"type":"object","required":["model","device","deviceName","controllable","retrievable","supportCmds","properties"],"properties":{"device":{"$ref":"#/components/schemas/MACAddress"},"model":{"$ref":"#/components/schemas/ApplianceModel"},"deviceName":{"type":"string","description":"The friendly name of the device as its defined in the Govee Home App.","example":"Smart Air Purifier"},"controllable":{"type":"boolean","readOnly":true,"description":"Controllable will be `true` when the device support commands to control.","example":true},"retrievable":{"type":"boolean","readOnly":true,"description":"Retrievable will be `true` when the device support querying the current device state.","example":true},"supportCmds":{"type":"array","readOnly":true,"description":"Commands supported by the device.","example":["turn","mode"],"items":{"type":"string","enum":["turn","mode"],"example":"turn"}},"properties":{"type":"object","readOnly":true,"description":"The properties of the device.","properties":{"mode":{"$ref":"#/components/schemas/Mode"}}}}},"DeviceObject":{"type":"object","required":["model","device","deviceName","controllable","retrievable","supportCmds","properties"],"properties":{"device":{"$ref":"#/components/schemas/MACAddress"},"model":{"$ref":"#/components/schemas/Model"},"deviceName":{"type":"string","description":"The friendly name of the device as its defined in the Govee Home App.","example":"Smart Flood Lights"},"controllable":{"type":"boolean","readOnly":true,"description":"Controllable will be `true` when the device support commands to control.","example":true},"retrievable":{"type":"boolean","readOnly":true,"description":"Retrievable will be `true` when the device support querying the current device state.","example":true},"supportCmds":{"type":"array","readOnly":true,"description":"Commands supported by the device.","example":["turn","brightness","color","colorTem"],"items":{"type":"string","enum":["turn","brightness","color","colorTem"]}},"properties":{"type":"object","readOnly":true,"description":"The properties of the device. For example, the supported `colorTem` range supported by the device.","required":["colorTem"],"properties":{"colorTem":{"type":"object","description":"Color Temperature in Kelvin","required":["range"],"properties":{"range":{"type":"object","description":"Supported color temperature range for the device","required":["min","max"],"properties":{"min":{"type":"integer","description":"The min color temperature supported by the device","example":2700},"max":{"type":"integer","description":"The max color temperature supported by the device","example":6500}}}}}}}}},"CMDObject":{"type":"object","required":["cmd","name","value"],"properties":{"cmd":{"type":"object","description":"The command object to send to the device.","properties":{"name":{"type":"string","description":"The name of the command.","enum":["turn","brightness","color","colorTem"],"example":"turn"},"value":{"description":"The value to send for the command. Select the corresponding option below that matches the command name.","anyOf":[{"$ref":"#/components/schemas/Turn"},{"$ref":"#/components/schemas/Brightness"},{"$ref":"#/components/schemas/Color"},{"$ref":"#/components/schemas/ColorTemperature"}],"discriminator":{"propertyName":"name"}}}}}},"CMDObjectAppliance":{"type":"object","required":["cmd","name","value"],"properties":{"cmd":{"type":"object","description":"The command object to send to the device.","properties":{"name":{"type":"string","description":"The name of the command.","enum":["turn","mode"],"example":"turn"},"value":{"description":"The value to send for the command. Select the corresponding option below that matches the command name.","anyOf":[{"$ref":"#/components/schemas/Turn"},{"type":"integer","title":"Mode","description":"The value that matches the mode's option. You can obtain the supported options using the [List Appliances](/reference/getappliancedeviceinfo) API.","example":1,"minimum":0}],"discriminator":{"propertyName":"name"}}}}}},"Model":{"type":"string","description":"Product model of the device.","example":"H7060","enum":["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","H6046","H601A","H61A3","H610B","H6047","H7065","H61E1","H6057","H604C","H6065","H605C","H705A","H705B","H7055","H61A5","H6078","H604D","H6168","H6601","H70B1","H61A8"]},"ApplianceModel":{"type":"string","description":"Product model of the appliance.","example":"H7121","enum":["H7121","H7122","H7123","H7120","H7141","H7142","H7130","H7131","H7132","H7150","H7160","H7101","H7111"]},"MACAddress":{"type":"string","description":"MAC address of the device.","example":"0B:B2:CA:30:39:39:29:4F"},"Turn":{"type":"string","description":"Turn On/Off","enum":["on","off"],"example":"on"},"Mode":{"type":"object","description":"The supported modes from the device.","properties":{"options":{"type":"array","description":"The supported options for the models.","items":{"type":"object","properties":{"name":{"type":"string","description":"The name of the supported option.","example":"Low"},"value":{"type":"integer","description":"The value of the supported option.","example":1}}}}}},"Brightness":{"type":"integer","description":"Brightness 0-100","minimum":0,"maximum":100,"example":75},"Color":{"type":"object","description":"Color RGB","properties":{"r":{"type":"integer","description":"The amount of red color","minimum":0,"maximum":255,"example":255},"g":{"type":"integer","description":"The amount of green color","minimum":0,"maximum":255,"example":255},"b":{"type":"integer","description":"The amount of blue color","minimum":0,"maximum":255,"example":255}}},"ColorTemperature":{"type":"integer","description":"Color Temperature (Kelvin)","minimum":2000,"maximum":9000,"example":3000}},"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Govee-API-Key","description":"You can apply for a Govee Developer API Key through the Govee Home App.\nThe key is refreshed every time you apply and will be sent to the email address tied to your Govee Home App account.\n"}}},"security":[{"ApiKeyAuth":[]}],"x-readme":{"explorer-enabled":true,"proxy-enabled":true}}