# healthcare.dev

> One REST API, MCP server, TypeScript SDK and CLI for current, versioned US healthcare reference
> data: ICD-10-CM, ICD-10-PCS, HCPCS Level II, FDA NDC, RxNorm, with NPI providers coming next.
> Reference data only, not medical, clinical or billing advice. Never send patient information (PHI).

- API base URL: https://api.healthcare.dev/v1 (auth: `Authorization: Bearer hdev_live_...`)
- OpenAPI 3.1 spec: https://api.healthcare.dev/openapi.json (also https://docs.healthcare.dev/openapi.json)
- Remote MCP server (Streamable HTTP): https://mcp.healthcare.dev/mcp
- Local MCP server: `npx -y @healthcare.dev/mcp` with `HDEV_API_KEY`
- Every docs page has a Markdown version: append `.md` to its URL.
- Every response is `{ data, meta: { source, data_version, retrieved_at, license }, links? }`;
  errors are RFC 9457 `application/problem+json`.

## Docs

- [healthcare.dev](https://docs.healthcare.dev/index.md): One API for current, versioned US healthcare reference data. REST, MCP, TypeScript SDK and CLI.
- [Quickstart](https://docs.healthcare.dev/quickstart.md): Get a key and make your first call in under two minutes.
- [Authentication](https://docs.healthcare.dev/authentication.md): API keys, live and test keys, and keeping keys out of browsers.
- [Responses](https://docs.healthcare.dev/responses.md): The response envelope, provenance metadata and record lifecycle.
- [Errors](https://docs.healthcare.dev/errors.md): RFC 9457 problem details with stable type codes.
- [Rate limits and quotas](https://docs.healthcare.dev/rate-limits.md): Per-second limits, monthly quotas and the RateLimit headers.
- [Pagination and batch](https://docs.healthcare.dev/pagination.md): Cursor pagination for lists and batch lookups of up to 100 ids.
- [Versioning and changes](https://docs.healthcare.dev/versioning.md): API versions, dataset versions and the change feed.
- [Changelog](https://docs.healthcare.dev/changelog.md): API, SDK, MCP and docs changes. Dataset releases are in the change feed.
- [Status and data freshness](https://docs.healthcare.dev/status.md): Live service status and the current version of every dataset.

## Datasets

- [ICD-10-CM](https://docs.healthcare.dev/datasets/icd10cm.md): US diagnosis codes from CMS and CDC NCHS, with billable flags, hierarchy and full history.
- [ICD-10-PCS](https://docs.healthcare.dev/datasets/icd10pcs.md): US inpatient procedure codes from CMS.
- [HCPCS Level II](https://docs.healthcare.dev/datasets/hcpcs.md): CMS HCPCS Level II codes for supplies, drugs, equipment and services, updated quarterly.
- [NDC Directory](https://docs.healthcare.dev/datasets/ndc.md): FDA National Drug Code Directory: products, packages and RxNorm links, refreshed daily.
- [RxNorm](https://docs.healthcare.dev/datasets/rxnorm.md): NLM RxNorm Current Prescribable Content: normalized clinical drug names, ingredients and NDC links.
- [NPI registry (coming soon)](https://docs.healthcare.dev/datasets/npi.md): CMS NPPES: every US provider NPI with names, addresses and taxonomy codes.
- [Provider taxonomy (licensing)](https://docs.healthcare.dev/datasets/taxonomy.md): NUCC Health Care Provider Taxonomy codes. Not public yet: the code set needs a commercial license.

## MCP server

- [MCP server](https://docs.healthcare.dev/mcp.md): Give AI agents direct, cited access to US healthcare reference data over the Model Context Protocol.
- [Claude](https://docs.healthcare.dev/mcp/claude.md): Connect Claude Code, Claude Desktop or claude.ai to the healthcare.dev MCP server.
- [Cursor](https://docs.healthcare.dev/mcp/cursor.md): Use healthcare.dev tools in Cursor's agent.
- [VS Code](https://docs.healthcare.dev/mcp/vscode.md): Use healthcare.dev tools in GitHub Copilot agent mode.
- [Codex](https://docs.healthcare.dev/mcp/codex.md): Use healthcare.dev tools in the OpenAI Codex CLI.
- [Tools](https://docs.healthcare.dev/mcp/tools.md): Every MCP tool, with an example and when not to use it.

## SDK and CLI

- [TypeScript SDK](https://docs.healthcare.dev/guides/typescript.md): @healthcare.dev/sdk: typed client with retries, pagination and batch helpers.
- [CLI](https://docs.healthcare.dev/guides/cli.md): hdev: look up codes, drugs and NPIs from the terminal.

## Agents

- [Agent skill](https://docs.healthcare.dev/agents/skill.md): A SKILL.md coding agents can load to use healthcare.dev correctly without reading the docs.
- [Recipes](https://docs.healthcare.dev/agents/recipes.md): Worked examples for the tasks agents do most.
- [Example: referral checker](https://docs.healthcare.dev/agents/referral-checker.md): An agent that checks a referral's NPI and diagnosis codes before it's sent.
- [Example: claim code validator](https://docs.healthcare.dev/agents/claim-code-validator.md): Validate the diagnosis, procedure and HCPCS codes on a claim against the release in effect on the date of service.
- [Example: prescription lookup assistant](https://docs.healthcare.dev/agents/prescription-lookup.md): Resolve a drug name or NDC from a pharmacy system to RxNorm concepts and package details.

## API reference

- [Overview](https://docs.healthcare.dev/reference.md): Every endpoint of the healthcare.dev API, generated from the OpenAPI 3.1 spec.
- [Look up a code](https://docs.healthcare.dev/reference/codes/look-up-a-code.md): GET /v1/codes/{system}/{code}
- [Search codes](https://docs.healthcare.dev/reference/codes/search-codes.md): GET /v1/codes/{system}
- [Child codes](https://docs.healthcare.dev/reference/codes/child-codes.md): GET /v1/codes/{system}/{code}/children
- [Ancestor codes](https://docs.healthcare.dev/reference/codes/ancestor-codes.md): GET /v1/codes/{system}/{code}/parents
- [Code with ancestors and children](https://docs.healthcare.dev/reference/codes/code-with-ancestors-and-children.md): GET /v1/codes/{system}/{code}/hierarchy
- [Look up up to 100 codes](https://docs.healthcare.dev/reference/codes/look-up-up-to-100-codes.md): POST /v1/codes/{system}/batch
- [Look up an NDC](https://docs.healthcare.dev/reference/drugs/look-up-an-ndc.md): GET /v1/drugs/ndc/{ndc}
- [Look up an RxNorm concept](https://docs.healthcare.dev/reference/drugs/look-up-an-rxnorm-concept.md): GET /v1/drugs/rxnorm/{rxcui}
- [Search RxNorm](https://docs.healthcare.dev/reference/drugs/search-rxnorm.md): GET /v1/drugs/rxnorm
- [Search drugs across RxNorm and NDC](https://docs.healthcare.dev/reference/drugs/search-drugs-across-rxnorm-and-ndc.md): GET /v1/drugs/search
- [Dataset catalog](https://docs.healthcare.dev/reference/datasets/dataset-catalog.md): GET /v1/datasets
- [Change feed](https://docs.healthcare.dev/reference/datasets/change-feed.md): GET /v1/changes
- [Look up a provider taxonomy code](https://docs.healthcare.dev/reference/taxonomies/look-up-a-provider-taxonomy-code.md): GET /v1/taxonomies/{code}
- [Search provider taxonomies](https://docs.healthcare.dev/reference/taxonomies/search-provider-taxonomies.md): GET /v1/taxonomies
- [Process liveness](https://docs.healthcare.dev/reference/service/process-liveness.md): GET /healthz
- [Dependency readiness](https://docs.healthcare.dev/reference/service/dependency-readiness.md): GET /readyz
- [Service and data freshness status](https://docs.healthcare.dev/reference/service/service-and-data-freshness-status.md): GET /v1/status