# Changelog User-visible changes to the Verzi Healthcare Data API and dashboard. Format follows [Keep a Changelog](https://keepachangelog.com/); dates are ISO-8601 UTC. The full commit history is at [github.com/verzihealth/cms-star-ratings](https://github.com/verzihealth/cms-star-ratings). Anything not user-visible (refactors, test-only changes, internal tooling) is deliberately omitted from this log. --- ## [2026-07-02] ### Added - **`/my-usage` HTML dashboard** — the authenticated usage endpoint now serves a styled dashboard to browsers with a tier badge, color-coded usage progress bar (green under 50%, amber under 90%, red at 90%+), tile grid, and a contextual upgrade CTA. JSON shape unchanged for API clients; a new `billing_tier` key is additive. - **JSON-LD structured data** on the six main marketing pages (`/`, `/pricing`, `/quickstart`, `/sources`, `/accuracy`, `/legal/data-disclosure`). Enables Google Rich Results eligibility — pricing tiles as native price cards, quickstart as a HowTo card, `/sources` as a Dataset result. - **`/changelog`** — public user-visible change log (this file). Content-negotiated: browsers get styled HTML, `curl` gets raw markdown. - **`/status`** — public traffic-light health page. Shows real-time state of the four dependencies (PostgreSQL, S3, SES, pipeline freshness). - **`/health/deep`** — deep health check endpoint. Runs live dependency probes. `/health` remains shallow + fast for CI polling. - **`/examples`** and **`/examples/{lang}`** — copy-paste ready code samples in Python, Node.js, curl, Go, and PHP. Browsers get a styled page; `curl` gets the raw source file with the correct MIME type. - **OpenAPI/Swagger enrichment** — 12 endpoints across `hospitals`, `nursing-homes`, `exclusions`, `provider` (npi_profile), `licenses`, and `mips` routers now carry `summary`, `description`, path/query examples, and response payload examples. The Swagger UI at `/docs` "Try it" form now auto-fills with real CCNs, NPIs, and state codes. - **Sitemap now includes `/resources/{slug}` and `/examples/{lang}` URLs** with `lastmod` pulled from each file's mtime — helps search engines prioritize recently-updated content. ### Changed - `/pricing` "Start with Free" CTAs pre-wired to `/billing/checkout?tier=starter` and `?tier=pro`. Currently return `503` until Stripe env vars are set; will flip on live automatically the moment the keys land. - `/quickstart` "What's next" section now leads with `/examples` as the primary CTA (was "Full API Reference"). - `/health` split into shallow (`/health`, unchanged, fast) vs deep (`/health/deep`, runs real dependency probes). --- ## [2026-06-28] ### Added - **`/quickstart`** — 5-minute developer integration guide with tabbed curl / Python / JavaScript samples, endpoint gallery, rate-limit callouts. - **Open Graph social preview cards** — 1200×630 branded PNGs on every marketing page. LinkedIn / Twitter / Slack previews now render with a proper card instead of a bare URL. - **`/sources/{source_id}`** now returns a styled HTML detail page in browsers (was JSON-only). Completes the `/sources/*` HTML family (list, detail, history). - **`/resources` catalog + `/resources/{slug}`** rendered documents — the methodology docs (API Style Guide, Accuracy Benchmark, HCA Case Study, License Intelligence, Financial Intelligence, Employment Reconciliation) are now browsable as styled HTML with the site's brand chrome. `curl` still gets raw markdown. - **`robots.txt`** and **`sitemap.xml`** for search-engine discovery. Allows public marketing surfaces; blocks admin / billing internals. ### Fixed - `/billing/plans` legacy URL 301s to the canonical `/pricing`. Old page said "17 data sources" and referenced the wrong tier limits. --- ## [2026-06-27] ### Added - **`/sources/{source_id}/history`** HTML — per-source refresh audit timeline with status-colored markers, four stat tiles (session count, success rate, last run, last status), and a smart empty state. - **`/accuracy`** HTML — the marquee proof page. Four summary tiles (median variance, mean variance, systems within ±10%, within ±25%), methodology callout, sorted results table with color-coded variance (green/amber/red), and a ground-truth submission invitation. - **`/platform/stats`** HTML — live dashboard with pulse-animated "refreshed Xs ago" badge, four stat tiles (data rows, sources, facilities, clinicians), last-pipeline-run card with status pill. - SEO + Open Graph meta tags across seven public pages (description, `og:title`, `og:description`, `og:type`, `og:site_name`, `og:url`, `twitter:card`). - **`/pricing`** page with four tiers (Free / $49 Starter / $199 Pro / Enterprise), FAQ, and cross-sell to the executive dashboard. - **Shared content-negotiation helper** (`api/providers/_shared/content_negotiation.py:prefers_html`) — same URL serves HTML to browsers and JSON to API clients based on `Accept` header + explicit `?format=` override. ### Changed - **`BILLING_TIERS`** aligned with the new 4-tier pricing (Free 10K/day, Starter 50K/day, Pro 500K/day, Enterprise 10M/day). Was 3 tiers with stale limits. - **`/billing/checkout`** accepts a `?tier=` query param (starter or pro). Tier flows through Stripe checkout metadata so the webhook upgrades to the right tier. ### Fixed - `test_admin::test_get_organization` was failing because it referenced a `starter` tier that didn't exist in `BILLING_TIERS`. Now passes. --- ## [2026-06-26] ### Added - **Live source catalog at `/sources`** — every dataset we ingest with license, refresh cadence, accuracy class, and last-loaded state. 38 sources across CMS (13), other federal (5 — OIG, HRSA, CDC, AHRQ, Census/OMB), academic (1 — Dartmouth), state open-data (1 — CA Medical Board), commercial (2 — Google Maps, FMP), and Verzi-original layers (13). Same URL serves JSON to API clients. - **Per-source refresh history at `/sources/{source_id}/history`** — every load attempt, success or failure, with timing and row-count deltas. - **`/platform/stats`** endpoint — live row counts, source counts, facility / clinician counts, last pipeline run status. Backs the marketing numbers without hardcoding them. - **Data Use & Disclosure Statement** at `/legal/data-disclosure` — canonical, version-controlled statement of which datasets we ingest, under what license, and our HIPAA classification. Maintained outside the auto-generated Terms/Privacy so Termly regenerations can't wipe substantive disclosure. - **LoadSession instrumentation** — every pipeline loader run now records a session row (`source_id`, `started_at`, `completed_at`, `status`, `rows_loaded`, `error_message`) to the `load_sessions` table. ### Changed - Homepage stats now fetch from `/platform/stats` via Next.js ISR (1-hour revalidation) instead of hardcoded strings. Row counts stop drifting. - Data source attribution rewritten across README, `PROJECT_OVERVIEW`, `terms.html`, `privacy.html`, and the homepage to reflect the full 30+ source catalog (CMS, HHS OIG, HRSA, CDC, AHRQ, IRS, DOL, SEC EDGAR, Census, Dartmouth, plus commercial APIs) instead of claiming CMS-only. Every `312M+ rows` / `27 sources` reference updated to live counts or durable phrasing. - Signup form bot-prevention hardening: honeypot field, disposable email denylist, per-IP rate limit, Cloudflare Turnstile scaffolded and env-flag-gated. ### Fixed - Migration tooling: `run_migrations.py --stamp` bootstrap flag, cleaner prod auth flow via AWS Secrets Manager (`cms-dev/postgres-credentials`), fixed URL-encoding issue with prod password. --- ## [2026-06-17] ### Added - **Financial Intelligence** product layer — IRS Form 990 deep XML pipeline (Schedule R + Schedule J), DOL Form 5500 loader, SEC EDGAR 10-K via FMP for 30 curated public healthcare tickers. - **`financial_filings`** table — cross-source EIN × filing_type × tax_period_end unified store. 15K+ rows. - **`executive_compensation`** table — Schedule J + 10-K NEO records, 267 entries with matched NPIs for clinician-executives. - **Financial Intelligence API endpoints**: `/systems/{id}/financials`, `/systems/{id}/financials/executives`, `/systems/{id}/financials/workforce`, `/companies/{ticker}`, `/companies/search`, `/ma-events/recent`, `/provider/{npi}/financial-affiliation`. --- ## [2026-06-16] ### Changed - **API consolidation**: `/quality` nested under `/provider`, `/quality` router renamed to `/mips`, fixed `/systems` route collision. --- ## [2026-06-11] ### Added - **License + Quality Intelligence v1** - `provider_licenses` (5M+ NPI-keyed licenses derived from NPPES taxonomy across all 50 states) - `license_disciplinary_actions` (8.5K OIG LEIE joined to NPI) - License Intelligence API: `/licenses/state/{state}`, `/licenses/{npi}`, `/licenses/{npi}/disciplinary`, `/licenses/alerts/recent` - Quality Intelligence API: `/quality/{npi}`, `/quality/leaderboards/{specialty}`, `/quality/systems/{system_id}` - Extended `/provider/{npi}` dossier with new `license_intelligence`, `quality_intelligence`, `employment_intelligence` blocks --- ## [2026-06-10] ### Added - **Physician Employment Intelligence v2** — multi-source attribution, HCA wedge - `org_eins`, `employment_attribution_signals`, `system_hierarchy` tables - HCA decomposed into 14 divisions - Accuracy benchmark at `/accuracy` — headline: HCA at +2.8% variance - **Physician Employment Intelligence v1** — initial employer typology product - `physician_employer_systems`, `employer_facts` materialized view - 12 API endpoints at `/provider/*`, `/employers/*`, `/systems/*` --- ## Older Prior to 2026-06-10, changes were tracked via git log only. The last major additions before that date were VBC/ACO analytics, HCAHPS benchmarking materialized views, market intelligence (HSAF), community health (CDC PLACES, Medicare Geographic Variation, AHRQ SDOH), and the initial 9 CMS provider-type ingestion. --- ## How to read this - **Added** — new endpoints, tables, or user-visible features - **Changed** — modifications to existing behavior (usually backward-compatible) - **Fixed** — bugs or inconsistencies resolved - **Deprecated** — features scheduled for removal (none yet) - **Removed** — features removed (none yet) - **Security** — security-relevant changes (none breaking; hardening only) For the machine-readable API changelog, hit `curl https://api.healthcaredata.io/changelog` — returns raw markdown.