The API, without the guesswork.

Register the client, pick the interface you need, and read exposure data with predictable, well-typed results. Every surface shares this shell and these conventions.

Register the client

Call AddPwnedServices once at startup. Bind from configuration, or configure options inline. Every interface is registered as a singleton.

using HaveIBeenPwned.Client;

var builder = WebApplication.CreateBuilder(args);

// Binds the "HibpOptions" section from appsettings.json.
builder.Services.AddPwnedServices(
    builder.Configuration.GetSection(nameof(HibpOptions)));

var app = builder.Build();

using HaveIBeenPwned.Client;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddPwnedServices(options =>
{
    options.ApiKey = builder.Configuration["Hibp:ApiKey"];
    options.SubscriptionLevel = HibpSubscriptionLevel.Pro2;
    options.UserAgent = "MyApp/1.0";
});

var app = builder.Build();

Which interface do I inject?

Inject the narrow interface for the surface you use, or IPwnedClient for all of them. They resolve to the same instance.

Configure HibpOptions

Subscription levels and limits

Set SubscriptionLevel to one of the HibpSubscriptionLevel tiers. Core plans cover breach, password, and domain search; Pro plans add stealer logs; High RPM plans raise the request ceiling. Read the live plan at runtime with GetSubscriptionStatusAsync.

public sealed class PlanInspector(IPwnedClient client)
{
    public async Task ReportAsync()
    {
        SubscriptionStatus? status =
            await client.GetSubscriptionStatusAsync();

        Console.WriteLine(
            $"{status?.SubscriptionName}: {status?.Rpm} rpm, " +
            $"stealer logs {(status?.IncludesStealerLogs is true ? "on" : "off")}.");
    }
}

Pro 2: 100 rpm, stealer logs on.

Choose a surface

Error behavior stays honest.

Documented 404 responses map to each operation's no-result shape. Every other non-success throws PwnedApiException, carrying the status, response body, and retry hint.

try
{
    var breaches = await client.GetBreachesForAccountAsync("account@example.com");
}
catch (PwnedApiException exception)
{
    // Inspect status, body, and retry hint where the failure happened.
    Console.WriteLine(exception.StatusCode);      // e.g. TooManyRequests
    Console.WriteLine(exception.RetryAfter);      // e.g. 00:00:02
    Console.WriteLine(exception.ResponseContent); // raw HIBP body, if any
}