# Responses

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

Every successful response has the same shape:

```json
{
  "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.