canonical: https://jentic.com/apis/openhue.io/openhue

# Openhue Hue CLIP API

The Hue CLIP API v2 is the local REST interface exposed by every Philips Hue Bridge for controlling and observing the connected smart-home devices. It covers lights, scenes, rooms, zones, motion and contact sensors, smart buttons, entertainment configurations, geofencing, behavior scripts, and bridge-level features such as software updates and Matter and HomeKit pairing. Authentication is via the hue-application-key header issued by the bridge, and all calls are made directly to the bridge IP rather than to a cloud endpoint, so the API is local-network-only.

## For AI agents

Control Philips Hue lights, scenes, rooms, sensors, and entertainment configurations through the local Hue Bridge CLIP v2 API.

## Scope

Does not handle non-Hue devices, cloud-relay control, or remote access without a bridge - use for local Philips Hue Bridge control only.

## Capabilities

- Switch lights on or off and adjust brightness, colour, and colour temperature on individual bulbs or groups
- Recall and update scenes to apply preset lighting moods across rooms or zones
- Read motion, contact, temperature, and light-level sensor values for automation triggers
- Configure entertainment areas and stream synchronised lighting effects for media
- Manage rooms, zones, and grouped lights to address devices by physical or logical layout
- Pair the bridge with HomeKit, Matter, or Zigbee accessories and inspect connectivity status

## Use cases

### Voice-Controlled Room Lighting

Build a voice or chat assistant that turns lights on or off, dims them, or recalls a scene by name. The agent looks up the room or zone, finds the grouped_light service, and updates its on, dimming, and color attributes via PUT `/clip/v2/resource/grouped_light/{id}.` Because the bridge speaks locally, latency is well under a second on the home network.

Example prompt: List rooms, find the one named 'Living Room', then PUT to its grouped_light resource setting on.on=false to turn off all lights in that room.

### Automation Triggers from Motion and Contact Sensors

Read the current state of motion, contact, and light-level sensors via GET `/clip/v2/resource/motion` and related endpoints to drive automation logic such as turning hallway lights on at night when motion is detected. The CLIP v2 event model also exposes /eventstream for pushed updates, complementing polled sensor reads.

Example prompt: Get the motion sensor list, find the one in the hallway, and if its motion.motion_report.motion is true, set the hallway grouped_light on to true at 40 percent brightness.

### Entertainment Light Sync for Media

Configure entertainment areas and stream synchronised colour effects to a group of lights for music, gaming, or video. Entertainment configurations are managed under `/clip/v2/resource/entertainment_configuration` and reference the participating light services. This is the local-bridge surface that lights up sync apps and game integrations.

Example prompt: Create a new entertainment_configuration referencing the four lights in the gaming room and start the configuration so it is ready to receive a UDP stream from a sync application.

### AI Agent Smart-Home Control via Jentic

An AI agent can take natural-language commands like 'dim the lights for movie night' and translate them into the right Hue CLIP v2 calls. Through Jentic the hue-application-key is vaulted and the agent works against the bridge IP it is told about, with the operation schema returned for each step rather than parsed from the 133-endpoint spec.

Example prompt: Use Jentic to search for 'recall a hue scene', execute PUT `/clip/v2/resource/scene/{id}` with recall.action='active' for the 'Relax' scene, and confirm the response status is 200.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/clip/v2/resource/light` | List all lights |
| PUT | `/clip/v2/resource/light/{lightId}` | Update a light's on state, brightness, or color |
| GET | `/clip/v2/resource/grouped_light` | List grouped lights for rooms and zones |
| GET | `/clip/v2/resource/scene` | List saved scenes |
| GET | `/clip/v2/resource/room` | List rooms |
| GET | `/clip/v2/resource/motion` | List motion sensors and their state |
| GET | `/clip/v2/resource/entertainment_configuration` | List entertainment configurations |

## Key resources

- **Light** — List, get, and update individual light services.
- **GroupedLight** — Address all lights in a room or zone in a single update.
- **Scene** — List, recall, create, and update lighting scenes.
- **Room and Zone** — Manage physical rooms and logical zones used to group devices.
- **Motion, Contact, Temperature, LightLevel** — Read smart-sensor state for automation logic.
- **Entertainment** — Configure and start entertainment areas for synchronised lighting effects.
- **Bridge** — Inspect bridge state, software updates, Matter, and HomeKit pairing.

## Why Jentic

- **Setup:** Wiring the Hue CLIP API by hand means finding your bridge's internal IP address, sending the hue-application-key header, and picking the right operation from 133 endpoints for local Philips Hue control. Through Jentic you install once, import the Hue CLIP API from the API Directory, store the application key once, and your agent calls it.
- **Permission scoping:** Hue CLIP puts the light id in the URL path (`/clip/v2/resource/light/{lightId}`), so a rule can pin your agent to one light: it can read or set state for that light and nothing else. You choose the operations it may call, so bridge-wide changes like scene or entertainment configuration are not included unless you add them.
- **Credential handling:** Your hue-application-key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'turn off lights in a room' or 'activate a scene', and Jentic returns the matching CLIP v2 operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **LIFX HTTP API** — LIFX exposes a cloud HTTP API for its Wi-Fi smart bulbs; Hue CLIP runs locally against the bridge.
- **Particle Device Cloud API** — Particle manages connected hardware fleets; Hue CLIP focuses on Philips Hue lighting devices on a single bridge.
- **ecobee API** — ecobee exposes thermostat and occupancy data; pair with Hue CLIP for combined lighting and climate routines.

## FAQ

### What authentication does the Hue CLIP API use?

API key authentication via the hue-application-key header, issued by the bridge after a physical button press during pairing. Through Jentic the key is stored in your Jentic One instance and added to each request automatically.

### Can I control individual lights and scenes with the Hue CLIP API?

Yes. PUT `/clip/v2/resource/light/{lightId}` updates a single bulb's on, dimming, color, and color_temperature attributes, and PUT `/clip/v2/resource/scene/{id}` with recall.action='active' activates a saved scene.

### What are the rate limits for the Hue CLIP API?

The bridge enforces a soft cap of around 10 light commands per second to a single light and 1 grouped_light command per second per room or zone. Stay within these limits to avoid dropped commands; entertainment streaming uses a separate UDP channel rather than HTTP.

### How do I turn off all lights in a room with the Hue CLIP API through Jentic?

Search Jentic for 'turn off lights in a room', load PUT `/clip/v2/resource/grouped_light/{id}`, then execute it with on.on=false using the grouped_light id of the target room. Jentic injects the hue-application-key from the vault.

### Does the Hue CLIP API run locally or in the cloud?

The CLIP v2 API runs on the Philips Hue Bridge on the local network, addressed by the bridge's IP. There is no cloud round trip, so latency is low but the agent or its proxy must be reachable from the same network as the bridge.

### Can the Hue CLIP API drive entertainment light sync?

Yes. Create an entertainment_configuration referencing the participating lights and start it; the bridge then accepts a UDP stream of colour values for low-latency effects. The HTTP API handles configuration, the UDP channel handles the streaming.

### Can I limit what my agent is allowed to do with the Hue CLIP API?

Yes. Because Jentic One is self-hosted, your own rules decide which Hue CLIP operations and credentials the agent may use. Since the API puts the light id in the URL path, such as `/clip/v2/resource/light/{lightId}`, you can pin the agent to a single light so it only reads or sets state for that bulb and nothing else. You choose the operations it may call, so bridge-wide changes like scene recall or entertainment configuration stay off limits unless you explicitly allow them.