Oakrey.Hue.ApiV1 3.0.0

dotnet add package Oakrey.Hue.ApiV1 --version 3.0.0
                    
NuGet\Install-Package Oakrey.Hue.ApiV1 -Version 3.0.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Oakrey.Hue.ApiV1" Version="3.0.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Oakrey.Hue.ApiV1" Version="3.0.0" />
                    
Directory.Packages.props
<PackageReference Include="Oakrey.Hue.ApiV1" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Oakrey.Hue.ApiV1 --version 3.0.0
                    
#r "nuget: Oakrey.Hue.ApiV1, 3.0.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Oakrey.Hue.ApiV1@3.0.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Oakrey.Hue.ApiV1&version=3.0.0
                    
Install as a Cake Addin
#tool nuget:?package=Oakrey.Hue.ApiV1&version=3.0.0
                    
Install as a Cake Tool

Oakrey.Hue.ApiV1

DTO and model library for the Philips Hue REST API v1. Provides System.Text.Json-annotated C# types that map directly to the JSON responses returned by a Hue bridge. No HTTP client or bridge discovery is included � compose with HttpClient or any REST library of your choice.


Main features

  • Full model graph for the Hue v1 light resource: Light, State, Capabilities, Control, Config, Startup, Streaming, Swupdate, ColorTemperature
  • ConnectionInfo for storing bridge address, port, and API username
  • All properties annotated with [JsonPropertyName] matching Hue bridge field names exactly
  • No external dependencies � uses only System.Text.Json from the .NET runtime
  • Targets .NET 11

Requirements

  • .NET 11 or higher
  • No additional NuGet packages required

Installation

.NET CLI

dotnet add package Oakrey.Hue.ApiV1

Package Manager Console

Install-Package Oakrey.Hue.ApiV1

NuGet Package Manager (Visual Studio)

Search for Oakrey.Hue.ApiV1 under Tools > NuGet Package Manager > Manage NuGet Packages for Solution and click Install.


Model graph

classDiagram
    class Light {
        +string Name
        +string Type
        +string ModelId
        +string ProductName
        +string ManufacturerName
        +string UniqueId
        +string SwVersion
        +string SwConfigId
        +string ProductId
        +State State
        +Capabilities Capabilities
        +Config Config
        +Swupdate SwUpdate
    }

    class State {
        +bool On
        +int Brightness
        +int BrightnessIncrement
        +int Hue
        +int Saturation
        +int SaturationIncrement
        +int Ct
        +string ColorMode
        +string Alert
        +string Effect
        +string Mode
        +bool Reachable
        +int TransitionTime
        +List~double~ Xy
    }

    class Capabilities {
        +bool Certified
        +Control Control
        +Streaming Streaming
    }

    class Control {
        +int MaxLumen
        +int MinDimLevel
        +string ColorGamutType
        +double[][] ColorGamut
        +ColorTemperature Ct
    }

    class ColorTemperature {
        +int Min
        +int Max
    }

    class Streaming {
        +bool Proxy
        +bool Renderer
    }

    class Config {
        +string Archetype
        +string Direction
        +string Function
        +Startup Startup
    }

    class Startup {
        +bool Configured
        +string Mode
    }

    class Swupdate {
        +string State
        +string LastInstall
    }

    class ConnectionInfo {
        +string IpAddress
        +string Username
        +string Port
    }

    Light --> State
    Light --> Capabilities
    Light --> Config
    Light --> Swupdate
    Capabilities --> Control
    Capabilities --> Streaming
    Control --> ColorTemperature
    Config --> Startup

Usage

Read all lights from a Hue bridge

using System.Net.Http.Json;
using System.Text.Json;
using Oakrey.Hue.ApiV1;

ConnectionInfo connection = new ConnectionInfo
{
    IpAddress = "192.168.1.100",
    Port = "80",
    Username = "your-hue-api-username"
};

using HttpClient client = new HttpClient();
string url = $"http://{connection.IpAddress}:{connection.Port}/api/{connection.Username}/lights";

Dictionary<string, Light>? lights = await client.GetFromJsonAsync<Dictionary<string, Light>>(url);

foreach (KeyValuePair<string, Light> entry in lights ?? [])
{
    Console.WriteLine($"{entry.Key}: {entry.Value.Name} � on={entry.Value.State.On}, bri={entry.Value.State.Brightness}");
}

Deserialize a single light from JSON

string json = await File.ReadAllTextAsync("light.json");
Light? light = JsonSerializer.Deserialize<Light>(json);

Console.WriteLine($"Color gamut type: {light?.Capabilities.Control.ColorGamutType}");
Console.WriteLine($"CT range: {light?.Capabilities.Control.Ct.Min} - {light?.Capabilities.Control.Ct.Max} mired");

Model reference

Class Hue API resource field Purpose
Light /api/{user}/lights/{id} Top-level light resource
State state Runtime state (on, bri, hue, sat, ct, xy, �)
Capabilities capabilities Static capability declaration
Control capabilities.control Lumen range, color gamut, CT range
ColorTemperature capabilities.control.ct Mirek min/max bounds
Streaming capabilities.streaming Proxy and renderer flags
Config config Archetype, direction, function, startup mode
Startup config.startup Power-on behaviour
Swupdate swupdate Firmware update state and timestamp
ConnectionInfo n/a Helper for storing bridge address and credentials

Development notes

  • This library covers the light resource only. Groups, scenes, sensors, schedules, and rules from the Hue v1 API are not included.
  • ConnectionInfo is a plain data holder with no HTTP logic. Constructing the request URL and handling authentication headers is left to the consumer.
  • The Hue API v1 returns lights as a Dictionary<string, Light> where the key is the numeric light ID as a string.
  • The Hue bridge uses self-signed TLS on port 443. When targeting HTTPS, configure HttpClientHandler to accept the bridge certificate or use port 80.

License

MIT � Copyright (c) Oakrey 2016-present

Project information

Product Compatible and additional computed target framework versions.
.NET net11.0 is compatible. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
3.0.0 50 11/13/2026
2.0.2 180 6/3/2026
2.0.1 129 5/15/2026
2.0.0 149 2/2/2026
1.0.0 279 4/22/2025