# Search codes

URL: https://docs.healthcare.dev/reference/codes/search-codes

```http
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](/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**

```sh
curl "https://api.healthcare.dev/v1/codes/icd10cm?q=diabetes&limit=25" \
  -H "Authorization: Bearer $HDEV_API_KEY"
```

**TypeScript**

```ts
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**

```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()
```

## Response

Matching codes, best first

```json
{
  "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](https://www.rfc-editor.org/rfc/rfc9457)). Branch on `type`, not on `title`. See [Errors](/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. |