Responses
The response envelope, provenance metadata and record lifecycle.
Every successful response has the same shape:
{
"data": {},
"meta": {
"source": "cms-icd10",
"data_version": "2026.1",
"retrieved_at": "2026-10-24T12:00:00Z",
"license": "Public domain (CMS)"
},
"links": { "self": "/v1/codes/icd10cm?q=diabetes", "next": null }
}| Field | Meaning |
|---|---|
data | One record, or a list for searches and listings |
meta.source | Upstream source id (cms-icd10, cms-hcpcs, fda-ndc, nlm-rxnorm) |
meta.data_version | The published dataset release the answer came from |
meta.retrieved_at | When we generated the response |
meta.license | License or attribution terms for the data |
meta.as_of | Present when you asked for a past date with as_of |
links.next | Cursor URL for the next page, null on the last page |
Record lifecycle
Codes and drugs carry status (active, retired, replaced), effective_start and
effective_end (exclusive). Retired records stay available: a code that was valid on a claim
from 2019 still resolves, and replaced_by lists its successors where the source says so.
Pass as_of=YYYY-MM-DD on lookups to get a record as it was on that date.
Caching
Data responses carry a weak ETag that only changes with data_version. Send If-None-Match to
get a 304 with no body. Responses are Cache-Control: private: cache them in your app, not in
shared caches.