Versioning and changes
API versions, dataset versions and the change feed.
API versions
The major version is in the URL (/v1). Within v1 we only add things: new endpoints, new optional
parameters, new fields. Deprecations are announced six months ahead with Deprecation and
Sunset headers and in the changelog.
Dataset versions
Each upstream release is loaded, checked against quality gates (schema, row counts, golden records)
and published as an immutable version. meta.data_version names it. A bad release never replaces
a good one: it's rejected and the previous version keeps serving.
Change feed
GET /v1/changes?dataset=icd10cm lists records added, changed or retired in each release:
curl "https://api.healthcare.dev/v1/changes?dataset=icd10cm&since=2026-10-01T00:00:00Z" \
-H "Authorization: Bearer $HDEV_API_KEY"Webhooks for the same feed are coming in Phase 2.