Dark Web Exposure API

Check if a password has been exposed in known breaches. Scan emails, usernames, and domains against 13 billion breached records from Have I Been Pwned. Powered by a server-side cache for instant repeat lookups.

---

Authentication

All requests require your RapidAPI key in headers:

"x-rapidapi-key": "YOUR_RAPIDAPI_KEY"
"x-rapidapi-host": "dark-web-exposure-api.p.rapidapi.com"

Some endpoints also require your own HIBP API key (BYOK — Bring Your Own Key). Get one at haveibeenpwned.com/API/Key. Send it via the X-HIBP-API-Key header.

---

Endpoints

1. Check Password Exposure

POST /password

Check if a password has appeared in known breaches. Results are cached for 90 days — repeat checks are instant.

Request Body

{
  "password": "mypassword123",
  "include_hash": true
}

Parameter	Type	Required	Description
password	string	yes	The password to check (max 1024 chars)
include_hash	boolean	no	Also return the uppercase SHA-1 hash

You can also send via GET query params: GET /password?password=xxx&include_hash=true

Or check by pre-computed SHA-1 hash: GET /password?sha1_hash=B8DFB080BC33FB564249E34252BF143D88FC018F

Successful Response

{
  "ok": true,
  "breach_count": 33,
  "breached": true,
  "cached": false,
  "checked_at": "2026-08-09T07:23:10.235727",
  "sha1_hash": "B8DFB080BC33FB564249E34252BF143D88FC018F"
}

• breach_count — Number of times this password appeared in known breaches.
• breached — true if breach_count > 0.
• cached — true if served from cache (no upstream call).

Error Response

{
  "ok": false,
  "error": {
    "code": "missing_input",
    "message": "Provide either 'password' or 'sha1_hash'."
  }
}

---

2. Batch Password Check

POST /passwords/batch

Check up to 100 passwords in a single request. Uses k-anonymity — passwords are grouped by SHA-1 prefix so a batch of 100 may cost as few as 10 upstream calls. Cached 90 days.

Request Body

{
  "passwords": ["password", "testing 123", "hunter2", "letmein"],
  "include_hashes": true
}

Parameter	Type	Required	Description
passwords	array	yes	1–100 plaintext password strings
include_hashes	boolean	no	Return each password's SHA-1 hash

Successful Response

{
  "ok": true,
  "results": [
    { "index": 0, "breach_count": 52372427, "breached": true, "sha1_hash": "5BAA61E4C9B93F3F0682250B6CF8331B7EE68FD8" },
    { "index": 1, "breach_count": 33, "breached": true, "sha1_hash": "B8DFB080BC33FB564249E34252BF143D88FC018F" },
    { "index": 2, "breach_count": 1406604, "breached": true, "sha1_hash": "B7A875FC1EA228B9061041B7CEC4BD3C52AB3CE3" },
    { "index": 3, "breach_count": 0, "breached": false, "sha1_hash": "6367C48DD193D56EA7A0A905AFC1E3BE1D5D9B74" }
  ],
  "total": 4,
  "upstream_calls": 2
}

• results — Per-password breach counts in the same order as input.
• upstream_calls — How many HIBP requests were actually made (shows cache efficiency).

---

3. k-Anonymity Password Range

GET /passwords/range

Search by a 5-character SHA-1 prefix and get every matching hash suffix with its breach count. Enables fully client-side password checking — the full hash never touches the server. Ideal for password managers and browser extensions.

Query Parameters

Parameter	Type	Required	Description
prefix	string	one of prefix or hash	5 hex characters (e.g. B8DFB)
hash	string	one of prefix or hash	Full 40-character SHA-1; first 5 chars are used

Example Request

GET /passwords/range?prefix=B8DFB

Successful Response

{
  "ok": true,
  "prefix": "B8DFB",
  "suffixes": {
    "0026A114E9A357BFB0D38916287208E2B81": 46,
    "00878CA72A19BDAED187D554A45B5C46011": 8,
    "080BC33FB564249E34252BF143D88FC018F": 33
  },
  "suffix_count": 1957,
  "cached": true
}

How to use client-side: Compute SHA1(password).toUpperCase(), take characters [5:] as the suffix, look it up in suffixes. A count of 0 or a missing key means the password is not in any known breach.

---

4. Breach Scan

GET | POST /scan

Scan an email address, username, or domain against the HIBP breach database. Returns all known breaches including name, date, data classes exposed, and description.

• Domain scans (e.g. adobe.com) — no HIBP key required.
• Email/username scans (e.g. alice@example.com) — requires your own HIBP API key via the X-HIBP-API-Key header (BYOK).

Results are cached 90 days per identifier.

Parameters

Parameter	In	Type	Required	Description
identifier	body/query	string	yes	Email, username, or domain
include_hashes	body/query	boolean	no	Include password hash fields in findings
include_pastes	body/query	boolean	no	Include pastebin exposure (email/username only, requires BYOK key)
X-HIBP-API-Key	header	string	for email/username	Your own HIBP API key

Example Requests

GET /scan?identifier=adobe.com

POST /scan
Content-Type: application/json
X-HIBP-API-Key: your-key-here

{
  "identifier": "alice@example.com",
  "include_pastes": true
}

Successful Response (domain)

{
  "ok": true,
  "input": { "type": "domain", "value": "adobe.com" },
  "breach_status": "exposed",
  "breach_count": 5,
  "sources": ["Adobe", "Adobe Creative Cloud"],
  "findings": [
    {
      "name": "Adobe",
      "title": "Adobe",
      "domain": "adobe.com",
      "first_seen": "2013-10-04",
      "added_date": "2013-10-04T00:00:00Z",
      "last_seen": "2013-10-04T00:00:00Z",
      "pwn_count": 152445165,
      "description": "In October 2013, 153 million Adobe accounts were breached.",
      "data_classes": ["Email addresses", "Password hints", "Passwords"],
      "is_verified": true,
      "is_fabricated": false,
      "is_sensitive": false,
      "is_retired": false,
      "is_spam_list": false,
      "is_malware": false
    }
  ],
  "pastes": null,
  "cached": false,
  "checked_at": "2026-08-09T07:30:00.000000"
}

Successful Response (email, safe)

{
  "ok": true,
  "input": { "type": "email", "value": "safe@example.com" },
  "breach_status": "safe",
  "breach_count": 0,
  "sources": [],
  "findings": [],
  "pastes": [],
  "cached": false,
  "checked_at": "2026-08-09T07:30:00.000000"
}

Error — Missing BYOK Key

{
  "ok": false,
  "error": {
    "code": "missing_api_key",
    "message": "Provide your HIBP API key via the X-HIBP-API-Key header."
  }
}

Error — Invalid Key

{
  "ok": false,
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid or expired HIBP API key. Get yours at haveibeenpwned.com/API/Key"
  }
}

---

5. Batch Breach Scan

POST /scan/batch

Scan up to 25 identifiers in a single request. Results are returned per-identifier — one bad entry doesn't fail the batch. Uncached scans are throttled at ~1.5 s per HIBP call.

• Domain scans — no key required.
• Email/username scans — requires X-HIBP-API-Key header.

Request Body

{
  "identifiers": ["alice@example.com", "adobe.com", "safe@example.com"],
  "include_pastes": false
}

Parameter	Type	Required	Description
identifiers	array	yes	1–25 emails, usernames, or domains
include_hashes	boolean	no	Include password hash fields in findings
include_pastes	boolean	no	Include pastebin exposure for email/username items
X-HIBP-API-Key	header	string	for email/username scans

Successful Response

{
  "ok": true,
  "results": [
    {
      "index": 0,
      "input": { "type": "email", "value": "alice@example.com" },
      "breach_status": "exposed",
      "breach_count": 3,
      "sources": ["Adobe", "LinkedIn"],
      "findings": [ { "name": "Adobe", "...": "..." } ],
      "pastes": null,
      "cached": false,
      "checked_at": "2026-08-09T07:30:00.000000"
    },
    {
      "index": 1,
      "input": { "type": "domain", "value": "adobe.com" },
      "breach_status": "exposed",
      "breach_count": 5,
      "sources": ["Adobe"],
      "findings": [ { "name": "Adobe", "...": "..." } ],
      "pastes": null,
      "cached": true,
      "checked_at": "2026-08-09T07:30:00.000000"
    },
    {
      "index": 2,
      "input": { "type": "email", "value": "safe@example.com" },
      "breach_status": "safe",
      "breach_count": 0,
      "sources": [],
      "findings": [],
      "pastes": null,
      "cached": false,
      "checked_at": "2026-08-09T07:30:00.000000"
    }
  ],
  "total": 3,
  "upstream_calls": 1
}

Response with per-item error (missing key)

{
  "ok": true,
  "results": [
    {
      "index": 0,
      "input": {"value": "alice@example.com"},
      "error": { "code": "missing_api_key", "message": "Provide your HIBP API key via the X-HIBP-API-Key header." }
    },
    {
      "index": 1,
      "input": { "type": "domain", "value": "adobe.com" },
      "breach_status": "exposed",
      "breach_count": 5,
      "sources": ["Adobe"],
      "findings": [],
      "pastes": null,
      "cached": true,
      "checked_at": "2026-08-09T07:30:00.000000"
    }
  ],
  "total": 2,
  "upstream_calls": 1
}

---

6. Breach Catalog

GET /breaches

Full catalog of all breaches in the HIBP database. Optionally filter by domain. Cached 1 day.

Query Parameters

Parameter	Type	Required	Description
domain	string	no	Show only breaches involving this domain

Example Requests

GET /breaches
GET /breaches?domain=adobe.com

Successful Response

{
  "ok": true,
  "count": 923,
  "domain": null,
  "cached": true,
  "breaches": [
    {
      "Name": "Adobe",
      "Title": "Adobe",
      "Domain": "adobe.com",
      "BreachDate": "2013-10-04",
      "AddedDate": "2013-10-04T00:00:00Z",
      "ModifiedDate": "2013-10-04T00:00:00Z",
      "PwnCount": 152445165,
      "Description": "In October 2013, 153 million Adobe accounts were breached.",
      "LogoPath": "https://haveibeenpwned.com/Content/Images/Logos/Adobe.png",
      "DataClasses": ["Email addresses", "Password hints", "Passwords"],
      "IsVerified": true,
      "IsFabricated": false,
      "IsSensitive": false,
      "IsRetired": false,
      "IsSpamList": false,
      "IsMalware": false
    }
  ]
}

---

7. Latest Breaches

GET /breaches/latest

Most recently added breaches, sorted by date added (newest first). Shares the same 1-day cache as /breaches. Great for powering a "latest breaches" news feed. No key required.

Query Parameters

Parameter	Type	Required	Description
limit	integer	no	1–50, default 10

Example Request

GET /breaches/latest?limit=10

Successful Response

{
  "ok": true,
  "count": 10,
  "limit": 10,
  "cached": true,
  "breaches": [
    {
      "Name": "NewBreach2026",
      "Title": "New Breach 2026",
      "Domain": "newbreach2026.com",
      "BreachDate": "2026-07-15",
      "AddedDate": "2026-08-01T00:00:00Z",
      "ModifiedDate": "2026-08-01T00:00:00Z",
      "PwnCount": 25000000,
      "Description": "A major breach at NewBreach2026 exposed user credentials.",
      "DataClasses": ["Email addresses", "Passwords"],
      "IsVerified": true,
      "IsFabricated": false,
      "IsSensitive": false,
      "IsRetired": false,
      "IsSpamList": false,
      "IsMalware": false
    }
  ]
}

---

8. Single Breach Details

GET /breaches/{name}

Full details for one named breach from the HIBP database. Cached 1 day. No key required.

Path Parameters

Parameter	Type	Required	Description
name	string	yes	Exact breach name (case-sensitive, URL-encode spaces)

Example Request

GET /breaches/Adobe

Successful Response

{
  "ok": true,
  "cached": false,
  "breach": {
    "Name": "Adobe",
    "Title": "Adobe",
    "Domain": "adobe.com",
    "BreachDate": "2013-10-04",
    "AddedDate": "2013-10-04T00:00:00Z",
    "ModifiedDate": "2013-10-04T00:00:00Z",
    "PwnCount": 152445165,
    "Description": "In October 2013, 153 million Adobe accounts were breached.",
    "LogoPath": "https://haveibeenpwned.com/Content/Images/Logos/Adobe.png",
    "DataClasses": ["Email addresses", "Password hints", "Passwords"],
    "IsVerified": true,
    "IsFabricated": false,
    "IsSensitive": false,
    "IsRetired": false,
    "IsSpamList": false,
    "IsMalware": false
  }
}

Error Response

{
  "ok": false,
  "error": {
    "code": "breach_not_found",
    "message": "No breach named 'DoesNotExist'."
  }
}

---

9. Pastebin Exposure

GET /pastes/{account}

Returns all known pastebin paste entries that include a given email address or username. Each paste includes the source, title, date, and number of email addresses in the paste. Requires your own HIBP API key (BYOK). Cached 1 day.

Path Parameters

Parameter	Type	Required	Description
account	string	yes	Email address or username

Required Header

X-HIBP-API-Key: your-hibp-api-key

Example Request

GET /pastes/alice@example.com
Headers: X-HIBP-API-Key: your-key-here

Successful Response

{
  "ok": true,
  "account": "alice@example.com",
  "count": 2,
  "cached": false,
  "pastes": [
    {
      "Id": "abcdef1234",
      "Source": "Pastebin",
      "Title": "breach dump 2024",
      "Date": "2024-03-15T00:00:00Z",
      "EmailCount": 34
    },
    {
      "Id": "ghijk56789",
      "Source": "Pastebin",
      "Title": "dumped credentials",
      "Date": "2023-11-02T00:00:00Z",
      "EmailCount": 12
    }
  ]
}

Error — Missing Key

{
  "ok": false,
  "error": {
    "code": "missing_api_key",
    "message": "Provide your HIBP API key via the X-HIBP-API-Key header."
  }
}

Error — Invalid Key

{
  "ok": false,
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid or expired HIBP API key. Get yours at haveibeenpwned.com/API/Key"
  }
}

---

10. Data Classes

GET /data_classes

The complete fixed list of data classes HIBP uses to categorize breach content (e.g. "Email addresses", "Passwords", "Dates of birth"). Useful for building filters and risk-scoring UIs. Cached 30 days. No key required.

Example Request

GET /data_classes

Successful Response

{
  "ok": true,
  "count": 53,
  "cached": true,
  "data_classes": [
    "Account balances", "Age groups", "Avatars", "Bank account numbers",
    "Bank identifiers", "Banking information", "Bios", "Birth dates",
    "Blood types", "Dates of birth", "Debit/credit card numbers",
    "Device information", "Email addresses", "Ethnicities", "Favourites",
    "Gender", "Geographic locations", "Government-issued IDs",
    "Historical passwords", "IP addresses", "Job titles",
    "Marital statuses", "Name", "Nationalities", "Password hints",
    "Passwords", "Payment data", "Personal health data", "Phone numbers",
    "Physical addresses", "Purchases", "Races", "Relationship statuses",
    "Religious affiliations", "Salts", "Security questions and answers",
    "Sexual preferences", "Social media profiles", "Spoken languages",
    "Time zones", "User website URLs", "Usernames", "Website activity"
  ]
}

---

11. Health Check

GET /status

Returns API version, uptime, cache table sizes, and service health. Use this as a pre-flight check before making other calls.

Example Request

GET /status

Successful Response

{
  "ok": true,
  "service": "Dark Web Exposure API",
  "version": "0.0.2",
  "time": "2026-08-09T07:23:06.000900",
  "uptime_seconds": 1234,
  "cache": {
    "scanned_identifiers": 312,
    "password_hashes": 4091,
    "hash_prefixes": 87,
    "catalog_entries": 14
  }
}

---

BYOK (Bring Your Own Key)

The following endpoints require the subscriber to provide their own Have I Been Pwned API key:

Endpoint	Why key needed
GET/POST /scan (email/username)	Account breach lookup requires HIBP key
POST /scan/batch	Same — email/username items need key
GET /pastes/{account}	Paste lookup requires HIBP key

How to get a key: Purchase at haveibeenpwned.com/API/Key

How to send it: Add the header X-HIBP-API-Key: your-key-here to your request.

No key needed for: /password, /passwords/batch, /passwords/range, /scan (domain only), /breaches, /breaches/latest, /breaches/{name}, /data_classes, /status.

---

Caching

All endpoints use a server-side SQLite cache for speed and upstream savings:

• Password checks — cached 90 days per hash
• Breach scans — cached 90 days per identifier
• Breach catalog — cached 1 day
• Pastes — cached 1 day per account
• Data classes — cached 30 days

A cached: true flag in the response means the result was served from cache with zero upstream latency.

---

Error Reference

HTTP	Code	Cause
400	missing_input	Required parameter absent
400	missing_identifier	No identifier sent to /scan
400	invalid_identifier	Not a valid email, username, or domain
400	invalid_hash	sha1_hash isn't 40 hex characters
400	invalid_prefix	prefix isn't 5 hex characters
400	invalid_name	Breach name has unsupported characters
400	invalid_account	Account must be an email or username
400	invalid_limit	limit isn't 1–50
400	invalid_input	Wrong JSON type in array
400	password_too_long	Password exceeds 1024 chars
400	batch_too_large	Exceeds max batch size
400	missing_api_key	BYOK header not sent
401	invalid_api_key	HIBP key is bad or expired
404	breach_not_found	No breach with that name
429	hibp_rate_limited	HIBP rate limit hit
502	upstream_error	HIBP unreachable or timed out
500	internal_error	Server-side bug

---

Changelog

v0.0.2 — August 26, 2026

• New: /passwords/batch — check up to 100 passwords in one request
• New: /passwords/range — k-anonymity SHA-1 prefix search for client-side checking
• New: /scan — breach scan for email, username, and domain
• New: /scan/batch — scan up to 25 identifiers at once
• New: /breaches — full breach catalog with optional domain filter
• New: /breaches/latest — newest breaches sorted by date
• New: /breaches/{name} — single breach details
• New: /pastes/{account} — pastebin exposure lookup
• New: /data_classes — known HIBP data classes
• New: /status — health check with cache stats
• Enhanced: /password now supports GET, SHA-1 hash input, and include_hash option
• Architecture: SQLite cache (90-day TTL) for zero-cost repeat lookups
• Architecture: BYOK model — no server-side HIBP key; subscribers bring their own

v0.0.1 — Initial Release

• /password — check one password against known breaches