DolphinBoilderApi 0.2.0

DolphinBoilderApi

A .NET client library for the Dolphin Boiler smart water heater API.

Authenticate, monitor, and control your Dolphin Boiler programmatically — perfect for building custom home automation integrations, dashboards, or bots.

v0.2.0 covers the app's full documented /API/ surface (~50 endpoints). Authentication is handled internally by the client from the device name + account email (no server-issued API key). v0.1.x replaced the earlier /HA/V1/ API-key client with a partial /API/ client; v0.2.0 fills in the rest (manual control, history/graphs, notifications, sharing, network/specs, account ops).

Features

• Authentication & account — login, signup, logout, delete account
• Device discovery — list all boilers on the account, including their server-side nicknames
• Live status — power on/off, current temperature, target temperature, and current draw in Amps
• Manual control — turn on (by quantity) / off, enable/disable Dolphin, reset temperature
• Settings — Shabbat, Legionella, fixed-temperature flags (read + toggle)
• Schedule — read/create/edit/delete quantity timers and fixed-temperature timers
• History — per-month usage totals (getHistory) and per-day temperature traces (getGraphHistory)
• Notifications, sharing/permissions, network & boiler specs, Dolphin Plus

Setter/command endpoints return a CommandResult { Success, Message, Error, Raw }. Getters with a well-known response shape are strongly typed; those whose response isn't documented in the APK return the raw JsonElement so you can read whatever fields the server sends.

How authentication works

Log in once with LoginAsync(email, password); after that the client authenticates each call for you from the device name + account email, so no password or session key needs to be stored. The auth handling is internal to the client — just call the methods below.

The official app disables TLS certificate validation, and so does this client (it trusts all certs) to match the cloud server's behavior.

Quick start

Prerequisites

• .NET 10 or later

Installation

Add the project as a reference, or copy the single-file DolphinBoilderApi/DolphinBoilerApi.cs into your solution.

Usage

using DolphinBoilderApi;

await using var client = new DolphinClient();

const string email = "you@example.com";

// 1. Authenticate — returns the account's primary device name.
var login = await client.LoginAsync(email, "your-password");
if (!login.Success)
{
    Console.WriteLine($"Login failed: {login.Error}");
    return;
}

// 2. Discover devices (with nicknames). Seeded by the primary device from login.
var devices = await client.GetDevicesAsync(login.DeviceName!, email);
foreach (var d in devices)
    Console.WriteLine($"{d.DeviceName}  ({d.Nickname})");

var device = devices[0].DeviceName;

// 3. Read live state.
var data = await client.GetMainScreenDataAsync(device, email);
Console.WriteLine($"{data?.Temperature}°C (target {data?.TargetTemperature}°C) — " +
                  $"Power {(data?.PowerOn == true ? "ON" : "OFF")}, {data?.Amps} A");

// 4. Read settings (authoritative Shabbat state).
var settings = await client.GetSettingsAsync(device, email);
Console.WriteLine($"Shabbat: {(settings?.ShabbatEnabled == true ? "ON" : "OFF")}");

// 5. Read the schedule.
var timers = await client.GetTimersAsync(device, email);                  // start time + quantity (showers/°)
var windows = await client.GetFixedTemperatureTimersAsync(device, email); // explicit begin→end windows

// 6. Control.
await client.EnableShabbatAsync(device, email);

API reference

One method per /API/ endpoint, grouped as in the app. Setters return CommandResult; typed getters return the model shown; undocumented-shape getters return JsonElement? (read fields yourself).

Auth / account

Main screen / manual control

Devices / specs / network

Settings / Shabbat / Legionella

Timers (quantity / shower)

Fixed-temperature

History / graphs

Notifications

Sharing / permissions

Dolphin Plus

Account-level calls (getSharedAccounts, shareAccount, …) still need a deviceName because auth is always keyed to a device — pass the account's primary device name.

Field notes

• Amps, not kWh. MainScreenData.Amps is the API's Energy field — instantaneous current in Amperes (the app renders it as "X(A)"). The API exposes no voltage or kWh, so energy totals must be estimated (Ah × assumed voltage).
• Booleans. Settings flags arrive as "1"/"0"; main-screen flags arrive as "ON". Both are normalized for you. Parsing is lenient (JsonElement-based), so extra or missing fields are tolerated.
• Day encoding. Timer days are a comma-separated list of Sun,Mon,Tue,Wed,Thu,Fri,Sat (or once). Quantity timers carry only a start time + a Quantity (shower count or target °), not a duration — only fixed-temperature timers have an explicit end time.
• getHistory shape is unverified. The decompiled APK doesn't pin down getHistory.php's response fields, so MonthlyHistory.Cost / TotalMinutes / Consumption are a best-effort mapping over the likely key names. MonthlyHistory.Raw is authoritative — inspect it against a live response and tighten the mapping once the real field names are known.

Dependency injection

DolphinClient accepts optional HttpClient and ILogger<DolphinClient> parameters. Note that when you pass your own HttpClient, you are responsible for the trust-all TLS handler and the https://api.dolphinboiler.com/API/ base address — the built-in defaults are only applied when the client creates its own HttpClient.

Related projects

Shoutout to dolphin by @0xAlon — a Home Assistant integration for Dolphin Boiler. If you're looking for a ready-made HA custom component rather than a standalone .NET library, check it out!

License

This project is provided as-is. Use at your own risk.