API referenceCare categories
Records in a care category
GET /v1/care-categories/{slug}/codes
GET https://api.healthcare.dev/v1/care-categories/{slug}/codesCodes (ICD-10-CM, ICD-10-PCS, HCPCS Level II) or drug products (NDC) in this category or any category below it, in code order, each with the category it was assigned (category), confidence and derivation. Retired records are left out unless include_retired=true. A cursor belongs to the category and system it came from. Answers 503 while the system's published version has no care categories yet.
Requires an API key: Authorization: Bearer hdev_live_.... See Authentication.
Path parameters
| Name | Type | Required | Description | Example |
|---|---|---|---|---|
slug | string | yes | Category slug | knee-replacement |
Query parameters
| Name | Type | Required | Description | Example |
|---|---|---|---|---|
system | "icd10cm" | "icd10pcs" | "hcpcs" | "ndc" | yes | Which system's records | icd10pcs |
limit | integer | no | Page size (max 100) | 25 |
cursor | string | no | Opaque cursor from links.next | |
include_retired | "true" | "false" | no | Also return retired records (default false) | true |
view | "compact" | "standard" | "full" | no | How much of each record to return (default full). compact: system, code, display, category (fewest tokens, for agents). standard: every field. full: every field. | compact |
fields | string | no | Comma-separated fields to return instead of a view. Valid fields: system, code, display, status, category, confidence, derivation, href. | system,code,display |
Examples
curl
curl "https://api.healthcare.dev/v1/care-categories/knee-replacement/codes?system=icd10pcs&limit=25" \
-H "Authorization: Bearer $HDEV_API_KEY"TypeScript
const res = await fetch("https://api.healthcare.dev/v1/care-categories/knee-replacement/codes?system=icd10pcs&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/care-categories/knee-replacement/codes?system=icd10pcs&limit=25", headers={"Authorization": f"Bearer {os.environ['HDEV_API_KEY']}"})
body = res.json()Try it
Response
Records, in code order
{
"data": [
{
"system": "icd10cm",
"code": "string",
"display": "string",
"status": "string",
"category": "string",
"confidence": 0,
"derivation": "source_stated",
"href": "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/care-categories/knee-replacement/codes?system=icd10pcs&limit=25",
"next": "/v1/care-categories/knee-replacement/codes?system=icd10pcs&limit=25&cursor=eyJrIjoiRTExLjkifQ"
}
}Fields
| Field | Type | Always present | Description |
|---|---|---|---|
system | CareCategorySystem | yes | |
code | string | yes | The code, or the product NDC for ndc |
display | string | yes | Short description, or the drug's name |
status | string | yes | active or retired |
category | string | yes | Slug of the category it is in (this one or one below it) |
confidence | number | yes | |
derivation | Derivation | yes | source_stated: the source states it explicitly. derived: inferred from the source's text. reviewed: checked by a person against the source. |
href | string | yes | Lookup path for the full record |
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. |