API referenceCodes
Search codes
GET /v1/codes/{system}
GET https://api.healthcare.dev/v1/codes/{system}Search by description or code prefix. Exact code matches rank first, then code prefixes, then descriptions containing every word of the query (stemmed, any order) by relevance, then close matches for typos. Retired codes are excluded unless include_retired=true.
Requires an API key: Authorization: Bearer hdev_live_.... See Authentication.
Path parameters
| Name | Type | Required | Description | Example |
|---|---|---|---|---|
system | "icd10cm" | "icd10pcs" | "hcpcs" | yes | Code system | icd10cm |
Query parameters
| Name | Type | Required | Description | Example |
|---|---|---|---|---|
q | string | yes | Search text (fuzzy) | diabetes |
limit | integer | no | Page size (max 100) | 25 |
cursor | string | no | Opaque cursor from links.next | |
billable | "true" | "false" | no | Only billable (true) or header (false) codes | true |
include_retired | "true" | "false" | no | Also return retired codes (default false) | true |
view | "compact" | "full" | no | compact returns only the fields an agent usually needs (fewer tokens); full (default) returns every field | compact |
fields | string | no | Comma-separated record fields to return, e.g. code,display,billable | code,display,billable |
Examples
curl
curl "https://api.healthcare.dev/v1/codes/icd10cm?q=diabetes&limit=25" \
-H "Authorization: Bearer $HDEV_API_KEY"TypeScript
const res = await fetch("https://api.healthcare.dev/v1/codes/icd10cm?q=diabetes&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/codes/icd10cm?q=diabetes&limit=25", headers={"Authorization": f"Bearer {os.environ['HDEV_API_KEY']}"})
body = res.json()Try it
Response
Matching codes, best first
{
"data": [
{
"system": "icd10cm",
"code": "string",
"display": "string",
"description": "string",
"billable": true,
"parent": "string",
"attributes": {},
"status": "active",
"effective_start": "2026-10-01",
"effective_end": "2026-10-01",
"replaced_by": [
"string"
],
"match_score": 0
}
],
"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/codes/icd10cm?q=diabetes&limit=25",
"next": "/v1/codes/icd10cm?q=diabetes&limit=25&cursor=eyJrIjoiRTExLjkifQ"
}
}Fields
| Field | Type | Always present | Description |
|---|---|---|---|
system | "icd10cm" | "icd10pcs" | "hcpcs" | yes | |
code | string | yes | |
display | string | yes | Short description |
description | string | null | yes | Long description |
billable | boolean | yes | Valid for billing (leaf / header flag) |
parent | string | null | yes | |
attributes | object | no | System-specific attributes, e.g. HCPCS coverage and BETOS codes |
status | "active" | "retired" | "replaced" | yes | |
effective_start | string (date) | yes | |
effective_end | string | null (date) | yes | |
replaced_by | string[] | no | |
match_score | number | yes | How well this result matches the query: 1 exact code or id, 0.9 code prefix, 0.5 to 0.9 every query word in the text (higher is closer), under 0.5 a fuzzy (typo-tolerant) match. Below 0.5, check the result before relying on it. |
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. |