# Light

API to manage light services. These are offered by devices with lighting capabilities.

## List lights.

> List all available lights.

```json
{"openapi":"3.0.3","info":{"title":"Hue CLIP API","version":"v2"},"tags":[{"name":"Light","description":"API to manage light services. These are offered by devices with lighting capabilities."}],"servers":[{"url":"https://{bridgeInternalIPAddress}","description":"Your Home Bridge","variables":{"bridgeInternalIPAddress":{"default":"192.168.1.0","description":"Use the broker server discover process by visiting https://discovery.meethue.com\nto discover the IP address of the bridge on your network\n"}}}],"security":[{"HueApplicationKey":[]}],"components":{"securitySchemes":{"HueApplicationKey":{"type":"apiKey","in":"header","name":"hue-application-key"}},"schemas":{"ApiResponse":{"type":"object","required":["errors","data"],"properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error"}},"data":{"type":"array","items":{"type":"object"}}}},"Error":{"type":"object","required":["description"],"properties":{"description":{"type":"string","description":"a human-readable explanation specific to this occurrence of the problem."}}},"LightGet":{"type":"object","allOf":[{"$ref":"#/components/schemas/ResourceOwned"},{"type":"object","required":["metadata","identify","service_id","on","mode"],"properties":{"metadata":{"type":"object","description":"Deprecated, use metadata on device level","required":["name","archetype","function"],"properties":{"name":{"type":"string","description":"Human readable name of a resource"},"archetype":{"$ref":"#/components/schemas/LightArchetype"},"function":{"type":"string","description":"Function of the light service","enum":["functional","decorative","mixed","unknown"]},"fixed_mired":{"type":"integer","minimum":153,"maximum":500,"description":"A fixed mired value of the white lamp"}}},"identify":{"type":"object","description":"Triggers identification sequence on the light"},"service_id":{"type":"integer","minimum":0,"description":"Service identification number. 0 indicates service of a single instance"},"on":{"$ref":"#/components/schemas/On"},"dimming":{"type":"object","properties":{"brightness":{"$ref":"#/components/schemas/Brightness"},"min_dim_level":{"type":"number","minimum":0,"maximum":100,"description":"Percentage of the maximum lumen the device outputs on minimum brightness"}}},"color_temperature":{"type":"object","properties":{"mirek":{"type":"integer","minimum":153,"maximum":500,"description":"color temperature in mirek or null when the light color is not in the ct spectrum"},"mirek_valid":{"type":"boolean","description":"Indication whether the value presented in mirek is valid"},"mirek_schema":{"type":"object","properties":{"mirek_minimum":{"type":"integer","minimum":153,"maximum":500,"description":"minimum color temperature this light supports"},"mirek_maximum":{"type":"integer","minimum":153,"maximum":500,"description":"maximum color temperature this light supports"}}}}},"color":{"type":"object","properties":{"xy":{"$ref":"#/components/schemas/GamutPosition"},"gamut":{"type":"object","description":"Color gamut of color bulb. Some bulbs do not properly return the Gamut information. In this case this is not present.","properties":{"red":{"$ref":"#/components/schemas/GamutPosition"},"green":{"$ref":"#/components/schemas/GamutPosition"},"blue":{"$ref":"#/components/schemas/GamutPosition"}}},"gamut_type":{"type":"string","description":"The gammut types supported by hue – A Gamut of early Philips color-only products – B Limited gamut of first Hue color products – C Richer color gamut of Hue white and color ambiance products – other Color gamut of non-hue products with non-hue gamuts resp w/o gamut","enum":["A","B","C","other"]}}},"dynamics":{"type":"object","properties":{"status":{"$ref":"#/components/schemas/SupportedDynamicStatus"},"status_values":{"type":"array","description":"Statuses in which a lamp could be when playing dynamics.","items":{"$ref":"#/components/schemas/SupportedDynamicStatus"}},"speed":{"type":"number","minimum":0,"maximum":1,"description":"speed of dynamic palette or effect. The speed is valid for the dynamic palette if the status is dynamic_palette or for the corresponding effect listed in status. In case of status none, the speed is not valid"},"speed_valid":{"type":"boolean","description":"Indicates whether the value presented in speed is valid"}}},"alert":{"type":"object","description":"Joined alert control","properties":{"action_values":{"type":"array","description":"Supported alert actions for this light.","items":{"type":"string"}}}},"signaling":{"type":"object","description":"Feature containing signaling properties.","properties":{"signal_values":{"type":"array","items":{"$ref":"#/components/schemas/SupportedSignals"}},"estimated_end":{"type":"integer","description":"Timestamp indicating when the active signal is expected to end. Value is not set if there is no_signal"},"colors":{"type":"array","description":"Colors that were provided for the active effect.","items":{"$ref":"#/components/schemas/Color"}}}},"mode":{"type":"string","enum":["normal","streaming"]},"gradient":{"type":"object","allOf":[{"$ref":"#/components/schemas/Gradient"},{"type":"object","properties":{"points_capable":{"type":"integer","description":"Number of color points that gradient lamp is capable of showing with gradience."},"mode_values":{"type":"array","description":"Modes a gradient device can deploy the gradient palette of colors","items":{"$ref":"#/components/schemas/SupportedGradientMode"}},"pixel_count":{"type":"integer","description":"Number of pixels in the device"}}}]},"effects":{"type":"object","description":"Basic feature containing effect properties.","properties":{"status":{"$ref":"#/components/schemas/SupportedEffects"},"status_values":{"type":"array","description":"Possible status values in which a light could be when playing an effect.","items":{"$ref":"#/components/schemas/SupportedEffects"}},"effect":{"$ref":"#/components/schemas/SupportedEffects"},"effect_values":{"type":"array","description":"Possible status values in which a light could be when playing an effect.","items":{"$ref":"#/components/schemas/SupportedEffects"}}}},"effects_v2":{"$ref":"#/components/schemas/EffectsV2"},"timed_effects":{"type":"object","description":"Basic feature containing timed effect properties.","properties":{"effect":{"$ref":"#/components/schemas/SupportedTimedEffects"},"effect_values":{"type":"array","description":"Possible timed effect values you can set in a light","items":{"$ref":"#/components/schemas/SupportedTimedEffects"}},"status":{"$ref":"#/components/schemas/SupportedTimedEffects"},"status_values":{"type":"array","description":"Possible status values in which a light could be when playing a timed effect.","items":{"$ref":"#/components/schemas/SupportedTimedEffects"}},"duration":{"type":"integer","description":"Duration is mandatory when timed effect is set except for no_effect. Resolution decreases for a larger duration. e.g Effects with duration smaller than a minute will be rounded to a resolution of 1s, while effects with duration larger than an hour will be arounded up to a resolution of 300s. Duration has a max of 21600000 ms."}}},"powerup":{"type":"object","description":"Feature containing properties to configure powerup behaviour of a lightsource.","properties":{"preset":{"type":"string","description":"When setting the custom preset the additional properties can be set. For all other presets, no other properties can be included.","enum":["safety","powerfail","last_on_state","custom"]},"configured":{"type":"boolean","description":"Indicates if the shown values have been configured in the lightsource."},"on":{"type":"object","properties":{"mode":{"type":"string","description":"State to activate after powerup.\nOn will use the value specified in the “on” property.\nWhen setting mode “on”, the on property must be included.\nToggle will alternate between on and off on each subsequent power toggle.\nPrevious will return to the state it was in before powering off.\n","enum":["on","toggle","previous"]},"on":{"$ref":"#/components/schemas/On"}}},"dimming":{"type":"object","properties":{"mode":{"type":"string","description":"Dimming will set the brightness to the specified value after power up.\nWhen setting mode “dimming”, the dimming property must be included.\nPrevious will set brightness to the state it was in before powering off.\n","enum":["dimming","previous"]},"dimming":{"$ref":"#/components/schemas/Dimming"},"color":{"type":"object","properties":{"mode":{"type":"string","enum":["color_temperature","color","previous"],"description":"State to activate after powerup. Availability of “color_temperature” and “color” modes depend on the capabilities of the lamp. Colortemperature will set the colortemperature to the specified value after power up. When setting color_temperature, the color_temperature property must be included Color will set the color tot he specified value after power up. When setting color mode, the color property must be included Previous will set color to the state it was in before powering off."},"color_temperature":{"type":"object","properties":{"mirek":{"$ref":"#/components/schemas/Mirek"},"color":{"$ref":"#/components/schemas/Color"}}}}}}}}},"product_data":{"type":"object","description":"Product data about the light.","properties":{"function":{"type":"string","description":"Function of the light source.","enum":["functional","decorative","mixed","unknown"]}}},"geometry":{"type":"object","description":"Geometry information for pixel-addressable lights such as gradient strips.","properties":{"pixel_positions":{"type":"array","description":"Ordered list of pixel positions for this light. Empty for non-gradient lights.","items":{"type":"object","properties":{"x":{"type":"number"},"y":{"type":"number"},"z":{"type":"number"}}}}}}}}]},"ResourceOwned":{"type":"object","description":"Common resource properties including the owner","allOf":[{"$ref":"#/components/schemas/Resource"},{"type":"object","required":["owner"],"properties":{"owner":{"$ref":"#/components/schemas/ResourceIdentifier"}}}]},"Resource":{"type":"object","description":"Common resource properties","required":["type","id"],"properties":{"type":{"type":"string","description":"Type of the supported resources"},"id":{"type":"string","description":"Unique identifier representing a specific resource instance","pattern":"^[0-9a-f]{8}-([0-9a-f]{4}-){3}[0-9a-f]{12}$"},"id_v1":{"type":"string","description":"Clip v1 resource identifier","pattern":"^(\\/[a-z]{4,32}\\/[0-9a-zA-Z-]{1,32})?$"}}},"ResourceIdentifier":{"type":"object","required":["rid","rtype"],"properties":{"rid":{"type":"string","description":"The unique id of the referenced resource","pattern":"^[0-9a-f]{8}-([0-9a-f]{4}-){3}[0-9a-f]{12}$"},"rtype":{"type":"string","description":"The type of the referenced resource","enum":["device","bridge_home","room","zone","light","button","relative_rotary","temperature","light_level","motion","camera_motion","entertainment","contact","tamper","grouped_light","device_power","zigbee_bridge_connectivity","zigbee_connectivity","zgp_connectivity","bridge","zigbee_device_discovery","homekit","matter","matter_fabric","scene","entertainment_configuration","public_image","auth_v1","behavior_script","behavior_instance","geofence","geofence_client","geolocation","smart_scene","grouped_motion","grouped_light_level"]}}},"LightArchetype":{"type":"string","description":"Light archetype","enum":["unknown_archetype","classic_bulb","sultan_bulb","flood_bulb","spot_bulb","candle_bulb","luster_bulb","pendant_round","pendant_long","ceiling_round","ceiling_square","floor_shade","floor_lantern","table_shade","recessed_ceiling","recessed_floor","single_spot","double_spot","table_wash","wall_lantern","wall_shade","flexible_lamp","ground_spot","wall_spot","plug","hue_go","hue_lightstrip","hue_iris","hue_bloom","bollard","wall_washer","hue_play","vintage_bulb","vintage_candle_bulb","ellipse_bulb","triangle_bulb","small_globe_bulb","large_globe_bulb","edison_bulb","christmas_tree","string_light","hue_centris","hue_lightstrip_tv","hue_lightstrip_pc","hue_tube","hue_signe","pendant_spot","ceiling_horizontal","ceiling_tube"]},"On":{"type":"object","required":["on"],"properties":{"on":{"type":"boolean","description":"On/Off state of the light on=true, off=false"}}},"Brightness":{"type":"number","minimum":0,"maximum":100,"description":"Brightness percentage. value cannot be 0, writing 0 changes it to lowest possible brightness"},"GamutPosition":{"type":"object","description":"CIE XY gamut position","required":["x","y"],"properties":{"x":{"type":"number","minimum":0,"maximum":1,"description":"X position in color gamut"},"y":{"type":"number","minimum":0,"maximum":1,"description":"y position in color gamut"}}},"SupportedDynamicStatus":{"type":"string","description":"Current status of the lamp with dynamics.","enum":["dynamic_palette","none"]},"SupportedSignals":{"type":"string","description":"Indicates which signal is currently active.","enum":["no_signal","on_off","on_off_color","alternating"]},"Color":{"type":"object","required":["xy"],"properties":{"xy":{"$ref":"#/components/schemas/GamutPosition"}}},"Gradient":{"type":"object","description":"Basic feature containing gradient properties.","properties":{"points":{"type":"array","description":"Collection of gradients points. For control of the gradient points through a PUT a minimum of 2 points need to be provided.","items":{"$ref":"#/components/schemas/Color"},"maxItems":5},"mode":{"$ref":"#/components/schemas/SupportedGradientMode"}}},"SupportedGradientMode":{"type":"string","description":"Mode in which the points are currently being deployed. If not provided during PUT/POST it will be defaulted to interpolated_palette","enum":["interpolated_palette","interpolated_palette_mirrored","random_pixelated"]},"SupportedEffects":{"type":"string","enum":["prism","opal","glisten","sparkle","fire","candle","no_effect","underwater","cosmos","sunbeam","enchant"]},"EffectsV2":{"type":"object","description":"Extended effect control with support for custom color, color temperature, and speed parameters.\nThis property is present on lights that support the newer effects engine and allows fine-grained\ncontrol over effect appearance beyond what the basic `effects` property provides.\n","properties":{"action":{"type":"object","writeOnly":true,"description":"Set effect with optional parameters.","properties":{"effect":{"$ref":"#/components/schemas/SupportedEffects"},"parameters":{"$ref":"#/components/schemas/EffectsV2Parameters"}}},"status":{"type":"object","readOnly":true,"description":"Current effect status and active parameters.","properties":{"effect":{"readOnly":true,"$ref":"#/components/schemas/SupportedEffects"},"effect_values":{"readOnly":true,"type":"array","description":"Possible effect values supported by this light.","items":{"$ref":"#/components/schemas/SupportedEffects"}},"parameters":{"$ref":"#/components/schemas/EffectsV2Parameters"}}}}},"EffectsV2Parameters":{"type":"object","description":"Parameters for controlling the appearance of an active effect.","properties":{"color":{"$ref":"#/components/schemas/Color"},"color_temperature":{"type":"object","properties":{"mirek":{"$ref":"#/components/schemas/Mirek"},"mirek_valid":{"type":"boolean","readOnly":true,"description":"Indication whether the mirek value is valid for this effect"}}},"speed":{"type":"number","minimum":0,"maximum":1,"description":"Speed of the effect animation. 0.0 is slowest, 1.0 is fastest."}}},"Mirek":{"type":"integer","minimum":153,"maximum":500,"description":"color temperature in mirek or null when the light color is not in the ct spectrum"},"SupportedTimedEffects":{"type":"string","description":"Current status values the light is in regarding timed effects","enum":["sunrise","sunset","no_effect"]},"Dimming":{"type":"object","required":["brightness"],"properties":{"brightness":{"$ref":"#/components/schemas/Brightness"}}},"ErrorResponse":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error"}}}}},"responses":{"Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Forbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"MethodNotAllowed":{"description":"Method Not Allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotAcceptable":{"description":"Not Acceptable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Conflict":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"TooManyRequests":{"description":"Too Many Requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"InternalServerError":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"ServiceUnavailable":{"description":"Service Unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"InsufficientStorage":{"description":"Insufficient Storage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/clip/v2/resource/light":{"get":{"operationId":"getLights","summary":"List lights.","description":"List all available lights.","tags":["Light"],"responses":{"200":{"description":"Light Success Response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/LightGet"}}}}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"406":{"$ref":"#/components/responses/NotAcceptable"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"},"507":{"$ref":"#/components/responses/InsufficientStorage"}}}}}}
```

## Get light

> Get details of a single light from its given \`{lightId}\`.

```json
{"openapi":"3.0.3","info":{"title":"Hue CLIP API","version":"v2"},"tags":[{"name":"Light","description":"API to manage light services. These are offered by devices with lighting capabilities."}],"servers":[{"url":"https://{bridgeInternalIPAddress}","description":"Your Home Bridge","variables":{"bridgeInternalIPAddress":{"default":"192.168.1.0","description":"Use the broker server discover process by visiting https://discovery.meethue.com\nto discover the IP address of the bridge on your network\n"}}}],"security":[{"HueApplicationKey":[]}],"components":{"securitySchemes":{"HueApplicationKey":{"type":"apiKey","in":"header","name":"hue-application-key"}},"schemas":{"ApiResponse":{"type":"object","required":["errors","data"],"properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error"}},"data":{"type":"array","items":{"type":"object"}}}},"Error":{"type":"object","required":["description"],"properties":{"description":{"type":"string","description":"a human-readable explanation specific to this occurrence of the problem."}}},"LightGet":{"type":"object","allOf":[{"$ref":"#/components/schemas/ResourceOwned"},{"type":"object","required":["metadata","identify","service_id","on","mode"],"properties":{"metadata":{"type":"object","description":"Deprecated, use metadata on device level","required":["name","archetype","function"],"properties":{"name":{"type":"string","description":"Human readable name of a resource"},"archetype":{"$ref":"#/components/schemas/LightArchetype"},"function":{"type":"string","description":"Function of the light service","enum":["functional","decorative","mixed","unknown"]},"fixed_mired":{"type":"integer","minimum":153,"maximum":500,"description":"A fixed mired value of the white lamp"}}},"identify":{"type":"object","description":"Triggers identification sequence on the light"},"service_id":{"type":"integer","minimum":0,"description":"Service identification number. 0 indicates service of a single instance"},"on":{"$ref":"#/components/schemas/On"},"dimming":{"type":"object","properties":{"brightness":{"$ref":"#/components/schemas/Brightness"},"min_dim_level":{"type":"number","minimum":0,"maximum":100,"description":"Percentage of the maximum lumen the device outputs on minimum brightness"}}},"color_temperature":{"type":"object","properties":{"mirek":{"type":"integer","minimum":153,"maximum":500,"description":"color temperature in mirek or null when the light color is not in the ct spectrum"},"mirek_valid":{"type":"boolean","description":"Indication whether the value presented in mirek is valid"},"mirek_schema":{"type":"object","properties":{"mirek_minimum":{"type":"integer","minimum":153,"maximum":500,"description":"minimum color temperature this light supports"},"mirek_maximum":{"type":"integer","minimum":153,"maximum":500,"description":"maximum color temperature this light supports"}}}}},"color":{"type":"object","properties":{"xy":{"$ref":"#/components/schemas/GamutPosition"},"gamut":{"type":"object","description":"Color gamut of color bulb. Some bulbs do not properly return the Gamut information. In this case this is not present.","properties":{"red":{"$ref":"#/components/schemas/GamutPosition"},"green":{"$ref":"#/components/schemas/GamutPosition"},"blue":{"$ref":"#/components/schemas/GamutPosition"}}},"gamut_type":{"type":"string","description":"The gammut types supported by hue – A Gamut of early Philips color-only products – B Limited gamut of first Hue color products – C Richer color gamut of Hue white and color ambiance products – other Color gamut of non-hue products with non-hue gamuts resp w/o gamut","enum":["A","B","C","other"]}}},"dynamics":{"type":"object","properties":{"status":{"$ref":"#/components/schemas/SupportedDynamicStatus"},"status_values":{"type":"array","description":"Statuses in which a lamp could be when playing dynamics.","items":{"$ref":"#/components/schemas/SupportedDynamicStatus"}},"speed":{"type":"number","minimum":0,"maximum":1,"description":"speed of dynamic palette or effect. The speed is valid for the dynamic palette if the status is dynamic_palette or for the corresponding effect listed in status. In case of status none, the speed is not valid"},"speed_valid":{"type":"boolean","description":"Indicates whether the value presented in speed is valid"}}},"alert":{"type":"object","description":"Joined alert control","properties":{"action_values":{"type":"array","description":"Supported alert actions for this light.","items":{"type":"string"}}}},"signaling":{"type":"object","description":"Feature containing signaling properties.","properties":{"signal_values":{"type":"array","items":{"$ref":"#/components/schemas/SupportedSignals"}},"estimated_end":{"type":"integer","description":"Timestamp indicating when the active signal is expected to end. Value is not set if there is no_signal"},"colors":{"type":"array","description":"Colors that were provided for the active effect.","items":{"$ref":"#/components/schemas/Color"}}}},"mode":{"type":"string","enum":["normal","streaming"]},"gradient":{"type":"object","allOf":[{"$ref":"#/components/schemas/Gradient"},{"type":"object","properties":{"points_capable":{"type":"integer","description":"Number of color points that gradient lamp is capable of showing with gradience."},"mode_values":{"type":"array","description":"Modes a gradient device can deploy the gradient palette of colors","items":{"$ref":"#/components/schemas/SupportedGradientMode"}},"pixel_count":{"type":"integer","description":"Number of pixels in the device"}}}]},"effects":{"type":"object","description":"Basic feature containing effect properties.","properties":{"status":{"$ref":"#/components/schemas/SupportedEffects"},"status_values":{"type":"array","description":"Possible status values in which a light could be when playing an effect.","items":{"$ref":"#/components/schemas/SupportedEffects"}},"effect":{"$ref":"#/components/schemas/SupportedEffects"},"effect_values":{"type":"array","description":"Possible status values in which a light could be when playing an effect.","items":{"$ref":"#/components/schemas/SupportedEffects"}}}},"effects_v2":{"$ref":"#/components/schemas/EffectsV2"},"timed_effects":{"type":"object","description":"Basic feature containing timed effect properties.","properties":{"effect":{"$ref":"#/components/schemas/SupportedTimedEffects"},"effect_values":{"type":"array","description":"Possible timed effect values you can set in a light","items":{"$ref":"#/components/schemas/SupportedTimedEffects"}},"status":{"$ref":"#/components/schemas/SupportedTimedEffects"},"status_values":{"type":"array","description":"Possible status values in which a light could be when playing a timed effect.","items":{"$ref":"#/components/schemas/SupportedTimedEffects"}},"duration":{"type":"integer","description":"Duration is mandatory when timed effect is set except for no_effect. Resolution decreases for a larger duration. e.g Effects with duration smaller than a minute will be rounded to a resolution of 1s, while effects with duration larger than an hour will be arounded up to a resolution of 300s. Duration has a max of 21600000 ms."}}},"powerup":{"type":"object","description":"Feature containing properties to configure powerup behaviour of a lightsource.","properties":{"preset":{"type":"string","description":"When setting the custom preset the additional properties can be set. For all other presets, no other properties can be included.","enum":["safety","powerfail","last_on_state","custom"]},"configured":{"type":"boolean","description":"Indicates if the shown values have been configured in the lightsource."},"on":{"type":"object","properties":{"mode":{"type":"string","description":"State to activate after powerup.\nOn will use the value specified in the “on” property.\nWhen setting mode “on”, the on property must be included.\nToggle will alternate between on and off on each subsequent power toggle.\nPrevious will return to the state it was in before powering off.\n","enum":["on","toggle","previous"]},"on":{"$ref":"#/components/schemas/On"}}},"dimming":{"type":"object","properties":{"mode":{"type":"string","description":"Dimming will set the brightness to the specified value after power up.\nWhen setting mode “dimming”, the dimming property must be included.\nPrevious will set brightness to the state it was in before powering off.\n","enum":["dimming","previous"]},"dimming":{"$ref":"#/components/schemas/Dimming"},"color":{"type":"object","properties":{"mode":{"type":"string","enum":["color_temperature","color","previous"],"description":"State to activate after powerup. Availability of “color_temperature” and “color” modes depend on the capabilities of the lamp. Colortemperature will set the colortemperature to the specified value after power up. When setting color_temperature, the color_temperature property must be included Color will set the color tot he specified value after power up. When setting color mode, the color property must be included Previous will set color to the state it was in before powering off."},"color_temperature":{"type":"object","properties":{"mirek":{"$ref":"#/components/schemas/Mirek"},"color":{"$ref":"#/components/schemas/Color"}}}}}}}}},"product_data":{"type":"object","description":"Product data about the light.","properties":{"function":{"type":"string","description":"Function of the light source.","enum":["functional","decorative","mixed","unknown"]}}},"geometry":{"type":"object","description":"Geometry information for pixel-addressable lights such as gradient strips.","properties":{"pixel_positions":{"type":"array","description":"Ordered list of pixel positions for this light. Empty for non-gradient lights.","items":{"type":"object","properties":{"x":{"type":"number"},"y":{"type":"number"},"z":{"type":"number"}}}}}}}}]},"ResourceOwned":{"type":"object","description":"Common resource properties including the owner","allOf":[{"$ref":"#/components/schemas/Resource"},{"type":"object","required":["owner"],"properties":{"owner":{"$ref":"#/components/schemas/ResourceIdentifier"}}}]},"Resource":{"type":"object","description":"Common resource properties","required":["type","id"],"properties":{"type":{"type":"string","description":"Type of the supported resources"},"id":{"type":"string","description":"Unique identifier representing a specific resource instance","pattern":"^[0-9a-f]{8}-([0-9a-f]{4}-){3}[0-9a-f]{12}$"},"id_v1":{"type":"string","description":"Clip v1 resource identifier","pattern":"^(\\/[a-z]{4,32}\\/[0-9a-zA-Z-]{1,32})?$"}}},"ResourceIdentifier":{"type":"object","required":["rid","rtype"],"properties":{"rid":{"type":"string","description":"The unique id of the referenced resource","pattern":"^[0-9a-f]{8}-([0-9a-f]{4}-){3}[0-9a-f]{12}$"},"rtype":{"type":"string","description":"The type of the referenced resource","enum":["device","bridge_home","room","zone","light","button","relative_rotary","temperature","light_level","motion","camera_motion","entertainment","contact","tamper","grouped_light","device_power","zigbee_bridge_connectivity","zigbee_connectivity","zgp_connectivity","bridge","zigbee_device_discovery","homekit","matter","matter_fabric","scene","entertainment_configuration","public_image","auth_v1","behavior_script","behavior_instance","geofence","geofence_client","geolocation","smart_scene","grouped_motion","grouped_light_level"]}}},"LightArchetype":{"type":"string","description":"Light archetype","enum":["unknown_archetype","classic_bulb","sultan_bulb","flood_bulb","spot_bulb","candle_bulb","luster_bulb","pendant_round","pendant_long","ceiling_round","ceiling_square","floor_shade","floor_lantern","table_shade","recessed_ceiling","recessed_floor","single_spot","double_spot","table_wash","wall_lantern","wall_shade","flexible_lamp","ground_spot","wall_spot","plug","hue_go","hue_lightstrip","hue_iris","hue_bloom","bollard","wall_washer","hue_play","vintage_bulb","vintage_candle_bulb","ellipse_bulb","triangle_bulb","small_globe_bulb","large_globe_bulb","edison_bulb","christmas_tree","string_light","hue_centris","hue_lightstrip_tv","hue_lightstrip_pc","hue_tube","hue_signe","pendant_spot","ceiling_horizontal","ceiling_tube"]},"On":{"type":"object","required":["on"],"properties":{"on":{"type":"boolean","description":"On/Off state of the light on=true, off=false"}}},"Brightness":{"type":"number","minimum":0,"maximum":100,"description":"Brightness percentage. value cannot be 0, writing 0 changes it to lowest possible brightness"},"GamutPosition":{"type":"object","description":"CIE XY gamut position","required":["x","y"],"properties":{"x":{"type":"number","minimum":0,"maximum":1,"description":"X position in color gamut"},"y":{"type":"number","minimum":0,"maximum":1,"description":"y position in color gamut"}}},"SupportedDynamicStatus":{"type":"string","description":"Current status of the lamp with dynamics.","enum":["dynamic_palette","none"]},"SupportedSignals":{"type":"string","description":"Indicates which signal is currently active.","enum":["no_signal","on_off","on_off_color","alternating"]},"Color":{"type":"object","required":["xy"],"properties":{"xy":{"$ref":"#/components/schemas/GamutPosition"}}},"Gradient":{"type":"object","description":"Basic feature containing gradient properties.","properties":{"points":{"type":"array","description":"Collection of gradients points. For control of the gradient points through a PUT a minimum of 2 points need to be provided.","items":{"$ref":"#/components/schemas/Color"},"maxItems":5},"mode":{"$ref":"#/components/schemas/SupportedGradientMode"}}},"SupportedGradientMode":{"type":"string","description":"Mode in which the points are currently being deployed. If not provided during PUT/POST it will be defaulted to interpolated_palette","enum":["interpolated_palette","interpolated_palette_mirrored","random_pixelated"]},"SupportedEffects":{"type":"string","enum":["prism","opal","glisten","sparkle","fire","candle","no_effect","underwater","cosmos","sunbeam","enchant"]},"EffectsV2":{"type":"object","description":"Extended effect control with support for custom color, color temperature, and speed parameters.\nThis property is present on lights that support the newer effects engine and allows fine-grained\ncontrol over effect appearance beyond what the basic `effects` property provides.\n","properties":{"action":{"type":"object","writeOnly":true,"description":"Set effect with optional parameters.","properties":{"effect":{"$ref":"#/components/schemas/SupportedEffects"},"parameters":{"$ref":"#/components/schemas/EffectsV2Parameters"}}},"status":{"type":"object","readOnly":true,"description":"Current effect status and active parameters.","properties":{"effect":{"readOnly":true,"$ref":"#/components/schemas/SupportedEffects"},"effect_values":{"readOnly":true,"type":"array","description":"Possible effect values supported by this light.","items":{"$ref":"#/components/schemas/SupportedEffects"}},"parameters":{"$ref":"#/components/schemas/EffectsV2Parameters"}}}}},"EffectsV2Parameters":{"type":"object","description":"Parameters for controlling the appearance of an active effect.","properties":{"color":{"$ref":"#/components/schemas/Color"},"color_temperature":{"type":"object","properties":{"mirek":{"$ref":"#/components/schemas/Mirek"},"mirek_valid":{"type":"boolean","readOnly":true,"description":"Indication whether the mirek value is valid for this effect"}}},"speed":{"type":"number","minimum":0,"maximum":1,"description":"Speed of the effect animation. 0.0 is slowest, 1.0 is fastest."}}},"Mirek":{"type":"integer","minimum":153,"maximum":500,"description":"color temperature in mirek or null when the light color is not in the ct spectrum"},"SupportedTimedEffects":{"type":"string","description":"Current status values the light is in regarding timed effects","enum":["sunrise","sunset","no_effect"]},"Dimming":{"type":"object","required":["brightness"],"properties":{"brightness":{"$ref":"#/components/schemas/Brightness"}}},"ErrorResponse":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error"}}}}},"responses":{"Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Forbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"MethodNotAllowed":{"description":"Method Not Allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotAcceptable":{"description":"Not Acceptable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Conflict":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"TooManyRequests":{"description":"Too Many Requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"InternalServerError":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"ServiceUnavailable":{"description":"Service Unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"InsufficientStorage":{"description":"Insufficient Storage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/clip/v2/resource/light/{lightId}":{"get":{"operationId":"getLight","summary":"Get light","description":"Get details of a single light from its given `{lightId}`.","tags":["Light"],"parameters":[{"name":"lightId","in":"path","schema":{"type":"string"},"required":true,"description":"ID of the light"}],"responses":{"200":{"description":"Light Success Response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/LightGet"}}}}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"406":{"$ref":"#/components/responses/NotAcceptable"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"},"507":{"$ref":"#/components/responses/InsufficientStorage"}}}}}}
```

## Update light

> Update a single light from its given \`{lightId}\`.

```json
{"openapi":"3.0.3","info":{"title":"Hue CLIP API","version":"v2"},"tags":[{"name":"Light","description":"API to manage light services. These are offered by devices with lighting capabilities."}],"servers":[{"url":"https://{bridgeInternalIPAddress}","description":"Your Home Bridge","variables":{"bridgeInternalIPAddress":{"default":"192.168.1.0","description":"Use the broker server discover process by visiting https://discovery.meethue.com\nto discover the IP address of the bridge on your network\n"}}}],"security":[{"HueApplicationKey":[]}],"components":{"securitySchemes":{"HueApplicationKey":{"type":"apiKey","in":"header","name":"hue-application-key"}},"schemas":{"LightPut":{"type":"object","properties":{"type":{"type":"string","description":"Type of the supported resources (always `light` here)"},"on":{"$ref":"#/components/schemas/On"},"dimming":{"$ref":"#/components/schemas/Dimming"},"dimming_delta":{"$ref":"#/components/schemas/DimmingDelta"},"color_temperature":{"$ref":"#/components/schemas/ColorTemperature"},"color_temperature_delta":{"$ref":"#/components/schemas/ColorTemperatureDelta"},"color":{"$ref":"#/components/schemas/Color"},"dynamics":{"$ref":"#/components/schemas/LightDynamics"},"alert":{"$ref":"#/components/schemas/Alert"},"signaling":{"$ref":"#/components/schemas/Signaling"},"mode":{"type":"string","enum":["normal","streaming"]},"gradient":{"$ref":"#/components/schemas/Gradient"},"effects":{"$ref":"#/components/schemas/Effects"},"effects_v2":{"$ref":"#/components/schemas/EffectsV2"},"timed_effects":{"type":"object","description":"Basic feature containing timed effect properties.","properties":{"effect":{"$ref":"#/components/schemas/SupportedTimedEffects"},"duration":{"type":"integer","description":"Duration is mandatory when timed effect is set except for no_effect. Resolution decreases for a larger duration. e.g Effects with duration smaller than a minute will be rounded to a resolution of 1s, while effects with duration larger than an hour will be arounded up to a resolution of 300s. Duration has a max of 21600000 ms."}}},"powerup":{"$ref":"#/components/schemas/Powerup"}}},"On":{"type":"object","required":["on"],"properties":{"on":{"type":"boolean","description":"On/Off state of the light on=true, off=false"}}},"Dimming":{"type":"object","required":["brightness"],"properties":{"brightness":{"$ref":"#/components/schemas/Brightness"}}},"Brightness":{"type":"number","minimum":0,"maximum":100,"description":"Brightness percentage. value cannot be 0, writing 0 changes it to lowest possible brightness"},"DimmingDelta":{"type":"object","properties":{"action":{"type":"string","enum":["up","down","stop"]},"brightness_delta":{"type":"number","minimum":0,"maximum":100,"description":"Brightness percentage of full-scale increase delta to current dimlevel. Clip at Max-level or Min-level.\n"}}},"ColorTemperature":{"type":"object","properties":{"mirek":{"$ref":"#/components/schemas/Mirek"}}},"Mirek":{"type":"integer","minimum":153,"maximum":500,"description":"color temperature in mirek or null when the light color is not in the ct spectrum"},"ColorTemperatureDelta":{"type":"object","properties":{"action":{"type":"string","enum":["up","down","stop"]},"mirek_delta":{"type":"integer","minimum":0,"maximum":347,"description":"Mirek delta to current mirek. Clip at mirek_minimum and mirek_maximum of mirek_schema."}}},"Color":{"type":"object","required":["xy"],"properties":{"xy":{"$ref":"#/components/schemas/GamutPosition"}}},"GamutPosition":{"type":"object","description":"CIE XY gamut position","required":["x","y"],"properties":{"x":{"type":"number","minimum":0,"maximum":1,"description":"X position in color gamut"},"y":{"type":"number","minimum":0,"maximum":1,"description":"y position in color gamut"}}},"LightDynamics":{"type":"object","properties":{"duration":{"type":"integer","description":"Duration of a light transition or timed effects in ms."},"speed":{"type":"number","minimum":0,"maximum":0,"description":"Speed of dynamic palette or effect.\nThe speed is valid for the dynamic palette if the status is `dynamic_palette` or for the corresponding effect listed in status.\nIn case of status `none`, the speed is not valid.\n"}}},"Alert":{"type":"object","description":"Joined alert control","properties":{"action":{"type":"string"}}},"Signaling":{"type":"object","description":"Feature containing basic signaling properties.","properties":{"signal":{"type":"string","description":"- `no_signal`: No signal is active. Write “no_signal” to stop active signal.\n- `on_off`: Toggles between max brightness and Off in fixed color.\n- `on_off_color`: Toggles between off and max brightness with color provided.\n- `alternating`: Alternates between 2 provided colors.\n","enum":["no_signal","on_off","on_off_color","alternating"]},"duration":{"type":"integer","minimum":0,"maximum":65534000,"description":"Duration has a max of 65534000 ms and a stepsize of 1 second.\nValues inbetween steps will be rounded.\nDuration is ignored for `no_signal`.\n"},"color":{"type":"array","minItems":1,"maxItems":2,"description":"List of colors to apply to the signal (not supported by all signals)","items":{"$ref":"#/components/schemas/Color"}}}},"Gradient":{"type":"object","description":"Basic feature containing gradient properties.","properties":{"points":{"type":"array","description":"Collection of gradients points. For control of the gradient points through a PUT a minimum of 2 points need to be provided.","items":{"$ref":"#/components/schemas/Color"},"maxItems":5},"mode":{"$ref":"#/components/schemas/SupportedGradientMode"}}},"SupportedGradientMode":{"type":"string","description":"Mode in which the points are currently being deployed. If not provided during PUT/POST it will be defaulted to interpolated_palette","enum":["interpolated_palette","interpolated_palette_mirrored","random_pixelated"]},"Effects":{"type":"object","description":"Basic feature containing effect properties.","properties":{"effect":{"$ref":"#/components/schemas/SupportedEffects"}}},"SupportedEffects":{"type":"string","enum":["prism","opal","glisten","sparkle","fire","candle","no_effect","underwater","cosmos","sunbeam","enchant"]},"EffectsV2":{"type":"object","description":"Extended effect control with support for custom color, color temperature, and speed parameters.\nThis property is present on lights that support the newer effects engine and allows fine-grained\ncontrol over effect appearance beyond what the basic `effects` property provides.\n","properties":{"action":{"type":"object","writeOnly":true,"description":"Set effect with optional parameters.","properties":{"effect":{"$ref":"#/components/schemas/SupportedEffects"},"parameters":{"$ref":"#/components/schemas/EffectsV2Parameters"}}},"status":{"type":"object","readOnly":true,"description":"Current effect status and active parameters.","properties":{"effect":{"readOnly":true,"$ref":"#/components/schemas/SupportedEffects"},"effect_values":{"readOnly":true,"type":"array","description":"Possible effect values supported by this light.","items":{"$ref":"#/components/schemas/SupportedEffects"}},"parameters":{"$ref":"#/components/schemas/EffectsV2Parameters"}}}}},"EffectsV2Parameters":{"type":"object","description":"Parameters for controlling the appearance of an active effect.","properties":{"color":{"$ref":"#/components/schemas/Color"},"color_temperature":{"type":"object","properties":{"mirek":{"$ref":"#/components/schemas/Mirek"},"mirek_valid":{"type":"boolean","readOnly":true,"description":"Indication whether the mirek value is valid for this effect"}}},"speed":{"type":"number","minimum":0,"maximum":1,"description":"Speed of the effect animation. 0.0 is slowest, 1.0 is fastest."}}},"SupportedTimedEffects":{"type":"string","description":"Current status values the light is in regarding timed effects","enum":["sunrise","sunset","no_effect"]},"Powerup":{"type":"object","description":"Feature containing properties to configure powerup behaviour of a lightsource.","properties":{"preset":{"type":"string","description":"When setting the custom preset the additional properties can be set. For all other presets, no other properties can be included.","enum":["safety","powerfail","last_on_state","custom"]},"configured":{"type":"boolean","description":"Indicates if the shown values have been configured in the lightsource."},"on":{"type":"object","properties":{"mode":{"type":"string","description":"State to activate after powerup.\nOn will use the value specified in the “on” property.\nWhen setting mode “on”, the on property must be included.\nToggle will alternate between on and off on each subsequent power toggle.\nPrevious will return to the state it was in before powering off.\n","enum":["on","toggle","previous"]},"on":{"$ref":"#/components/schemas/On"}}},"dimming":{"type":"object","properties":{"mode":{"type":"string","description":"Dimming will set the brightness to the specified value after power up.\nWhen setting mode “dimming”, the dimming property must be included.\nPrevious will set brightness to the state it was in before powering off.\n","enum":["dimming","previous"]},"dimming":{"$ref":"#/components/schemas/Brightness"},"color":{"type":"object","properties":{"mode":{"type":"string","enum":["color_temperature","color","previous"],"description":"State to activate after powerup. Availability of “color_temperature” and “color” modes depend on the capabilities of the lamp. Colortemperature will set the colortemperature to the specified value after power up. When setting color_temperature, the color_temperature property must be included Color will set the color tot he specified value after power up. When setting color mode, the color property must be included Previous will set color to the state it was in before powering off."},"color_temperature":{"type":"object","properties":{"mirek":{"$ref":"#/components/schemas/Mirek"},"color":{"$ref":"#/components/schemas/Color"}}}}}}}}},"ApiResponse":{"type":"object","required":["errors","data"],"properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error"}},"data":{"type":"array","items":{"type":"object"}}}},"Error":{"type":"object","required":["description"],"properties":{"description":{"type":"string","description":"a human-readable explanation specific to this occurrence of the problem."}}},"ResourceIdentifier":{"type":"object","required":["rid","rtype"],"properties":{"rid":{"type":"string","description":"The unique id of the referenced resource","pattern":"^[0-9a-f]{8}-([0-9a-f]{4}-){3}[0-9a-f]{12}$"},"rtype":{"type":"string","description":"The type of the referenced resource","enum":["device","bridge_home","room","zone","light","button","relative_rotary","temperature","light_level","motion","camera_motion","entertainment","contact","tamper","grouped_light","device_power","zigbee_bridge_connectivity","zigbee_connectivity","zgp_connectivity","bridge","zigbee_device_discovery","homekit","matter","matter_fabric","scene","entertainment_configuration","public_image","auth_v1","behavior_script","behavior_instance","geofence","geofence_client","geolocation","smart_scene","grouped_motion","grouped_light_level"]}}},"ErrorResponse":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error"}}}}},"responses":{"Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Forbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"MethodNotAllowed":{"description":"Method Not Allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotAcceptable":{"description":"Not Acceptable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Conflict":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"TooManyRequests":{"description":"Too Many Requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"InternalServerError":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"ServiceUnavailable":{"description":"Service Unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"InsufficientStorage":{"description":"Insufficient Storage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/clip/v2/resource/light/{lightId}":{"put":{"operationId":"updateLight","summary":"Update light","description":"Update a single light from its given `{lightId}`.","tags":["Light"],"parameters":[{"name":"lightId","in":"path","schema":{"type":"string"},"required":true,"description":"ID of the light"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LightPut"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ResourceIdentifier"}}}}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"406":{"$ref":"#/components/responses/NotAcceptable"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"},"507":{"$ref":"#/components/responses/InsufficientStorage"}}}}}}
```