# Versioning and changes

URL: https://docs.healthcare.dev/versioning

## 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](/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:

```sh
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.