HIBP: CHECK AN ADDRESS YOU CONTROL AND RECORD THE BREACH ENTRY

The job is a breach entry for an address you control

Someone drops a breach logo into the work chat and writes "so are we hacked?" The useful reply is smaller than the logo. You take an email address you control, or a test address Have I Been Pwned publishes for integrators, you ask what HIBP has filed against it, and you write down what that entry is. A sighting in a dataset. A name, a pair of dates, a list of data classes, and a row of flags. The password is not in that row, and the row is not a live session.

Have I Been Pwned is the site at haveibeenpwned.com, run by Superlative Enterprises Pty Ltd out of Queensland. The homepage, when this lesson was checked, offered an email box and described itself as a check for whether an address has been exposed in a data breach. That browser search is free. The terms call the free services the website email search and anything else on the site that does not require payment. Notify-me sits on that side of the counter. The page at haveibeenpwned.com/NotifyMe is headed as free breach notifications: you enter an address, you open the verification mail, and later you hear if that address shows up in a breach HIBP loads afterwards. The FAQ says every notification goes to the address being watched, so you cannot subscribe a stranger and you cannot subscribe an inbox you have lost. The same FAQ says the mail comes from noreply@haveibeenpwned.com. If it never arrives, their experience is that the destination server bounced it. Check the junk folder, then stop inventing a second path.

The API is the other counter, and it is where a cheatsheet goes stale. Version 3 is served under https://haveibeenpwned.com/api/v3. The page that explains it is https://haveibeenpwned.com/API/v3. There is no local --help. The help text is that page, the FAQ, the terms, the subscription page, and the HTTP body you just received. This lesson was read against those pages. The terms copy showed a last-updated date of 27 October 2026. If a badge, a path, or a sentence has moved, the page wins and this lesson loses. A write-up that cannot name the day it was read is a souvenir.

Four jobs need no paid key, on the pages and the calls this lesson checked.

The browser search, above. One address at a time. The FAQ is explicit that the public search returns the result for a single address or username you typed, and that a list of everyone's addresses is not a feature.

Notify-me, also above. The service stores the address, the date you subscribed, and a verification token, because otherwise it cannot write to you later. That is a collection. On your own inbox, for the purpose of being told, it is a collection you can explain.

Pwned Passwords. Hundreds of millions of password strings, stored as SHA-1 and as NTLM hashes of the UTF-8 password, with a count of how often each has been seen, and with no email address beside them. The range API is GET https://api.pwnedpasswords.com/range/ plus the first five characters of the hash. No API key. The API docs and the support article both say there is no rate limit, and no attribution requirement, though they will take a credit if you offer one. k-anonymity here means HIBP sees a five-character prefix and you compare the suffix locally. The docs also allow ?mode=ntlm and an Add-Padding: true header. Padded rows, they say, carry a count of 0 and can be discarded. "Pwned Passwords support" on a paid plan is the docs' name for help integrating this API. The API itself is the free one. This lesson does not print a price. The subscription page does, and the number moves.

The breach catalogue. The terms name four unauthenticated paths: /breaches, /breach/{name}, /latestbreach, and /dataclasses. When this lesson was checked, the latest-breach call, GET /breach/Adobe, and the data-class call each returned HTTP 200 with a user agent and no key. The subscription page's free line includes a "breach monitoring API" next to browser search, email notifications, and Pwned Passwords. That phrase lines up with the catalogue calls. It does not mean "search any inbox by API."

The calls that search HIBP by email address or by domain want a key in the hibp-api-key header. The docs say the key is 32 hexadecimal characters. Missing it, on the email route, returned HTTP 401 and a body that said the key was missing.

GET /breachedaccount/{email} is marked Core, Pro, and High RPM. The default body is breach names only. ?truncateResponse=false returns the full model. GET /pasteaccount/{email} carries the same paid badges. GET /breacheddomain/{domain} is marked Core and Pro, and only after you have verified that you control the domain. The docs say an unverified domain is HTTP 403. Stealer-log routes are marked Pro or higher, and they too want a verified domain. The email k-anonymity route, GET /breachedaccount/range/ plus the first six characters of the SHA-1 of the address, is marked Pro and High RPM. Six characters, not five. It is a different API from the password range, it is not free, and the terms tell you to throw away every suffix that is not the address you asked about.

The subscription page, read for this lesson, also puts "monitor domains with up to 10 breached addresses" on the free line, and it says you prove control before a domain is searchable. A small domain you administer is a dashboard question for the day you read that page. It is not a mailbox list you collect in class. The API path that returns every alias is the paid, key-gated one.

The docs publish a test key of 32 zeros, and they say it can query addresses on hibp-integration-tests.com. That key is a prop. It is not a free pass at the rest of the internet, and it is not a key you found in a gist and pasted into a product.

A breach, in the API docs' own line, is an instance of a system having been compromised and the data disclosed. The FAQ then spends most of its length on the cases that sentence does not cover: unverified, fabricated, spam lists, malware collections, stealer logs, pastes, and incidents with no password in them at all. "Pwned", the FAQ notes, is a gamer spelling of "owned". It can stay in the logo. The sentence you file is plainer.

The artefact is the breach name, the two dates, the data classes, and the flags. A password value is not part of the artefact.