Hue API V2

The Hue API - referred to as CLIP API ('Connected Lighting Interface Protocol') - has moved to version 2, which is a breaking change over version 1. Version 2 is still a RESTful JSON HTTP API, but the structure has been redefined to make some improvements and allow for new use-cases. Both APIs will exist in parallel for some time to give developers time to upgrade, however any new features (such as dynamics, effects, gradient, events) are only available on V2, and in the long term the V1 API will eventually be removed. The V2 API was released for early access in bridge version 1948086000. Since bridge version 1955082050 the API is released in production, and is exclusively used by all Signify developed applications. The only missing features compared to API V1 are app registration and rule engine. For anything else we recommend to start using API V2 as soon as possible.

Where to start

The best place to start depends on whether you are an existing Hue developer with knowledge on the V1 API, or a completely new Hue developer.

Maturity state

The V2 API has been released in production and is the recommended API to use for any application. Do take these notes into account:

  • Missing features: the API still has two missing features: app registration, and programmable rule engine. For app registration, you should for now keeping using the V1 API as described in our getting started guide. We do not recommend new apps to use the V1 rule engine as it will not be available long term.
  • Deprecated items: a few items that were used during our own internal development remain visible on the API even though they have since been replaced. Be careful to not use any properties that are marked as deprecated in the api reference.

Free to publish

Signify (the company behind Philips Hue) has a quite progressive policy with Hue which will remain unchanged for the V2 API. As you are free to create with our product, we think it should also be you who profits from your work. What you produce you own and are free to give away or sell. And, it’s up to you whether and on what terms you choose to commercialize your product. There’s a little catch – this also means that everything connected with use of your product is your responsibility. Signify will not accept liability if your product causes harm, for example. So use your powers for good!

Furthermore, while we say “what is yours is yours”, on the flip side we also say, “what is ours is ours”. Here, we mean the software, trademarks documentation, and any other materials we provide to help you develop Hue apps.

For example, you may refer to “Hue” and “Philips” in plain text but you aren’t allowed to use “Hue” or “Philips” branding in any logo or graphics. Also important to note is that the interface specifications “API” belong to Signify. Imagine you are working on an app and you come up with a brilliant idea for an improvement in the API or our materials. If you suggest any improvements to us and we adopt them, they become part of the platform used by everyone, and will belong to us.

And a final note: as the interface between your apps and the Hue platform will evolve over time, we will do our level best to maintain backwards compatibility and will inform you with enough time, before we roll out updates. That’s why, to keep everyone up to date, we ask you to register your app/s in the whitelist and make it clear they are your creation.