# Code search

Status: LIVE
Price: $0.005 USDC
`GET /api/codes/search`
HTML: https://magentlab.com/docs/code-search
Markdown: https://magentlab.com/docs/code-search.md

Not a medical device. Not a diagnosis, dose, or listing recommendation.

## What it computes

Rank a natural-language drug, diagnosis, or lab phrase to current RxNorm, ICD-10-CM, or LOINC codes from the local catalog.

## When to use

When an agent must not hallucinate or invent a billing or pharmacy code. Pay-per-request; empty matches is a valid paid 200.

## When not to use

- ICD-10 in this product means ICD-10-CM (US claims), not WHO ICD-10.
- Production coverage is Current Prescribable RxNorm + ICD-10-CM + LOINC (gold-gated full). Not complete monthly RxNorm or UMLS.
- Not a billing submission and not a medical device. Do not send names or MRNs.

## Formula

```
Rank local catalog matches by token/prefix score; return current RxNorm, ICD-10-CM, or LOINC. Empty matches is a valid paid 200.
```

## Citation

Current Prescribable RxNorm, CMS ICD-10-CM, and LOINC
NLM, CMS, Regenstrief Institute
Local catalog. Production coverage is Current Prescribable RxNorm + ICD-10-CM + LOINC after gold gate. Not complete UMLS.
DOI: none

## Worked example

### Tylenol 500mg → RxNorm

Given: `query=Tylenol 500mg, system=rxnorm`

1. Normalize the query and rank local catalog rows by token/prefix score.
2. Best current RxNorm hit is code 198440.
3. Empty matches is a valid paid 200; magent does not invent a code.


## Parameters

- `query` (string, required): Natural-language drug, diagnosis, or lab description. Max 512 characters. Do not send patient names.
- `system` (string, optional): Restrict to rxnorm, icd10 (ICD-10-CM), or loinc. Omit to search all.
- `tty` (string, optional): Restrict term type. Pharmacy orders typically want SCD. ICD-10-CM is CM; LOINC is LN.
- `limit` (integer, optional): Number of ranked matches to return (1-25). Default 5.
- `min_score` (integer, optional): Minimum rank score 0-100. Default 35.
- `include_obsolete` (boolean, optional): Include deprecated/obsolete codes. Default false.
- `billable_only` (boolean, optional): ICD-10-CM: return only HIPAA billable codes, not headers. Default true.

## Bulk (POST)

POST the same path with a JSON items array. Price is n times the GET unit. Invalid items return HTTP 400 before settlement.

Method: `POST /api/codes/search`
Max items: 25
Price: unit_amount * n (unit 5000 atomic)
Status: PREVIEW

- 1 to 25 items. Each item uses the same keys as the GET query parameters.
- The first invalid item fails the whole request (index in the 400 JSON). You are not charged.
- HTTP 200 is {count, path, items}. Each items[i] is the GET 200 body for that row.
- Catalog misses (empty matches, found=false) stay paid 200s inside that slot.
- x402 resource URL is this path plus n and body_sha256. Browsers that prefer text/html get the same paywall as GET; Pay retries POST with the same items.

Example request:

```json
{
  "items": [
    {
      "query": "Tylenol 500mg",
      "system": "rxnorm"
    },
    {
      "query": "Tylenol 500mg",
      "system": "rxnorm"
    }
  ]
}
```

Human paywall (two-item fixture): https://api.magentlab.com/paywall/bulk/code-search

Example 200:

```json
{
  "count": 2,
  "path": "/api/codes/search",
  "items": [
    {
      "system": "rxnorm",
      "matches": [
        {
          "code": "198440",
          "status": "current",
          "system": "rxnorm",
          "display": "acetaminophen 500 MG Oral Tablet",
          "tty": "SCD",
          "obsolete": false,
          "score": 95,
          "billable": null
        }
      ],
      "query": "Tylenol 500mg",
      "disclaimer": "Not a medical device. Deterministic published-formula or published-code output for autonomous agents. A licensed clinician remains responsible for patient care and billing submissions.",
      "catalog": {
        "coverage": "seed",
        "notes": "ICD-10 entries are ICD-10-CM (US claims), not WHO ICD-10. RxNorm codes are RxCUI. LOINC codes are official LOINC numerics.",
        "source": "magent curated seed",
        "systems": [
          "rxnorm",
          "icd10",
          "loinc"
        ],
        "version": "2026.08-wedge"
      },
      "match_count": 1,
      "match_quality": "high"
    },
    {
      "system": "rxnorm",
      "matches": [
        {
          "code": "198440",
          "status": "current",
          "system": "rxnorm",
          "display": "acetaminophen 500 MG Oral Tablet",
          "tty": "SCD",
          "obsolete": false,
          "score": 95,
          "billable": null
        }
      ],
      "query": "Tylenol 500mg",
      "disclaimer": "Not a medical device. Deterministic published-formula or published-code output for autonomous agents. A licensed clinician remains responsible for patient care and billing submissions.",
      "catalog": {
        "coverage": "seed",
        "notes": "ICD-10 entries are ICD-10-CM (US claims), not WHO ICD-10. RxNorm codes are RxCUI. LOINC codes are official LOINC numerics.",
        "source": "magent curated seed",
        "systems": [
          "rxnorm",
          "icd10",
          "loinc"
        ],
        "version": "2026.08-wedge"
      },
      "match_count": 1,
      "match_quality": "high"
    }
  ]
}
```

## Response fields

- `query` (string): Echo of the submitted query
- `system` (string): rxnorm, icd10, loinc, or all
- `match_count` (integer): Number of ranked matches returned
- `match_quality` (string): none, low, or high
- `matches` (array): Ranked codes. First row is the best deterministic hit.
- `catalog` (object): Seed vs ingested vs full coverage metadata
- `disclaimer` (string): Not-a-device notice

## Example JSON

Frozen fixture. Not a live lookup.

```json
{
  "system": "rxnorm",
  "matches": [
    {
      "code": "198440",
      "status": "current",
      "system": "rxnorm",
      "display": "acetaminophen 500 MG Oral Tablet",
      "tty": "SCD",
      "obsolete": false,
      "score": 95,
      "billable": null
    }
  ],
  "query": "Tylenol 500mg",
  "disclaimer": "Not a medical device. Deterministic published-formula or published-code output for autonomous agents. A licensed clinician remains responsible for patient care and billing submissions.",
  "catalog": {
    "coverage": "seed",
    "notes": "ICD-10 entries are ICD-10-CM (US claims), not WHO ICD-10. RxNorm codes are RxCUI. LOINC codes are official LOINC numerics.",
    "source": "magent curated seed",
    "systems": [
      "rxnorm",
      "icd10",
      "loinc"
    ],
    "version": "2026.08-wedge"
  },
  "match_count": 1,
  "match_quality": "high"
}
```

## Errors

- HTTP 400 `invalid_query`: query is required and must be 1-512 characters Returned before settlement; you are not charged.
- HTTP 400 `invalid_system`: system must be rxnorm, icd10, or loinc Returned before settlement; you are not charged.
- HTTP 400 `invalid_tty`: tty must be a known RxNorm, ICD-10-CM, or LOINC term type Returned before settlement; you are not charged.
- HTTP 400 `invalid_limit`: limit must be an integer from 1 to 25 Returned before settlement; you are not charged.
- HTTP 400 `invalid_min_score`: min_score must be an integer from 0 to 100 Returned before settlement; you are not charged.
- HTTP 400 `invalid_items`: POST body must be a JSON object with only an items array Returned before settlement; you are not charged.
- HTTP 400 `invalid_item_count`: items must be an array of 1 to 25 objects Returned before settlement; you are not charged.
- HTTP 400 `invalid_item`: each items entry must be a JSON object Returned before settlement; you are not charged.
- HTTP 402 `payment_required`: Missing or invalid PAYMENT-SIGNATURE; decode the PAYMENT-REQUIRED header
- HTTP 409 `payment_in_progress`: The same authorization nonce is already being settled; retry shortly
- HTTP 429 `rate_limited`: Too many requests from this client
- HTTP 503 `settlement_uncertain`: Settlement is unconfirmed; retry with the same PAYMENT-SIGNATURE
- HTTP 503 `facilitator_unavailable`: Payment facilitator unavailable
- HTTP 503 `facilitator_misconfigured`: Payment facilitator is not configured
- HTTP 503 `facilitator_unauthorized`: Payment facilitator rejected credentials
- HTTP 503 `ledger_unavailable`: Payment ledger unavailable
- HTTP 503 `payment_unavailable`: Payment processing unavailable

## Related tools

- [Code lookup](https://magentlab.com/docs/code-lookup) — Look up a current RxNorm, ICD-10-CM, or LOINC preferred term from an exact published code.

## Also searched as

- RxNorm translation
- ICD-10-CM lookup
- LOINC code search
- Tylenol 500mg RxNorm

## Payment

Required query parameters must be present and valid. Invalid params return HTTP 400 JSON before settlement. magent does not charge. Fix the params, then request a new 402 quote for that complete URL. Catalog misses (empty matches, found=false) are valid paid 200s.

## Guarantees

- Invalid query parameters return HTTP 400 before settlement. You are not charged.
- Settlement finishes before the tool executes. Uncertain settlement fails closed (HTTP 503).
- Execution is timeout-bounded and concurrency-capped.
- Calculator inputs are not persisted. Request logs store path without query.