The healthcare reference data your AI agent actually needs

If you're building an agent that drafts claims, checks credentialing files, or answers billing questions, there's a specific failure mode worth designing around: a large language model will produce a plausible-looking NPI or ICD-10 code from its training data or from pattern-matching, and that code will be wrong in a way that's invisible until it fails downstream — a rejected claim, a denied credentialing application, a wrong drug-interaction lookup keyed off the wrong diagnosis.

Why hallucinated codes are dangerous here

Unlike a hallucinated fact in a chat response, a hallucinated NPI or ICD-10 code often looks completely legitimate — the right number of digits, the right letter-plus-digits shape, sometimes even a real code, just the wrong one for the clinical picture described. Neither the model nor a casual human reviewer catches this reliably by inspection. The fix isn't a better prompt; it's giving the agent a deterministic, authoritative lookup it calls instead of generating the answer from memory.

What an agent needs, specifically

• NPI resolution against the live CMS NPPES registry — not a stale training-data snapshot, since providers change addresses, taxonomies and status continuously.
• ICD-10-CM lookup and validation against the current official release, including the billable/header distinction — a header code submitted as if it were billable is a common and avoidable agent mistake.
• NUCC taxonomy resolution, for anything that needs to map a specialty description to (or from) a structured code.
• Batch validation, so an agent can check an entire claim or roster in one call instead of one identifier at a time.

None of this is exotic data — it's all public. The value of wiring it in isn't proprietary information, it's turning "the model's best guess" into "a verified lookup against the primary source," which is the difference between an agent that's useful in production and one that quietly generates plausible-looking errors.

Wiring it into an agent — REST

Any agent framework that can make an HTTP call can use the plain REST API directly:

• curl "https://patientary.com/api/v1/npi?last_name=smith&state=CA&taxonomy=cardiology"
• curl https://patientary.com/api/v1/icd10/E11.9
• curl -X POST https://patientary.com/api/v1/validate -H "Content-Type: application/json" -d '{"npis":["1245319599"],"icd10":["E11.9","Z00.00"]}'

Every response includes a `request_id` and a `disclaimer` field, and calls are anonymous-friendly and rate-limited by IP for light use — an API key (`Authorization: Bearer ptn_live_…`) raises the limit and unlocks batch validation and monitoring.

Wiring it into an agent — MCP

For agent frameworks that speak MCP, `POST /api/mcp` exposes the same data as first-class tools: `lookup_npi`, `search_providers`, `lookup_icd10`, `search_icd10`, `validate_codes` and `lookup_taxonomy`. That means an agent can call `validate_codes` before it proposes a diagnosis code the same way it would call any other tool — no custom HTTP client code, no bespoke parsing, and the tool schema documents exactly what arguments are expected.

Machine-readable docs

The full endpoint reference is also published as OpenAPI (`/api/openapi`) and as a plain-text summary at `/llms.txt`, specifically so an agent (or the developer configuring one) doesn't have to scrape a marketing page to figure out what's callable.

The honesty contract

Patientary is a reference layer over public data, not a coding or billing authority — every response carries a disclaimer to that effect, and final code assignment remains the responsibility of a qualified professional. What it does guarantee is that a lookup reflects the actual current source (NPPES, the CMS ICD-10-CM release, NUCC), instead of a model's best guess at what that source probably says.