Dark Web Exposure API

Snapshot from docs/endpoints.md for source API version 0.0.2. This is source documentation, not evidence that an upstream is deployed.

GET /status

Health check + service info. No parameters.

Response 200

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

Source contract imported from dark web exposure/app.py. Handler: health. Reference: docs/endpoints.md.

Snapshot from docs/endpoints.md for source API version 0.0.2. This is source documentation, not evidence that an upstream is deployed.

GET|POST /password

Breach count for a single password (or pre-computed SHA-1). Cached 90 days.

GET — query params:

POST — JSON body:

{ "password": "testing 123", "include_hash": true }

include_hash defaults to false. If both password and sha1_hash are given, password wins. Never pass both to avoid ambiguity.

Response 200

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

Errors: missing_input 400, password_too_long 400, invalid_hash 400.

Security note: GET /password?password=... places the password in the URL where

it may be logged by proxies. Prefer POST for plaintext.

Source contract imported from dark web exposure/app.py. Handler: check_password. Reference: docs/endpoints.md.

Snapshot from docs/endpoints.md for source API version 0.0.2. This is source documentation, not evidence that an upstream is deployed.

GET|POST /password

Breach count for a single password (or pre-computed SHA-1). Cached 90 days.

GET — query params:

POST — JSON body:

{ "password": "testing 123", "include_hash": true }

include_hash defaults to false. If both password and sha1_hash are given, password wins. Never pass both to avoid ambiguity.

Response 200

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

Errors: missing_input 400, password_too_long 400, invalid_hash 400.

Security note: GET /password?password=... places the password in the URL where

it may be logged by proxies. Prefer POST for plaintext.

Source contract imported from dark web exposure/app.py. Handler: check_password. Reference: docs/endpoints.md.

Snapshot from docs/endpoints.md for source API version 0.0.2. This is source documentation, not evidence that an upstream is deployed.

POST /passwords/batch

Breach counts for up to 100 passwords in one request. Uses k-anonymity: passwords are grouped by SHA-1 prefix, each unique prefix is fetched from HIBP once, and counts are resolved locally — the full hash never leaves your server.

Body

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

Response 200

{
  "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": 0, "breached": false, "sha1_hash": "1E14F1610264EE9A05F26E0B59D2BC9732DEE8B9" }
  ],
  "total": 3,
  "upstream_calls": 2
}

results mirrors the input order; index is the position in passwords. upstream_calls reports how many actual HIBP requests were needed (helps you see cache efficiency).

Errors: missing_input 400, batch_too_large 400, invalid_input 400, password_too_long 400.

Source contract imported from dark web exposure/app.py. Handler: check_passwords_batch. Reference: docs/endpoints.md.

Snapshot from docs/endpoints.md for source API version 0.0.2. This is source documentation, not evidence that an upstream is deployed.

POST /scan/batch

Breach scans for up to 25 identifiers in one request. Results are returned per-identifier; one bad identifier does not fail the batch — it gets an error entry. Uncached identifiers are throttled at SCAN_THROTTLE (default 1.5 s, HIBP's rate limit), so a fully-uncached batch takes ~38 s max.

Body

{
  "identifiers": ["[email protected]", "[email protected]", "adobe.com"],
  "include_pastes": true
}

Response 200

{
  "ok": true,
  "results": [
    { "index": 0, "input": { "type": "email", "value": "[email protected]" },
      "breach_status": "exposed", "breach_count": 3, "sources": ["Adobe", "LinkedIn"],
      "findings": [ { "name": "Adobe", "..." : "..." } ], "pastes": [ ],
      "cached": false, "checked_at": "2026-08-09T07:30:00.000000" },
    { "index": 1, "input": { "value": "[email protected]" },
      "error": { "code": "hibp_key_required", "message": "HIBP_API_KEY env var is not set; account scans are unavailable." } },
    { "index": 2, "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": 3,
  "upstream_calls": 2
}

Each results entry is the same shape as a single /scan response, or an error object when that identifier failed. upstream_calls reports how many HIBP requests were actually made.

Errors: missing_input 400, batch_too_large 400, invalid_input 400.

In production, gunicorn is configured with --timeout 120 so slow uncached

batches complete without being killed (see deployment.md).

Handler compatibility: The POST handler also accepts hibp_api_key as a query parameter; prefer the X-HIBP-API-Key header because query strings may be logged.

Source contract imported from dark web exposure/app.py. Handler: scan_batch. Reference: docs/endpoints.md.

Snapshot from docs/endpoints.md for source API version 0.0.2. This is source documentation, not evidence that an upstream is deployed.

GET /passwords/range

k-anonymity search: given a 5-character SHA-1 prefix, returns every matching hash suffix and its breach count. Enables clients to check passwords **without sending them** or their full hash.

Query params (provide exactly one):

Response 200

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

• suffixes — map of the remaining 35 hash chars → breach count.
• A client checks a password locally: compute SHA-1, take hash[5:], look it up

in suffixes. 0 or missing means not breached.

Errors: invalid_hash 400, invalid_prefix 400.

Input rule: Supply either a five-character prefix or a full 40-character hash; the source derives the prefix from the hash.

Source contract imported from dark web exposure/app.py. Handler: password_range. Reference: docs/endpoints.md.

Snapshot from docs/endpoints.md for source API version 0.0.2. This is source documentation, not evidence that an upstream is deployed.

GET|POST /scan

Breach scan for an email, username, or domain. Cached 90 days per identifier. Legacy params email/username/domain are also accepted in the POST body for backward compatibility.

GET — query params:

POST — JSON body:

{ "identifier": "[email protected]", "include_pastes": true }

Type detection: [email protected] → email; example.com / sub.example.com → domain; alice_doe → username.

Response 200 (domain scan)

{
  "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...",
      "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"
}

Without include_hashes, findings entries omit password_hash/hash_alg. (HIBP does not currently return password hashes in account responses; these fields exist for forward compatibility.)

Errors: missing_identifier 400, invalid_identifier 400, hibp_key_required 503, hibp_rate_limited 429, hibp_error/upstream_error 502.

The HIBP key is only required for email/username scans. Domain scans use

the public breach catalog.

Handler compatibility: The POST handler also accepts hibp_api_key as a query parameter; prefer the X-HIBP-API-Key header because query strings may be logged.

POST input rule: Supply one of identifier, email, username, or domain; the latter three are legacy alternatives.

Source contract imported from dark web exposure/app.py. Handler: scan. Reference: docs/endpoints.md.

Snapshot from docs/endpoints.md for source API version 0.0.2. This is source documentation, not evidence that an upstream is deployed.

GET|POST /scan

Breach scan for an email, username, or domain. Cached 90 days per identifier. Legacy params email/username/domain are also accepted in the POST body for backward compatibility.

GET — query params:

POST — JSON body:

{ "identifier": "[email protected]", "include_pastes": true }

Type detection: [email protected] → email; example.com / sub.example.com → domain; alice_doe → username.

Response 200 (domain scan)

{
  "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...",
      "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"
}

Without include_hashes, findings entries omit password_hash/hash_alg. (HIBP does not currently return password hashes in account responses; these fields exist for forward compatibility.)

Errors: missing_identifier 400, invalid_identifier 400, hibp_key_required 503, hibp_rate_limited 429, hibp_error/upstream_error 502.

The HIBP key is only required for email/username scans. Domain scans use

the public breach catalog.

Handler compatibility: The POST handler also accepts hibp_api_key as a query parameter; prefer the X-HIBP-API-Key header because query strings may be logged.

POST input rule: Supply one of identifier, email, username, or domain; the latter three are legacy alternatives.

Source contract imported from dark web exposure/app.py. Handler: scan. Reference: docs/endpoints.md.

Snapshot from docs/endpoints.md for source API version 0.0.2. This is source documentation, not evidence that an upstream is deployed.

GET /breaches

Full breach catalog. Optional ?domain= filter limits results to breaches involving that domain. Cached 1 day (per domain value).

curl "http://localhost:8000/breaches"
curl "http://localhost:8000/breaches?domain=linkedin.com"

Response 200

{
  "ok": true,
  "count": 923,
  "domain": null,
  "cached": true,
  "breaches": [
    { "Name": "Adobe", "Domain": "adobe.com", "BreachDate": "2013-10-04", "PwnCount": 152445165, "DataClasses": ["Email addresses", "Passwords"], "...": "..." }
  ]
}

Breach entries use HIBP's field names (Name, Title, Domain, BreachDate, AddedDate, ModifiedDate, PwnCount, Description, LogoPath, DataClasses, IsVerified, IsFabricated, IsSensitive, IsRetired, IsSpamList, IsMalware).

Errors: upstream_error 502.

Source contract imported from dark web exposure/app.py. Handler: list_breaches. Reference: docs/endpoints.md.

Snapshot from docs/endpoints.md for source API version 0.0.2. This is source documentation, not evidence that an upstream is deployed.

GET /breaches/latest

The most recently *added* breaches (sorted by HIBP AddedDate, newest first). Shares the same 1-day catalog cache as /breaches, so it costs nothing extra after a catalog fetch.

curl "http://localhost:8000/breaches/latest?limit=10"

Query params

Response 200

{
  "ok": true,
  "count": 10,
  "limit": 10,
  "cached": true,
  "breaches": [ { "Name": "NewBreach", "AddedDate": "2026-08-01T00:00:00Z", "...": "..." } ]
}

Errors: invalid_limit 400, upstream_error 502.

Source contract imported from dark web exposure/app.py. Handler: latest_breaches. Reference: docs/endpoints.md.

Snapshot from docs/endpoints.md for source API version 0.0.2. This is source documentation, not evidence that an upstream is deployed.

GET /breaches/<name>

Details for a single named breach. Cached 1 day.

curl "http://localhost:8000/breaches/Adobe"

Response 200

{
  "ok": true,
  "cached": false,
  "breach": { "Name": "Adobe", "Domain": "adobe.com", "PwnCount": 152445165, "...": "..." }
}

Errors: invalid_name 400, breach_not_found 404, upstream_error 502.

Source contract imported from dark web exposure/app.py. Handler: single_breach. Reference: docs/endpoints.md.

Snapshot from docs/endpoints.md for source API version 0.0.2. This is source documentation, not evidence that an upstream is deployed.

GET /pastes/<account>

Pastebin exposure for an email address or username. Requires HIBP_API_KEY. Cached 1 day.

curl "http://localhost:8000/pastes/[email protected]"

Response 200

{
  "ok": true,
  "account": "[email protected]",
  "count": 2,
  "cached": false,
  "pastes": [
    {
      "Id": "abcdef1234",
      "Source": "Pastebin",
      "Title": "dumps",
      "Date": "2023-01-15T00:00:00Z",
      "EmailCount": 34
    }
  ]
}

Errors: hibp_key_required 503, invalid_account 400, hibp_error/upstream_error 502.

Input rule: Supply the HIBP key in either X-HIBP-API-Key or the compatibility hibp_api_key query parameter; prefer the header.

Source contract imported from dark web exposure/app.py. Handler: account_pastes. Reference: docs/endpoints.md.

Snapshot from docs/endpoints.md for source API version 0.0.2. This is source documentation, not evidence that an upstream is deployed.

GET /data_classes

The fixed list of data classes HIBP uses (e.g. Email addresses, Passwords, Dates of birth). Cached 30 days. Useful for building filters in client apps.

Response 200

{ "ok": true, "count": 53, "cached": true, "data_classes": ["Account balances", "..."] }

Source contract imported from dark web exposure/app.py. Handler: data_classes. Reference: docs/endpoints.md.

Snapshot from docs/endpoints.md for source API version 0.0.2. This is source documentation, not evidence that an upstream is deployed.

GET /stats

Server-side usage analytics: per-endpoint request counters, cache sizes, uptime. Useful to watch from your own monitoring (RapidAPI's dashboard shows its own numbers).

Response 200

{
  "ok": true,
  "uptime_seconds": 86400,
  "total_requests": 15403,
  "endpoint_usage": [
    { "endpoint": "/password", "hits": 8200, "last_hit": "2026-08-09T07:30:00.000000" },
    { "endpoint": "/passwords/batch", "hits": 3121, "last_hit": "2026-08-09T07:29:00.000000" }
  ],
  "cache_entries": { "breaches": 312, "passwords": 4091, "password_ranges": 87, "catalog": 14 }
}

Source contract imported from dark web exposure/app.py. Handler: stats. Reference: docs/endpoints.md.