Smart lighting hub project: talk to a Hue Bridge locally with the v2 API using curl, then Home Assistant

Discuss the Philips Hue Lighting Hub
Post Reply
User avatar
ZerOne
Site Admin
Posts: 292
Joined: Sun Dec 13, 2020 8:21 am

A hands-on walkthrough to see what your Hue Bridge exposes on your own network, then use it in Home Assistant. Based on the community OpenHue API specification (an unofficial OpenAPI description of the bridge's v2 API) and the Home Assistant Hue documentation, as at October 2026. Signify's own developer documentation needs a free developer login, which is why I am citing the OpenHue spec. I have not run every call on every bridge, so check the spec and test on one light first. This is for a bridge on your own network. Do not expose it to the internet.

Step 1: find the bridge

Check your router's DHCP list or Home Assistant's discovered integrations, and give the bridge a DHCP reservation. A cloud lookup page also exists (discovery.meethue.com), which lists bridges seen from your public IP, but it needs internet and is not needed if you know the IP.

Step 2: get an application key

Press the round link button on the bridge, then send the request shortly afterwards (the link button only stays active briefly). The bridge uses HTTPS with a certificate issued by Signify, so curl will complain. For a quick test on your own LAN you can add -k to skip verification (not for anything permanent):

Code: Select all

curl -k -X POST https://BRIDGE_IP/api -H "Content-Type: application/json" -d '{"devicetype":"jsh#test","generateclientkey":true}'
The spec's examples show a successful reply containing a username value (this is the application key) and a client key. If you have not pressed the button, the reply is an error of type 101, "link button not pressed". Keep the key private, like a password, since it gives full control of the bridge.

Step 3: read resources

The v2 API sends the key in a hue-application-key header and lives under /clip/v2/resource. The spec lists resource types including light, grouped_light, scene, smart_scene, room, zone, device, motion, temperature and button:

Code: Select all

curl -k -H "hue-application-key: YOUR_KEY" https://BRIDGE_IP/clip/v2/resource/light
The reply is JSON with a data list. Note each light's id. Rooms and zones link to their lights and a grouped_light you can use to control the whole room.

Step 4: control one light

The spec's example for updating a light is a PUT with an on object:

Code: Select all

curl -k -X PUT -H "hue-application-key: YOUR_KEY" -H "Content-Type: application/json" -d '{"on":{"on":true}}' https://BRIDGE_IP/clip/v2/resource/light/LIGHT_ID
The spec also shows dimming (brightness 0 to 100 percent) and color_temperature fields. Scenes are recalled by sending a PUT to a scene with a recall action (the spec lists active, dynamic_palette and static). Test with one light, then one scene.

Limits: this is a request/response API suited to occasional control. For fast continuous effects such as syncing lights to video or music, Hue has a separate Entertainment API, and you should not hammer the normal one. Also, the spec lists status code 429 (too many requests), which means you are going too fast.

Step 5: Home Assistant

Home Assistant normally discovers the bridge. Otherwise go to Settings > Devices and services > Add integration > Philips Hue and follow the prompts, pressing the link button when asked. Useful notes from the HA docs:
  • Rooms and zones become grouped light entities that are disabled by default. Enable the ones you want.
  • Hue scenes are imported as scene entities, and V2 bridges get a Scene dropdown per room or zone. Create and edit scenes in the Hue app.
  • Hue remotes such as the dimmer switch are stateless and fire hue_event events. You can watch them under Settings > Tools > Events (the docs say button events are rate-limited to one per second).
  • There is a Philips Hue activate scene action with extra options such as dynamic mode and brightness.
Other tools

The OpenHue project publishes an OpenAPI spec and a command line tool (openhue-cli) built on it, useful if you prefer a ready-made CLI to raw curl. Check its README for installation and current version.

Safety

Treat the application key as a secret, do not post it in forums or paste it into untrusted scripts, and if it leaks, look for a way to remove the app authorisation in the Hue app or bridge settings (I have not checked the exact steps). Keep the bridge on a trusted network and do not port-forward it.

Links
Question for the group: what are you automating directly through the Hue local API instead of via Home Assistant, and did you hit any rate limits?
Post Reply

Return to “Philips Hue Discussion”