<!-- BusyBot node reference — https://busybot.net/tools/philips-hue/ -->

> Node: Philips Hue (`philips_hue`) · Action · v1
> Category: Utility · Credentials: Philips Hue OAuth2 (`philipsHueOAuth2`)
> Updated: 2026-08-16

# Philips Hue

> Control Philips Hue smart lights via the Hue Remote API.

## Overview

Philips Hue is a smart lighting system. This tool controls Hue lights via the Philips Hue Remote API (cloud). It supports retrieving individual light details, listing all lights on a bridge, updating light state (on/off, brightness, color, hue, saturation, color temperature, effects, transitions), and deleting lights from the bridge. Requires OAuth2 authentication with the Philips Hue developer portal.

**Category:** Utility  
**Tool Name:** `philips_hue`  
**Version:** 1

**Appearance:** Icon: `lucide-Lightbulb` | Color: `#4A90D9`

## Node Type

**Action** — processes input items and produces output

## Input / Output

| Direction | Port(s) |
|-----------|--------|
| Input | `Input` |
| Output | `Output`, `Error` |

## Credentials

This tool requires **Philips Hue OAuth2** credentials.
See the [Credentials Guide](https://busybot.net/credentials/philips-hue-oauth2/) for setup instructions.

### Resources

| Resource | Value |
|----------|-------|
| Light | `light` |

### Operations

| Operation | Value | Description |
|-----------|-------|-------------|
| Delete | `delete` | Delete a light from the bridge |
| Get | `get` | Retrieve a light |
| Get Many | `getAll` | Retrieve many lights |
| Update | `update` | Update a light state |

### Parameters

#### Light: Get

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Light ID | `string` | Yes | — | The numeric ID of the light on the Hue bridge. Supports expressions like {{ $json.lightId }}. |

#### Light: Get Many

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Return All | `boolean` | No | `false` | Whether to return all results or only up to a given limit. |
| Limit | `number` | No | `100` | Max number of results to return. Between 1 and 500. _(shown when Return All is `false`)_ |

#### Light: Update

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Light ID | `string` | Yes | — | The numeric ID of the light on the Hue bridge. Pick from the list to see lights with their room names. Supports expressions. |
| On | `boolean` | Yes | `true` | On/Off state of the light. Supports expressions. |
| Additional Fields | `collection` | No | `{}` | Additional light properties to update. Add only the ones you want to change — anything left empty is not sent. |
| — Alert Effect | `options` | No | — | The alert effect -- a temporary change to the bulb's state. |
| | | | | Options: `none` (the light is not performing an alert effect), `select` (one breathe cycle), `lselect` (breathe cycles for 15 seconds or until an alert of `none` is received) |
| — Brightness | `number` | No | `100` | The brightness value to set the light to. Scale from 1 (min) to 254 (max). |
| — Brightness Increments | `number` | No | `0` | Increments or decrements the brightness. Ignored if Brightness is provided. Between -254 and 254. |
| — Color Temperature | `number` | No | `0` | The Mired color temperature. 153 (6500K) to 500 (2000K). |
| — Color Temperature Increments | `number` | No | `0` | Increments or decrements the color temperature. Ignored if Color Temperature is provided. |
| — Coordinates | `string` | No | — | CIE color space x,y coordinates. Both values between 0 and 1. Enter them comma-separated, e.g. `0.64394,0.33069`. |
| — Coordinates Increments | `string` | No | — | Increments or decrements the CIE coordinates. Ignored if Coordinates is provided. Max value [0.5, 0.5]. Comma-separated, e.g. `0.5,0.5`. |
| — Dynamic Effect | `options` | No | — | The dynamic effect of the light. |
| | | | | Options: `none`, `colorloop` |
| — Hue | `number` | No | `0` | The hue value (0-65535). Both 0 and 65535 are red, 25500 is green, 46920 is blue. |
| — Hue Increments | `number` | No | `0` | Increments or decrements the hue. Ignored if Hue is provided. Between -65534 and 65534. |
| — Saturation | `number` | No | `0` | Saturation of the light. 254 is most saturated (colored), 0 is least (white). |
| — Saturation Increments | `number` | No | `0` | Increments or decrements the saturation. Ignored if Saturation is provided. Between -254 and 254. |
| — Transition Time | `number` | No | `4` | The duration in seconds of the transition from the light's current state to the new state. |

#### Light: Delete

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Light ID | `string` | Yes | — | The numeric ID of the light on the Hue bridge. Supports expressions like {{ $json.lightId }}. |

#### All Operations

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Philips Hue Account | `credential` | No | — | Connect your Philips Hue account via OAuth2. Pick the connected account this node should use. |
| Max Concurrency | `number` | No | `5` | Maximum number of items to process concurrently. Lower values recommended for Hue bridge rate limits. |

## Output Data

The Hue API response is **merged onto the input item JSON** — the incoming fields pass through unchanged, and binary data is forwarded.

| Operation | Output |
|-----------|--------|
| `get` | One output item per input item, carrying the light's full record (name, state, type, model and so on). |
| `getAll` | **Fans out**: one output item per light on the bridge, each carrying `id` (the light's numeric ID on the bridge) plus that light's own fields. With Return All off, only the first *Limit* lights are emitted. |
| `update` | One output item per input item. The bridge's per-property acknowledgements are merged together, so the item carries one key per property that was actually changed. |
| `delete` | One output item per input item, carrying the bridge's delete response. |

Because `getAll` turns one input item into many, index-based pairing with the upstream node no longer holds downstream. Reference the result by expression, e.g. `{{ $json.id }}` or `{{ $json.name }}`.

## Usage Examples

- Turn on a Philips Hue light
- Set brightness of a Hue light to 50%
- Get details of all lights on the Hue bridge
- Change light color temperature to warm white
- Delete a light from the Hue bridge
- Set a colorloop effect on a Hue light

## Example Configuration

Read one light's state:

```json
{
  "type": "philips_hue",
  "parameters": {
    "resource": "light",
    "operation": "get",
    "lightId": "1"
  }
}
```

List every light on the bridge — one output item per light:

```json
{
  "type": "philips_hue",
  "parameters": {
    "resource": "light",
    "operation": "getAll",
    "returnAll": true,
    "maxConcurrency": 3
  }
}
```

Turn a light on with a specific brightness and a gentle fade:

```json
{
  "type": "philips_hue",
  "parameters": {
    "resource": "light",
    "operation": "update",
    "lightId": "1",
    "on": true,
    "additionalFields": {
      "bri": 127,
      "transitiontime": 4
    }
  }
}
```

Set a warm colour temperature on a light chosen by the incoming item:

```json
{
  "type": "philips_hue",
  "parameters": {
    "resource": "light",
    "operation": "update",
    "lightId": "{{ $json.lightId }}",
    "on": true,
    "additionalFields": {
      "ct": 300,
      "bri": 150,
      "transitiontime": 5
    }
  }
}
```

Set a blue, fully saturated colour by hue and saturation:

```json
{
  "type": "philips_hue",
  "parameters": {
    "resource": "light",
    "operation": "update",
    "lightId": "2",
    "on": true,
    "additionalFields": {
      "hue": 46920,
      "sat": 254,
      "bri": 200
    }
  }
}
```

Combine an alert, a colour-loop effect and CIE coordinates:

```json
{
  "type": "philips_hue",
  "parameters": {
    "resource": "light",
    "operation": "update",
    "lightId": "4",
    "on": true,
    "additionalFields": {
      "alert": "select",
      "bri": 180,
      "effect": "colorloop",
      "xy": "0.3,0.3",
      "transitiontime": 20
    }
  }
}
```

Remove a light from the bridge:

```json
{
  "type": "philips_hue",
  "parameters": {
    "resource": "light",
    "operation": "delete",
    "lightId": "3"
  }
}
```

### Error Handling

| Mode | Behavior |
|------|----------|
| **stop** | Halts workflow on first error |
| **continue** | Skips failed items, passes successful ones through |
| **errorPort** | Routes failed items to Error output port |

## Tips

Control Philips Hue smart lights -- turn on/off, adjust brightness, color, effects, and manage lights on a Hue bridge.

### Behavior notes

- **Transition Time is in seconds here.** Enter `4` for a four-second fade; the node converts it to the units the bridge expects.
- **Coordinates are typed as text.** Enter `x,y` comma-separated (for example `0.64394,0.33069`) and the node converts it to the pair the bridge wants. The same applies to Coordinates Increments.
- **Empty additional fields are dropped**, so adding a field and leaving it blank is the same as not adding it at all.
- **Absolute values beat increments.** Brightness, Color Temperature, Hue and Saturation each override their matching Increments field when both are set.
- **Colour needs the light on.** Update always sends the On state alongside your changes, so leaving **On** off will turn the light off no matter what colour you asked for.
- **Keep concurrency low.** The Hue bridge rate-limits aggressively; the default of 5 is a sensible ceiling.

### Parameter dependencies

1. `operation` becomes available once `resource` is `light`
2. `lightId` is required for `get`, `update` and `delete`
3. `limit` only appears when `returnAll` is `false` and `operation` is `getAll`
4. `on` and `additionalFields` only appear for `update`