openapi: 3.1.0
info:
  title: Govee Developer Device Control API
  version: '1.0'
  description: 'The Govee Developer API is a free, cloud REST API for controlling and querying Govee smart lighting and smart-home devices. All requests are made over HTTPS to https://openapi.api.govee.com/router/api/v1 and authenticated with a Govee-API-Key header (the key is issued in the Govee Home App). The API is capability-based: GET /user/devices returns each device''s typed capability list, POST /device/state queries live state, and POST /device/control sends a single typed capability command. Dynamic (light) scenes and user-authored DIY scenes are enumerated with POST /device/scenes and POST /device/diy-scenes, then applied through the control endpoint.

    Endpoints in this document are grounded in the public Govee Developer API v1 reference (developer.govee.com). Request and response schemas are modeled from the documented capability structure; exact per-capability value shapes vary by device and should be read from GET /user/devices.'
  contact:
    name: Govee Developer Platform
    url: https://developer.govee.com/
  license:
    name: Govee Developer API Terms
    url: https://developer.govee.com/
servers:
- url: https://openapi.api.govee.com/router/api/v1
  description: Govee Developer API v1 (cloud, production)
security:
- GoveeApiKey: []
tags:
- name: Device Control
  description: Send capability commands to a device.
paths:
  /device/control:
    post:
      operationId: controlDevice
      summary: Control device
      description: Sends a single typed capability command to a device - for example on_off/powerSwitch to turn power on or off, range/brightness to set brightness, color_setting/colorRgb or colorTemperatureK to set color, dynamic_scene or diy_scene to apply a scene, or segment_color_setting/segmentedColorRgb and segmentedBrightness to address individual RGBIC segments.
      tags:
      - Device Control
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeviceControlRequest'
      responses:
        '200':
          description: Command accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommandResponse'
        '400':
          description: Invalid capability, instance, or value for this device.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    ControlCapability:
      type: object
      required:
      - type
      - instance
      - value
      properties:
        type:
          type: string
          examples:
          - devices.capabilities.on_off
        instance:
          type: string
          examples:
          - powerSwitch
        value:
          description: Control value; its shape depends on the capability. Integer for on_off (0/1) and range/brightness, integer 0-16777215 for colorRgb, Kelvin integer for colorTemperatureK, or an object for segment_color_setting and work_mode.
          oneOf:
          - type: integer
          - type: string
          - type: object
            additionalProperties: true
    CommandResponse:
      type: object
      properties:
        requestId:
          type: string
        code:
          type: integer
          examples:
          - 200
        msg:
          type: string
          examples:
          - success
    DeviceControlRequest:
      type: object
      required:
      - payload
      properties:
        requestId:
          type: string
          description: Client-generated correlation id (a UUID).
        payload:
          type: object
          required:
          - sku
          - device
          - capability
          properties:
            sku:
              type: string
            device:
              type: string
            capability:
              $ref: '#/components/schemas/ControlCapability'
  responses:
    RateLimited:
      description: Rate limit exceeded. The account-wide limit is 10,000 requests per day; a per-device per-minute limit also applies. Inspect the API-RateLimit-* response headers and back off.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CommandResponse'
    Unauthorized:
      description: Missing or invalid Govee-API-Key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CommandResponse'
  securitySchemes:
    GoveeApiKey:
      type: apiKey
      in: header
      name: Govee-API-Key
      description: API key issued in the Govee Home App (Profile > About Us > Apply for API Key).