API Documentation

Base URL: https://breach.house/api/v1

Authorization: Bearer <your_token>
X-API-Key: <your_token>
?token=<your_token>          (query string, less recommended)

curl -H "Authorization: Bearer $TOKEN" \
  "https://breach.house/api/v1/me"

{
  "error": "invalid_token",
  "message": "Optional human-readable description"
}

# listing-only (NOT indexed) — equivalent:
curl -H "Authorization: Bearer $TOKEN" "https://breach.house/api/v1/ransomware?status=listed"
curl -H "Authorization: Bearer $TOKEN" "https://breach.house/api/v1/ransomware?status=pending"
curl -H "Authorization: Bearer $TOKEN" "https://breach.house/api/v1/ransomware?published=false"
curl -H "Authorization: Bearer $TOKEN" "https://breach.house/api/v1/ransomware?indexed=false"

# only HIBR-indexed:
curl -H "Authorization: Bearer $TOKEN" "https://breach.house/api/v1/breaches?status=published"
curl -H "Authorization: Bearer $TOKEN" "https://breach.house/api/v1/breaches?indexed=true"

Exchange credentials for a token

Issues a new API token. Use the same username/password as your account.

curl -X POST https://breach.house/api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"username":"alice","password":"...","name":"my-laptop","expires_in_days":30}'

Returns { "token": "...", "name": "...", "created_at": "...", "expires_at": "..." }.

Current user info

curl -H "Authorization: Bearer $TOKEN" https://breach.house/api/v1/me

List ransomware victims

Accepts common filters.

curl -H "Authorization: Bearer $TOKEN" \
  "https://breach.house/api/v1/ransomware?country=US&limit=20"

Ransomware-specific response fields (in addition to the common victim fields):

id	int	Numeric record id (the sequential dataransom.json id). Accepted by /ransomware/{id} and the id filter.
victim_id	string	Stable alphanumeric victim id. Also accepted by /ransomware/{id} and the victim_id filter.
t2_time	string	Public-disclosure timestamp (t2 of the exposure "Window Zero"), YYYY-MM-DD HH:MM:SS.ffffff.
hibr_indexed	bool	Whether HIBR has indexed this victim. See HIBR indexing & listing-only.
is_indexed	bool	Same value as hibr_indexed.
indexed	string / null	HIBR index timestamp, or null when the victim is listing-only.
hibr	object	Optional. Have I Been Ransom metadata for the victim's domain, present only when indexed. Includes domain, infostealer (hits/employee_hits), breaches, ransomware, emails, ids and a leaks breakdown.

Example response item (truncated):

{
  "id": 12345,
  "victim_id": "fThjSoJ6g4oJ",
  "post_title": "Banco Azzoaglio",
  "group_name": "lockbit3",
  "country": "IT",
  "website": "bancoazzoaglio.it",
  "discovered": "2023-01-15 10:22:00.000000",
  "t2_time": "2023-02-01 00:00:00.000000",
  "hibr_indexed": true,
  "is_indexed": true,
  "indexed": "2025-06-08T16:41:23.807397",
  "meta_description": "...",
  "hibr": {
    "domain": "bancoazzoaglio.it",
    "infostealer": { "hits": 3071, "employee_hits": 75 },
    "breaches": 120,
    "ransomware": 8,
    "emails": { "total": 1875, "unique": 1640, "internal": 980, "external": 660 },
    "ids": { "distinct_leaks": 14 },
    "leaks": [ { "post_title": "...", "group_name": "...", "is_ransomware": true } ]
  }
}

Get a single ransomware victim

{id} accepts EITHER the numeric record id OR the alphanumeric victim_id. Returns the full victim object, including both identifiers, t2_time and the hibr block when available (see the list endpoint).

curl -H "Authorization: Bearer $TOKEN" \
  https://breach.house/api/v1/ransomware/12345
curl -H "Authorization: Bearer $TOKEN" \
  https://breach.house/api/v1/ransomware/wAmZhughls2y

List data breaches

Accepts common filters. Each breach includes the HIBR-index flags hibr_indexed / is_indexed and the indexed date (or null when listing-only).

curl -H "Authorization: Bearer $TOKEN" \
  "https://breach.house/api/v1/breaches?since=2026-01-01&limit=50"

Get a single breach

curl -H "Authorization: Bearer $TOKEN" \
  https://breach.house/api/v1/breaches/789

All HIBR-indexed records (ransomware + breaches)

Everything Have I Been Ransom has indexed — ransomware leaks and traditional breaches — in a single feed. Also accepts the common filters (country, group, q, since, until, limit, offset).

Parameter	Values	Description
type	all, ransomware, breaches	Which indexed set to return. Default all.

curl -H "Authorization: Bearer $TOKEN" \
  "https://breach.house/api/v1/indexed?type=ransomware&limit=20"

Response fields (each row is enriched against local data):

type	string	Ransomware Leak or Traditional Breach.
indexed	string	HIBR index timestamp — always present here, since every row is indexed.
local	bool	true if the record also exists in the local dataset; false for index-only records (indexed by HIBR but not yet ingested locally).
victim_id	string	For ransomware rows present locally, the local victim_id.

{
  "type": "ransomware",
  "total": 1447,
  "count": 20,
  "generated_at": "2026-07-23T09:15:00.100000",
  "source": "https://haveibeenransom.com/breaches/full",
  "results": [
    {
      "id": "677",
      "post_title": "Bangkok Airways",
      "group_name": "lockbit",
      "type": "Ransomware Leak",
      "indexed": "2025-06-08T16:41:23.807397",
      "hibr_indexed": true,
      "is_indexed": true,
      "local": true,
      "victim_id": "F1KDHgI5VSkm"
    }
  ]
}

List leads

Accepts common filters.

curl -H "Authorization: Bearer $TOKEN" \
  "https://breach.house/api/v1/leads?q=acme"

Get a single lead

curl -H "Authorization: Bearer $TOKEN" \
  https://breach.house/api/v1/leads/456

List infostealer logs

Accepts common filters.

curl -H "Authorization: Bearer $TOKEN" \
  "https://breach.house/api/v1/stealers?country=ES"

Get a single stealer log

curl -H "Authorization: Bearer $TOKEN" \
  https://breach.house/api/v1/stealers/321

List threat-actor groups

Parameter	Values	Description
type	all, breaches, stealers, leads	Group source. Default all.
q	string	Substring match on group name.
limit	int	Page size, default 100, max 500.
offset	int	Pagination offset.

curl -H "Authorization: Bearer $TOKEN" \
  "https://breach.house/api/v1/groups?type=breaches&q=lock"

Get a single group

{name} accepts either the slug or the raw name.

curl -H "Authorization: Bearer $TOKEN" \
  https://breach.house/api/v1/groups/lockbit

Latest activity (mixed)

Most recent items across sources. Accepts common filters. Ransomware victims in the response carry t2_time and, when available, the hibr block (see /ransomware).

curl -H "Authorization: Bearer $TOKEN" \
  "https://breach.house/api/v1/latest?limit=10"

Country metadata

curl -H "Authorization: Bearer $TOKEN" \
  https://breach.house/api/v1/countries

Monthly country intelligence report

Everything a monthly country report renders from, pre-aggregated: headline KPIs against the previous month, a per-day timeline, sector and threat-actor breakdowns, the year-to-date series and a year-on-year comparison.

Parameter	Type	Description
cc	path	ISO 3166-1 alpha-2 country code, e.g. GR
period	string	YYYY-MM. Omit it and you get the most recent month that actually has data.

curl -H "Authorization: Bearer $TOKEN" \
  "https://breach.house/api/v1/countries/GR/report?period=2026-04"

What is not in the response, and why. Victim revenue, exfiltrated volume, dwell time, intrusion vector and editorial prose are not tracked in our datasets, so they come back null and are itemised in meta.unavailable with the reason — we never estimate them. Honest stand-ins are listed in meta.substitutions. Check meta.data_coverage for the real window, and meta.requested_period_has_data before reading a month of zeros as a quiet month.

Industry-sector vocabulary

The canonical sector list with slugs and victim counts, plus aliases — retired spellings that still resolve to the surviving sector, so older integrations keep working.

curl -H "Authorization: Bearer $TOKEN" \
  https://breach.house/api/v1/sectors

Monthly sector intelligence report

The same report scoped to an industry sector instead of a country: the sector's share of global activity, the country breakdown month over month, most active groups with the long tail counted separately, and the YTD series.

Parameter	Type	Description
slug	path	Sector slug from /api/v1/sectors, e.g. construction-real-estate
period	string	YYYY-MM. Defaults to the latest month with data.
country	string	Optional ISO-2 code to narrow the report to one country.

curl -H "Authorization: Bearer $TOKEN" \
  "https://breach.house/api/v1/sectors/construction-real-estate/report?period=2026-05"

Breach rows carry no sector of their own, so the breach dimension of a sector report is reported as 0 and flagged in meta.unavailable rather than silently omitted.

Tor gateway — open a .onion leak site

Fetches an onion service over Tor from our side and returns the page as sanitised, script-free HTML, so an analyst can read a leak site without running Tor Browser. Links inside the page are rewritten back through the gateway, so you can walk the site. There is a browser UI for the same thing at /gateway.

Parameter	Type	Description
url	string	The .onion address. Scheme optional (http:// is assumed).

curl -H "Authorization: Bearer $TOKEN" \
  "https://breach.house/api/v1/gateway?url=lockbit3753ekiocyo5epmpy6klmejchjtzddoekjlnt6mu3qh4de2id.onion"

Returns url, final_url, content_type, elapsed_s, bytes, links, images_blocked and the sanitised html.

Deliberate limits. Only .onion hosts are accepted — this is a research viewer, not a web proxy, and the restriction is what stops it being used to reach internal or clearnet addresses. Only text/html and text/plain are rendered: binaries are never fetched. Scripts, forms, iframes, event handlers and images are stripped. Capped at 2 MB, 60 s and 60 requests/hour per user. Errors come back as {"error":"gateway_error","message":"…"} with 400 (bad target), 403 (wrong plan), 429 (rate limit) or 502 (unreachable).

Resolve a victim to its id

Open endpoint: maps a (group, victim name) pair to the internal id, returning the most recent on duplicate names.

Parameter	Type	Description
group	string	Group name. Required.
name	string	Victim name. Required.
match	string	exact (default) or domain, which also matches the domain label (e.g. inrix → INRIX.COM).

curl "https://breach.house/api/v1/resolve?group=qilin&name=ACME+Corp"

Ingest breaches

Adds one or more breaches. Authenticated with X-Ingest-Secret (not an API token). Send an object or a list of objects; post_title is required, and the server generates the id — ids that already exist are skipped. Caches invalidate by mtime, so a new breach appears without a restart.

curl -X POST -H "X-Ingest-Secret: $SECRET" -H "Content-Type: application/json" \
  -d '{"post_title":"ACME Corp","group_name":"qilin","country":"ES"}' \
  https://breach.house/api/v1/ingest/breach

Responds with counts of received / added / skipped / invalid and the affected ids.

Cross-source text search

Parameter	Type	Description
q	string	Required. Search text; also matches an exact id or victim_id.
limit	int	Max results per source. Default 25, max 200.

curl -H "Authorization: Bearer $TOKEN" \
  "https://breach.house/api/v1/search?q=acme&limit=10"

Returns an object keyed by source: ransomware, breaches, leads, stealers. Items under ransomware include t2_time and the optional hibr block (see /ransomware).