# DisclosureLens

> Near-real-time, machine-readable feed of formally-filed breach
> disclosures worldwide — SEC 8-K Item 1.05, US state attorney-general
> notifications (18 states), HHS OCR breach reports, EU DPA and
> Singapore PDPC enforcement decisions, press coverage, and ransomware
> leak-site claims. REST/JSON, cursor-paginated, ~24 live sources.

Base URL: https://api.disclosurelens.com/v1
OpenAPI spec (no key needed): https://api.disclosurelens.com/openapi.json
Human docs: https://disclosurelens.com/docs
Methodology + field semantics: https://disclosurelens.com/methodology
Terms: https://disclosurelens.com/terms

## Essentials

- Auth: `Authorization: Bearer df_…` on every request. Free read-scoped
  keys at https://disclosurelens.com/settings/api-keys after sign-up.
  Health endpoints and the OpenAPI spec need no key.
- Envelope: list responses are `{data: [...], meta: {...}}`. Every data
  response carries `meta.ai_assisted: true` (EU AI Act Art. 50) and
  `meta.attribution` — reuse of the data requires the attribution
  "Data: DisclosureLens (https://disclosurelens.com)". Payloads carrying
  third-party leak/press data add `meta.upstream_attribution`; honor it.
- Errors: always `{"error": {"code", "message"[, "fields"]}}`.
- THE single most important integration fact: to sync or mirror, poll
  `/v1/disclosures?updated_after=<watermark>&sort=updated_asc` and page
  the cursor — NEVER poll `filed_after` (regulator filing dates lag our
  ingestion by months-to-years for archive-backfilled sources, so a
  filed-date window silently misses most new records). Use
  `created_after` + `sort=created_asc` for reproducible snapshots.
- Rate limits: 5 req/min on the free inquiry tier, 600 at casework, 6,000
  at watchtower, metered per API key; `x-ratelimit-*` and `retry-after`
  response headers.
- Webhooks: 1 endpoint on the free inquiry tier, 20 at casework, unlimited
  at watchtower. Delivery is per-record on every plan; only the endpoint
  COUNT is tiered.
- Bulk export: open to every signed-up account, metered as daily runs per
  plan (1 free / 100 casework, scoped to an entity or incident / unmetered
  at watchtower). Resuming an interrupted stream with `updated_after` draws
  on a separate continuation budget rather than a new run.
- Search: `?search=` (alias `q`) on /v1/disclosures; `?q=` (alias
  `search`) on /v1/entities. Leak-site claims and press reports are
  hidden from lists/aggregates unless `include_leak_site=true`.

# BEGIN GENERATED ENDPOINT INDEX (make codegen)
## disclosures
- GET https://api.disclosurelens.com/v1/disclosures — List disclosures
- GET https://api.disclosurelens.com/v1/disclosures/facets — Facet bucket counts
- GET https://api.disclosurelens.com/v1/disclosures/{disclosure_id} — Single disclosure with classification
- GET https://api.disclosurelens.com/v1/disclosures/{disclosure_id}/successor — Where a record retracted as a duplicate went
- GET https://api.disclosurelens.com/v1/disclosures/{disclosure_id}/related — Related disclosures for the same incident
- GET https://api.disclosurelens.com/v1/disclosures/{disclosure_id}/extraction — Extraction provenance for a disclosure

## incidents
- GET https://api.disclosurelens.com/v1/incidents — List incidents
- GET https://api.disclosurelens.com/v1/incidents/{incident_id} — Single incident with linked disclosures
- GET https://api.disclosurelens.com/v1/incidents/{incident_id}/litigation_timeline — Incident litigation timeline [paid tier]
- GET https://api.disclosurelens.com/v1/incidents/{incident_id}/cross_filing_comparison — Cross-filing comparison matrix [paid tier]

## entities
- GET https://api.disclosurelens.com/v1/entities — Search entities by name or identifier
- POST https://api.disclosurelens.com/v1/entities/resolve/batch — Resolve a batch of raw names to entities (read-only) [watchtower tier]
- GET https://api.disclosurelens.com/v1/entities/browse — Name-ordered entity browse index
- GET https://api.disclosurelens.com/v1/entities/{entity_id} — Single entity profile
- GET https://api.disclosurelens.com/v1/entities/{entity_id}/disclosures — Disclosures linked to an entity
- GET https://api.disclosurelens.com/v1/entities/{entity_id}/scorecard — Entity compliance scorecard

## stats
- GET https://api.disclosurelens.com/v1/stats/compliance_distribution — Compliance flag distribution
- GET https://api.disclosurelens.com/v1/stats/time_to_disclose_percentiles — Time-to-disclose percentiles by vertical
- GET https://api.disclosurelens.com/v1/stats/disclosure_timing_by_jurisdiction — Disclosure-timing benchmark by regime and state
- GET https://api.disclosurelens.com/v1/stats/late_disclosure_leaderboard — Late-disclosure entity leaderboard
- GET https://api.disclosurelens.com/v1/stats/compliance_trend — Monthly compliance trend
- GET https://api.disclosurelens.com/v1/stats/overview — Corpus overview counts and freshness
- GET https://api.disclosurelens.com/v1/stats/daily — Daily filing counts by source type
- GET https://api.disclosurelens.com/v1/stats/jurisdictions — Filing counts by jurisdiction
- GET https://api.disclosurelens.com/v1/stats/geography — Geography Stats
- GET https://api.disclosurelens.com/v1/stats/source_health — Per-source freshness summary
- GET https://api.disclosurelens.com/v1/stats/time_to_disclose — Time-to-disclose histogram
- GET https://api.disclosurelens.com/v1/stats/records_affected — Records-affected distribution
- GET https://api.disclosurelens.com/v1/stats/data_types — Counts per affected data type
- GET https://api.disclosurelens.com/v1/stats/data_elements — Counts per statutory data element
- GET https://api.disclosurelens.com/v1/stats/top_cves — Top CVEs by mention count
- GET https://api.disclosurelens.com/v1/stats/data_quality_events — Data-quality events in a window
- GET https://api.disclosurelens.com/v1/stats/extraction_quality — Review-status mix by source type
- GET https://api.disclosurelens.com/v1/stats/incidents_by_merge_method — Incident counts by merge method
- GET https://api.disclosurelens.com/v1/stats/incidents_jurisdictions_cardinality — Incident jurisdiction-count bands
- GET https://api.disclosurelens.com/v1/stats/incidents_lead_time — Leak-to-filing lead-time percentiles
- GET https://api.disclosurelens.com/v1/stats/press_first — Press-first incidents + press→filing lead time
- GET https://api.disclosurelens.com/v1/stats/claim_corroboration — Share of leak-site claims later corroborated
- GET https://api.disclosurelens.com/v1/stats/translated_count — Machine-translated records in a window
- GET https://api.disclosurelens.com/v1/stats/incidents_merge_confidence — Incident merge-confidence buckets
- GET https://api.disclosurelens.com/v1/stats/incidents_source_combos — Incident counts by source combination
- GET https://api.disclosurelens.com/v1/stats/frequency_severity — Vertical by severity-tier crosstab
- GET https://api.disclosurelens.com/v1/stats/records_affected_bands — Records-affected bands with Wilson CI
- GET https://api.disclosurelens.com/v1/stats/data_types_mix_shift — Monthly data-type mix shift
- GET https://api.disclosurelens.com/v1/stats/repeat_offenders — Repeat-offender entity ranking
- GET https://api.disclosurelens.com/v1/stats/source_cadence — Per-source monthly cadence with anomalies
- GET https://api.disclosurelens.com/v1/stats/enforcement — Regulator enforcement rollup
- GET https://api.disclosurelens.com/v1/stats/source_archive — Preserved-archive size and cross-source utility for one source

## analytics
- POST https://api.disclosurelens.com/v1/analytics/comparable_incidents — Comparable-incident cohort stats [paid tier]
- GET https://api.disclosurelens.com/v1/analytics/unreported_claims — Unreported leak-site claims early warning [paid tier]
- POST https://api.disclosurelens.com/v1/analytics/underwriting_brief — Broker underwriting brief [paid tier]
- POST https://api.disclosurelens.com/v1/analytics/freq_severity_curve — Notification-exposure (records) log-normal fit [paid tier]
- POST https://api.disclosurelens.com/v1/analytics/portfolio_rating — Portfolio risk rating [paid tier]
- GET https://api.disclosurelens.com/v1/analytics/entity_scorecard.pdf — Signed entity scorecard PDF [paid tier]
- GET https://api.disclosurelens.com/v1/analytics/compliance_report.pdf — Signed compliance report PDF [paid tier]
- GET https://api.disclosurelens.com/v1/analytics/broker_benchmark_letter.pdf — Signed broker benchmark letter PDF [paid tier]
- POST https://api.disclosurelens.com/v1/analytics/portfolio_scorecard — Portfolio compliance scorecard [watchtower tier]
- GET https://api.disclosurelens.com/v1/analytics/portfolio_scorecard.pdf — Signed portfolio compliance scorecard PDF [watchtower tier]
- GET https://api.disclosurelens.com/v1/analytics/entity_compliance_distribution — Entity position in its sector's clock distribution [paid tier]
- GET https://api.disclosurelens.com/v1/analytics/evidence_package.pdf — Signed incident evidence package PDF [paid tier]

## export
- GET https://api.disclosurelens.com/v1/export/disclosures.ndjson — Streaming NDJSON export

## source
- GET https://api.disclosurelens.com/v1/disclosures/{disclosure_id}/source/manifest — Source artifact manifest
- GET https://api.disclosurelens.com/v1/disclosures/{disclosure_id}/source/artifacts/{artifact_id} — Archived source artifact body

## threat-actors
- GET https://api.disclosurelens.com/v1/threat-actors — List ransomware groups with victim counts
- GET https://api.disclosurelens.com/v1/threat-actors/{slug} — Enriched threat-actor profile

## supply-chain
- GET https://api.disclosurelens.com/v1/supply-chain/cascades — List confirmed supply-chain cascades
- GET https://api.disclosurelens.com/v1/supply-chain/cascades/{cascade_id} — One confirmed cascade with its members

## scan
- GET https://api.disclosurelens.com/v1/scan — Name a domain's third-party vendors and check them for breach records
- GET https://api.disclosurelens.com/v1/scan/connection — Name the connectivity vendors behind a caller's own IP

## subscriptions
- GET https://api.disclosurelens.com/v1/me/subscriptions/decay — Watched-entity decay proposals
- GET https://api.disclosurelens.com/v1/me/subscriptions — List my email subscriptions
- POST https://api.disclosurelens.com/v1/me/subscriptions — Create an email subscription (idempotent)
- PATCH https://api.disclosurelens.com/v1/me/subscriptions/{subscription_id} — Update an email subscription
- DELETE https://api.disclosurelens.com/v1/me/subscriptions/{subscription_id} — Delete an email subscription

## watchlists
- GET https://api.disclosurelens.com/v1/me/watchlists — List my watchlists
- POST https://api.disclosurelens.com/v1/me/watchlists — Create a watchlist (idempotent on name)
- GET https://api.disclosurelens.com/v1/me/watchlists/{watchlist_id} — Get a watchlist with its entries and channels
- PATCH https://api.disclosurelens.com/v1/me/watchlists/{watchlist_id} — Rename a watchlist
- DELETE https://api.disclosurelens.com/v1/me/watchlists/{watchlist_id} — Delete a watchlist (deactivates its channels)
- POST https://api.disclosurelens.com/v1/me/watchlists/{watchlist_id}/entries — Add entries to a watchlist (bulk, idempotent)
- DELETE https://api.disclosurelens.com/v1/me/watchlists/{watchlist_id}/entries/{entity_id} — Remove one entry from a watchlist
- POST https://api.disclosurelens.com/v1/me/watchlists/{watchlist_id}/subscribe — Create the email alert for a watchlist
- GET https://api.disclosurelens.com/v1/me/watchlists/{watchlist_id}/decay — Watchlist decay proposals

## api-keys
- GET https://api.disclosurelens.com/v1/me/api-keys — List my API keys
- POST https://api.disclosurelens.com/v1/me/api-keys — Create an API key (secret shown once)
- DELETE https://api.disclosurelens.com/v1/me/api-keys/{key_id} — Revoke an API key

## health
- GET https://api.disclosurelens.com/v1/health — Liveness probe
- GET https://api.disclosurelens.com/healthz — Liveness probe
- GET https://api.disclosurelens.com/v1/health/ready — Readiness probe (DB connectivity)
- GET https://api.disclosurelens.com/v1/health/pdf — PDF signing cert health
- GET https://api.disclosurelens.com/v1/health/extract — LLM extraction pipeline health
- GET https://api.disclosurelens.com/v1/health/entity-resolution — Entity-resolution pipeline health
- GET https://api.disclosurelens.com/v1/health/dedup — Incident-dedup pipeline health
- GET https://api.disclosurelens.com/v1/health/sources — Per-source ingestion health

## webhooks
- GET https://api.disclosurelens.com/v1/me/webhooks — List my webhook endpoints
- POST https://api.disclosurelens.com/v1/me/webhooks — Create a webhook endpoint (idempotent)
- GET https://api.disclosurelens.com/v1/me/webhooks/{endpoint_id}/secret — Reveal an endpoint's signing secret
- POST https://api.disclosurelens.com/v1/me/webhooks/{endpoint_id}/rotate-secret — Rotate an endpoint's signing secret
- PATCH https://api.disclosurelens.com/v1/me/webhooks/{endpoint_id} — Update a webhook endpoint
- DELETE https://api.disclosurelens.com/v1/me/webhooks/{endpoint_id} — Delete a webhook endpoint
- GET https://api.disclosurelens.com/v1/me/webhooks/{endpoint_id}/deliveries — Recent delivery attempts for an endpoint
- POST https://api.disclosurelens.com/v1/me/webhooks/{endpoint_id}/test — Send a test event to an endpoint
# END GENERATED ENDPOINT INDEX

## Reuse

Free for public-interest use with attribution. Claims sourced from
ransomware leak sites are allegations, not verified breaches — the API
labels them `source_category: "claim"`; never present them as confirmed.
Contact: contact@disclosurelens.com