API referenceDatasets
Releases and what changed
GET /v1/datasets/{dataset}/releases
GET https://api.healthcare.dev/v1/datasets/{dataset}/releasesEvery published release of a dataset, newest first, with how many records it added, changed (revised) and retired, when the source published it and when we did. On every plan. The records themselves are in the change feed (changes links to /v1/changes?dataset=&version=, Builder and up). Retired records stay answerable with status: retired and, where known, replaced_by.
Requires an API key: Authorization: Bearer hdev_live_.... See Authentication.
Path parameters
| Name | Type | Required | Description | Example |
|---|---|---|---|---|
dataset | string | yes | Dataset id from /v1/datasets | icd10cm |
Query parameters
| Name | Type | Required | Description | Example |
|---|---|---|---|---|
limit | integer | no | Page size, 1 to 100 (default 25) | 25 |
cursor | string | no | Opaque cursor from links.next | |
version | string | no | Only this release (data_version) | fy2027 |
Examples
curl
curl "https://api.healthcare.dev/v1/datasets/icd10cm/releases?limit=25" \
-H "Authorization: Bearer $HDEV_API_KEY"TypeScript
const res = await fetch("https://api.healthcare.dev/v1/datasets/icd10cm/releases?limit=25", {
headers: { Authorization: `Bearer ${process.env.HDEV_API_KEY}` },
});
const { data, meta } = await res.json();Python
import os
import requests
res = requests.get("https://api.healthcare.dev/v1/datasets/icd10cm/releases?limit=25", headers={"Authorization": f"Bearer {os.environ['HDEV_API_KEY']}"})
body = res.json()Try it
Response
Releases, newest first
{
"data": [
{
"dataset": "string",
"version": "string",
"status": "current",
"effective_date": "2026-10-01",
"published_at": "2026-10-24T12:00:00Z",
"source_published_at": "2026-10-24T12:00:00Z",
"source_published_basis": "last-modified",
"lag_hours": 0,
"baseline": true,
"records": 1,
"added": 1,
"changed": 1,
"retired": 1,
"changes": "string"
}
],
"meta": {
"source": "cms-icd10",
"data_version": "2026.1",
"retrieved_at": "2026-10-24T12:00:00Z",
"license": "Public domain (CMS). Reference data, not medical advice."
},
"links": {
"self": "/v1/datasets/icd10cm/releases?limit=25",
"next": "/v1/datasets/icd10cm/releases?limit=25&cursor=eyJrIjoiRTExLjkifQ"
}
}Fields
| Field | Type | Always present | Description |
|---|---|---|---|
dataset | string | yes | |
version | string | yes | The release's data_version |
status | "current" | "superseded" | yes | current is the version served now; older releases are superseded |
effective_date | string (date) | yes | Date the release takes effect |
published_at | string (date-time) | yes | When we published it |
source_published_at | string | null (date-time) | yes | When the source published it |
source_published_basis | "last-modified" | "metadata" | "file-name" | "detected" | null | yes | Where source_published_at comes from: the source file's Last-Modified, the source's own metadata (an API or index date), the date in the release's file name, or detected (the source gives no date: the first time our pipeline saw the release, an estimate) |
lag_hours | number | null | yes | Hours from the source publishing this release to us publishing it |
baseline | boolean | yes | The first load of the dataset: every record counts as added and the change feed has no rows for it |
records | integer | null | yes | Records in the release, retired ones included |
added | integer | yes | Records new in this release |
changed | integer | yes | Records revised in this release |
retired | integer | yes | Records retired in this release |
changes | string | null | yes | The release's records in the change feed (/v1/changes, Builder and up); null for a baseline |
Errors
Errors are application/problem+json (RFC 9457). Branch on type, not on title. See Errors.
| Status | type | When |
|---|---|---|
| 400 | invalid-request | A parameter or the body failed validation; errors lists each field. |
| 401 | unauthorized | Missing, malformed or revoked API key. |
| 404 | not-found | No record with that id (retired records are still returned). |
| 429 | rate-limited / quota-exceeded | Too many requests per second (retry after Retry-After), or the monthly quota is used up. |
| 503 | dataset-unavailable / unavailable | The dataset has no published version yet, or the service is degraded. |