### Quick Start: Search dm+d with Fhirfly

Source: https://fhirfly.io/docs/search-apis/dmd

Quick start example for searching dm+d concepts using the Fhirfly client. Requires an API key and the @fhirfly-io/terminology package.

```javascript
import { Fhirfly } from "@fhirfly-io/terminology";

const client = new Fhirfly({ apiKey: "YOUR_API_KEY" });

// Search for paracetamol products
const results = await client.dmd.search({
  q: "paracetamol"
});

console.log(`Found ${results.total} concepts`);
for (const item of results.items) {
  console.log(`[${item.concept_type}] ${item.code}: ${item.display}`);
}
```

--------------------------------

### Response shape examples (HTTP)

Source: https://fhirfly.io/docs/value-apis/loinc

Example GET requests using the shape query parameter to control response detail: compact, standard (default), and full.

```HTTP
# Minimal data
GET /v1/loinc/2339-0?shape=compact

# Standard data (default)
GET /v1/loinc/2339-0?shape=standard

# Full data with provenance
GET /v1/loinc/2339-0?shape=full
```

--------------------------------

### Install @fhirfly-io/shl and @fhirfly-io/terminology

Source: https://fhirfly.io/docs/shl/ehr-integration

Install the required SDK packages for EHR integration.

```bash
npm install @fhirfly-io/shl @fhirfly-io/terminology

```

--------------------------------

### initialize

Source: https://fhirfly.io/docs/mcp/api-reference

Start an MCP session and negotiate capabilities.

```APIDOC
## initialize

### Description
Start an MCP session and negotiate capabilities.

### Method
JSON-RPC 2.0 method

### Endpoint
POST /mcp

### Parameters
#### Request Body
- **jsonrpc** (string) - Required - Must be "2.0"
- **id** (number) - Required - Request ID
- **method** (string) - Required - Must be "initialize"
- **params.protocolVersion** (string) - Required - Protocol version (e.g., "2024-11-05")
- **params.capabilities** (object) - Optional - Client capabilities
- **params.clientInfo.name** (string) - Required - Client name
- **params.clientInfo.version** (string) - Required - Client version

### Request Example
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": {
      "name": "my-mcp-client",
      "version": "1.0.0"
    }
  }
}

### Response
#### Success Response (200)
- **result.protocolVersion** (string) - Protocol version
- **result.capabilities.tools** (object) - Server capabilities
- **result.serverInfo.name** (string) - Server name

#### Response Example
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "tools": {}
    },
    "serverInfo": {
      "name": "fhirfly-mcp-server"
    }
  }
}
```

--------------------------------

### Install SHL SDK

Source: https://fhirfly.io/docs/shl/quickstart

Install the base SHL package or include the terminology package for FHIRfly API enrichment.

```bash
npm install @fhirfly-io/shl
```

```bash
npm install @fhirfly-io/shl @fhirfly-io/terminology
```

--------------------------------

### Configure Claude Desktop for Global Installation

Source: https://fhirfly.io/docs/mcp/claude-desktop

Use this configuration when the server is installed globally.

```json
{
  "mcpServers": {
    "fhirfly": {
      "command": "fhirfly-mcp-server",
      "env": {
        "FHIRFLY_API_KEY": "ffly_your_api_key_here"
      }
    }
  }
}
```

--------------------------------

### Install FHIRfly SDK via npm

Source: https://fhirfly.io/docs/getting-started/quickstart

Install the FHIRfly SDK from npm using the package name @fhirfly-io/terminology.

```bash
npm install @fhirfly-io/terminology

```

--------------------------------

### Install FHIRfly MCP Server Globally

Source: https://fhirfly.io/docs/mcp/claude-desktop

Install the package globally using npm if you prefer not to use npx.

```bash
npm install -g @fhirfly-io/mcp-server
```

--------------------------------

### Initialize S3Storage

Source: https://fhirfly.io/docs/shl/storage-adapters

Install the required AWS SDK dependency and configure the S3Storage adapter for production workloads.

```bash
npm install @aws-sdk/client-s3
```

```typescript
const storage = new SHL.S3Storage({
  bucket: "my-shl-bucket",
  region: "us-east-1",
  baseUrl: "https://shl.example.com",
  prefix: "shl-data/", // optional
});
```

--------------------------------

### Example Response from dm+d Search

Source: https://fhirfly.io/docs/search-apis/dmd

Example response from the dm+d search endpoint. Shows facets, items, pagination, and legal metadata.

```json
{
  "facets": {
    "concept_type": {
      "VMP": 45,
      "AMP": 120,
      "VMPP": 38,
      "AMPP": 95,
      "VTM": 2
    }
  },
  "has_more": true,
  "items": [
    {
      "code": "90332006",
      "code_system": "dm+d",
      "concept_type": "VTM",
      "name": "Paracetamol",
      "display": "Paracetamol"
    },
    {
      "code": "39732311000001104",
      "code_system": "dm+d",
      "concept_type": "VMP",
      "name": "Paracetamol 500mg tablets",
      "display": "Paracetamol 500mg tablets"
    }
  ],
  "limit": 2,
  "meta": {
    "legal": {
      "attribution_required": true,
      "citation": "dm+d, NHS England / NHSBSA. Crown copyright. Open Government Licence v3.0.",
      "license": "OGL-UK-3.0",
      "source_name": "NHS dm+d"
    }
  },
  "page": 1,
  "total": 300,
  "total_capped": false
}
```

--------------------------------

### Install @fhirfly-io/shl package

Source: https://fhirfly.io/docs/shl/troubleshooting

Install the SHL SDK package using npm. Requires Node.js 18+ for built-in crypto and fetch support.

```bash
npm install @fhirfly-io/shl
```

--------------------------------

### Quick Start: Search HCPCS Codes with Node.js

Source: https://fhirfly.io/docs/search-apis/hcpcs

Quick start example for searching HCPCS codes with the FHIRfly Node.js client. Requires an API key and the @fhirfly-io/terminology package. Searches for 'ambulance' and logs the total count and each code/display pair.

```javascript
import { Fhirfly } from "@fhirfly-io/terminology";

const client = new Fhirfly({ apiKey: "YOUR_API_KEY" });

// Search for ambulance-related HCPCS codes
const results = await client.hcpcs.search({
  q: "ambulance"
});

console.log(`Found ${results.total} codes`);
for (const item of results.items) {
  console.log(`${item.code}: ${item.display}`);
}
```

--------------------------------

### Batch Request Example

Source: https://fhirfly.io/docs/getting-started/rate-limits

Node.js example using the lookupMany method to fetch multiple items in one request, which counts as a single request toward the rate limit.

```javascript
const result = await client.ndc.lookupMany([
  "0069-0151-01",
  "0069-0152-01",
  "0069-0153-01"
]);
console.log(`Found ${result.data.found} drugs`);
```

--------------------------------

### CVX API shape query parameter examples

Source: https://fhirfly.io/docs/value-apis/cvx

Shows three GET requests to /v1/cvx/207 with shape=compact, shape=standard (default), and shape=full to control response detail levels.

```http
# Minimal data
GET /v1/cvx/207?shape=compact

# Standard data (default)
GET /v1/cvx/207?shape=standard

# Full data with provenance
GET /v1/cvx/207?shape=full
```

--------------------------------

### Initialize Session Request

Source: https://fhirfly.io/docs/mcp/api-reference

Start an MCP session and negotiate capabilities with the server.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": {
      "name": "my-mcp-client",
      "version": "1.0.0"
    }
  }
}
```

--------------------------------

### API Key format examples

Source: https://fhirfly.io/docs/getting-started/authentication

Distinguish between production and test/sandbox environments using the API key prefix.

```text
ffly_sk_live_abc123...  # Production key
ffly_sk_test_abc123...  # Test/sandbox key
```

--------------------------------

### Rate Limit Headers Example

Source: https://fhirfly.io/docs/getting-started/rate-limits

Example of rate limit headers included in every API response, showing the limit, remaining requests, and reset timestamp.

```http
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 115
X-RateLimit-Reset: 1704067200
```

--------------------------------

### RxClass members response example

Source: https://fhirfly.io/docs/value-apis/rxclass

Example JSON response for the members endpoint, showing the class details and a list of member drugs.

```json
{
  "data": {
    "class_id": "N0000175355",
    "class_name": "Angiotensin 2 Receptor Blocker",
    "member_count": 8,
    "members": [
      {
        "rxcui": "83818",
        "name": "valsartan",
        "tty": "IN"
      },
      {
        "rxcui": "52175",
        "name": "losartan",
        "tty": "IN"
      },
      {
        "rxcui": "29046",
        "name": "irbesartan",
        "tty": "IN"
      },
      {
        "rxcui": "321064",
        "name": "olmesartan",
        "tty": "IN"
      }
    ]
  },
  "meta": {
    "legal": {
      "license": "UMLS",
      "source_name": "RxClass"
    }
  }
}
```

--------------------------------

### Quick Start Node.js

Source: https://fhirfly.io/docs/search-apis/npi

Initialize the Fhirfly client and perform a search for cardiologists in California.

```javascript
import { Fhirfly } from "@fhirfly-io/terminology";

const client = new Fhirfly({ apiKey: "YOUR_API_KEY" });

// Search for cardiologists in California
const results = await client.npi.search({
  q: "cardiology",
  state: "CA"
});

console.log(`Found ${results.total} providers`);
for (const item of results.items) {
  console.log(`${item.npi}: ${item.name} (${item.location})`);
}
```

--------------------------------

### Example Response: Metformin search results

Source: https://fhirfly.io/docs/search-apis/ndc

Shows the JSON response structure returned by the NDC search endpoint, including facets, items, pagination, and legal metadata. The example uses limit=2 and shows a total of 186 products.

```JSON
{
  "facets": {
    "dosage_form": {
      "TABLET": 186
    },
    "product_type": {
      "HUMAN PRESCRIPTION DRUG": 170,
      "DRUG FOR FURTHER PROCESSING": 16
    },
    "route": {
      "ORAL": 170
    }
  },
  "has_more": true,
  "items": [
    {
      "active": true,
      "generic": "Metformin ER 500 mg",
      "labeler": "Aphena Pharma Solutions - Tennessee, LLC",
      "name": "Metformin",
      "ndc": "71610-613",
      "type": "product"
    },
    {
      "active": true,
      "generic": "Metformin ER 500 mg",
      "labeler": "A-S Medication Solutions",
      "name": "Metformin",
      "ndc": "50090-6515",
      "type": "product"
    }
  ],
  "limit": 2,
  "meta": {
    "legal": {
      "attribution_required": false,
      "citation": "FDA NDC Directory. Accessed 2026-01-28 via FHIRfly.",
      "license": "public_domain",
      "source_name": "FDA NDC Directory"
    }
  },
  "page": 1,
  "total": 186,
  "total_capped": false
}
```

--------------------------------

### DocumentReference PSHD Example Output

Source: https://fhirfly.io/docs/shl/pshd

An example of a DocumentReference resource formatted according to PSHD profile constraints, including specific coding, category, author, and security meta fields.

```json
{
  "resourceType": "DocumentReference",
  "status": "current",
  "type": {
    "coding": [{
      "system": "http://loinc.org",
      "code": "60591-5",
      "display": "Patient summary Document"
    }]
  },
  "category": [{
    "coding": [{
      "system": "https://cms.gov/fhir/CodeSystem/patient-shared-category",
      "code": "patient-shared",
      "display": "Patient Shared"
    }]
  }],
  "author": [{ "reference": "urn:uuid:<patient-id>" }],
  "meta": {
    "security": [{
      "system": "http://terminology.hl7.org/CodeSystem/v3-ActCode",
      "code": "PATAST",
      "display": "patient asserted"
    }]
  },
  "content": [{
    "attachment": {
      "contentType": "application/pdf",
      "url": "urn:uuid:<binary-id>",
      "title": "Patient Summary"
    }
  }]
}
```

--------------------------------

### Quick Start Node.js Search

Source: https://fhirfly.io/docs/search-apis/ucum

Initializes the FHIRfly client and performs a basic search for mass units.

```javascript
import { Fhirfly } from "@fhirfly-io/terminology";

const client = new Fhirfly({ apiKey: "YOUR_API_KEY" });

// Search for mass units
const results = await client.ucum.search({
  q: "milligram"
});

console.log(`Found ${results.total} units`);
for (const item of results.items) {
  console.log(`${item.code}: ${item.display}`);
}
```

--------------------------------

### List States response example (JSON)

Source: https://fhirfly.io/docs/sma/api-reference

Shows the JSON response structure for the List States endpoint, including state summaries, total count, and meta information. The example includes two states (California and Colorado) with Epic as the vendor and patient access status 'In Production'.

```JSON
{
  "states": [
    {
      "id": "california",
      "state": "California",
      "abbreviation": "CA",
      "is_implemented": true,
      "api_vendor": "Epic",
      "patient_access_status": "In Production",
      "provider_directory_status": "In Production",
      "production_url_count": 5,
      "fhir_version": "4.0.1"
    },
    {
      "id": "colorado",
      "state": "Colorado",
      "abbreviation": "CO",
      "is_implemented": true,
      "api_vendor": "Epic",
      "patient_access_status": "In Production",
      "provider_directory_status": "In Production",
      "production_url_count": 3,
      "fhir_version": "4.0.1"
    }
  ],
  "total": 2,
  "meta": {
    "data_as_of": "2026-03-01T00:00:00Z",
    "source": "CMS SMA Endpoint Directory",
    "source_url": "https://github.com/CMSgov/SMA-Endpoint-Directory"
  }
}
```

--------------------------------

### Quick Start Node.js

Source: https://fhirfly.io/docs/search-apis/cvx

Initialize the FHIRfly client and perform a basic search for COVID vaccines.

```javascript
import { Fhirfly } from "@fhirfly-io/terminology";

const client = new Fhirfly({ apiKey: "YOUR_API_KEY" });

// Search for COVID vaccines
const results = await client.cvx.search({
  q: "covid"
});

console.log(`Found ${results.total} vaccines`);
for (const item of results.items) {
  console.log(`${item.code}: ${item.display}`);
}
```

--------------------------------

### Initialize AzureStorage

Source: https://fhirfly.io/docs/shl/storage-adapters

Install the required Azure storage dependency and configure the AzureStorage adapter using a connection string.

```bash
npm install @azure/storage-blob
```

```typescript
const storage = new SHL.AzureStorage({
  container: "shl-data",
  connectionString: process.env.AZURE_STORAGE_CONNECTION_STRING,
  baseUrl: "https://shl.example.com",
  prefix: "shl-data/", // optional
});
```

--------------------------------

### GET /v1/snomed/:concept_id

Source: https://fhirfly.io/docs/value-apis/snomed

Example of a single concept lookup using the SNOMED CT API.

```APIDOC
## GET /v1/snomed/:concept_id

### Description
Retrieve a single SNOMED CT concept by its concept ID from the IPS Free Set.

### Method
GET

### Endpoint
/v1/snomed/:concept_id

### Parameters
#### Path Parameters
- **concept_id** (string) - Required - The SNOMED CT concept identifier (e.g., 73211009).

### Request Example
No request body required.

### Response
#### Success Response (200)
- **data** (object) - Contains the concept details.
  - **concept_id** (string) - The SNOMED CT concept identifier.
  - **active** (boolean) - Whether the concept is active.
  - **fsn** (string) - The fully specified name.
  - **preferred_term** (string) - The preferred term.
  - **synonyms** (array of strings) - List of synonyms.
  - **ips_category** (string) - The IPS category.
  - **semantic_tag** (string) - The semantic tag.
- **meta** (object) - Metadata about the source and legal information.
  - **source** (object) - Source details.
    - **name** (string) - Source name.
    - **url** (string) - Source URL.
    - **version** (string) - Source version.
  - **legal** (object) - Legal information.
    - **license** (string) - License type.
    - **attribution_required** (boolean) - Whether attribution is required.
    - **source_name** (string) - Source name.
    - **citation** (string) - Citation text.

#### Response Example
```json
{
  "data": {
    "concept_id": "73211009",
    "active": true,
    "fsn": "Diabetes mellitus (disorder)",
    "preferred_term": "Diabetes mellitus",
    "synonyms": [
      "DM - Diabetes mellitus",
      "Diabetes mellitus, NOS"
    ],
    "ips_category": "condition",
    "semantic_tag": "disorder"
  },
  "meta": {
    "source": {
      "name": "SNOMED CT IPS Free Set",
      "url": "https://www.snomed.org/our-standards/ips-terminology",
      "version": "IPS 1.1.0"
    },
    "legal": {
      "license": "CC BY 4.0",
      "attribution_required": true,
      "source_name": "SNOMED CT IPS Free Set",
      "citation": "SNOMED CT IPS Free Set. SNOMED International. Licensed under CC BY 4.0."
    }
  }
}
```
```

--------------------------------

### Run a full round-trip demo with fhirfly-shl demo

Source: https://fhirfly.io/docs/shl/cli-reference

Runs a full round-trip demo: builds an IPS bundle, creates an SHL, and optionally starts a server. Options include --port and --no-serve.

```bash
fhirfly-shl demo [options]
```

--------------------------------

### fhirfly-shl demo

Source: https://fhirfly.io/docs/shl/cli-reference

Runs a full round-trip demo: builds an IPS bundle, creates an SHL, and optionally starts a server. Supports port and no-serve options.

```APIDOC
## fhirfly-shl demo

### Description
Runs a full round-trip demo: build IPS bundle, create SHL, optionally start server.

### Usage
fhirfly-shl demo [options]

### Options
- `--port <number>` - Server port (default: `3456`)
- `--no-serve` - Skip starting the local server

```

--------------------------------

### Retrieve OPCS-4 code data with different shape parameters

Source: https://fhirfly.io/docs/value-apis/opcs4

Examples of GET requests for OPCS-4 codes using compact, standard, and full response shapes.

```http
# Minimal data
GET /v1/opcs4/W37.1?shape=compact

# Standard data (default)
GET /v1/opcs4/W37.1?shape=standard

# Full data with provenance
GET /v1/opcs4/W37.1?shape=full
```

--------------------------------

### Look up MUE limits for an office visit

Source: https://fhirfly.io/docs/claims/mue

Example request to retrieve MUE limits for HCPCS code 99213 using the GET /v1/mue/:hcpcs endpoint.

```javascript
const response = await fetch(
  "https://api.fhirfly.io/v1/mue/99213",
  {
    method: "GET",
    headers: {
    "x-api-key": "YOUR_API_KEY",
  }
  }
);

const data = await response.json();
console.log(data);
```

--------------------------------

### Initialize GCSStorage

Source: https://fhirfly.io/docs/shl/storage-adapters

Install the required Google Cloud storage dependency and configure the GCSStorage adapter for GCP deployments.

```bash
npm install @google-cloud/storage
```

```typescript
const storage = new SHL.GCSStorage({
  bucket: "my-shl-bucket",
  baseUrl: "https://shl.example.com",
  prefix: "shl-data/", // optional
});
```

--------------------------------

### Retrieve dm+d data with different shape parameters

Source: https://fhirfly.io/docs/value-apis/dmd

Examples of GET requests to the dm+d API using the shape query parameter to control the level of detail in the response.

```http
# Minimal data
GET /v1/dmd/39732311000001104?shape=compact

# Standard data (default)
GET /v1/dmd/39732311000001104?shape=standard

# Full data with provenance
GET /v1/dmd/39732311000001104?shape=full
```

--------------------------------

### Show CLI help with npx @fhirfly-io/shl --help

Source: https://fhirfly.io/docs/shl/cli-reference

Displays the CLI help and available commands.

```bash
npx @fhirfly-io/shl --help
```

--------------------------------

### Requesting HCC data with different shape parameters

Source: https://fhirfly.io/docs/value-apis/hcc

Examples of GET requests for HCC data using the compact, standard, and full shape query parameters to control response detail.

```http
# Minimal data
GET /v1/hcc/E11.9?shape=compact

# Standard data (default)
GET /v1/hcc/E11.9?shape=standard

# Full data with provenance
GET /v1/hcc/E11.9?shape=full
```

--------------------------------

### Reverse Lookup with model_version Filter (GET)

Source: https://fhirfly.io/docs/value-apis/hcc

Use the model_version query parameter to filter reverse lookup results to a specific CMS-HCC model. This example requests HCC 19 with model version V24.

```HTTP
GET /v1/hcc/reverse/19?model_version=V24
```

--------------------------------

### Run the live exercise integration test

Source: https://fhirfly.io/docs/shl/overview

Run the comprehensive integration test that exercises all SDK paths against the live API. Requires an API key and optionally the --verbose flag. Useful for smoke-testing deployment or as a usage reference.

```bash
npx tsx examples/live-exercise/index.ts --api-key <key> --verbose
```

--------------------------------

### Forward Lookup with model_version Filter (GET)

Source: https://fhirfly.io/docs/value-apis/hcc

Use the model_version query parameter to filter forward lookup results to a specific CMS-HCC model. This example requests ICD-10 code E11.9 with model version V28.

```HTTP
GET /v1/hcc/E11.9?model_version=V28
```

--------------------------------

### Low-Level PSHD Mode and Profile Options

Source: https://fhirfly.io/docs/shl/pshd

Use mode: "direct" and profile: "pshd" independently for fine-grained control. The first example shows direct mode without PSHD bundle constraints; the second shows building a PSHD bundle profile without direct mode.

```javascript
// Direct mode without PSHD bundle constraints
const result = await SHL.create({
  bundle: anyFhirBundle,    // does not need to be a PSHD bundle
  storage,
  mode: "direct",           // flag U, single-request retrieval
  expiresAt: new Date(Date.now() + 60 * 60_000),  // optional here
});
```

```javascript
// PSHD bundle profile without direct mode
const fhirBundle = await bundle.build({ profile: "pshd" });
// produces a collection bundle with CMS DocumentReference constraints
```

--------------------------------

### ICD-10 API shape parameter examples

Source: https://fhirfly.io/docs/value-apis/icd10

Shows three GET requests to the ICD-10 API endpoint `/v1/icd10/E11.9` with different `shape` values: `compact`, `standard` (default), and `full`. Use these to control the level of detail in responses.

```http
# Minimal data
GET /v1/icd10/E11.9?shape=compact

# Standard data (default)
GET /v1/icd10/E11.9?shape=standard

# Full data with provenance
GET /v1/icd10/E11.9?shape=full
```

--------------------------------

### Get SMA details for California - JSON response

Source: https://fhirfly.io/docs/sma/api-reference

Example JSON response for the California state request. Shows the structure including patient access endpoints, provider directory, contacts, and metadata. The response is 69 lines long.

```JSON
{
  "id": "california",
  "state": "California",
  "abbreviation": "CA",
  "api_vendor": "Epic",
  "survey_date": "2026-01-15",
  "is_implemented": true,
  "patient_access": {
    "status": "In Production",
    "implementation_date": "2024-07-01",
    "fhir_version": "4.0.1",
    "auth_protocol": "OAuth 2.0",
    "refresh_frequency": "Daily",
    "endpoints": {
      "claims": [
        "https://fhir.example.ca.gov/R4/Claims"
      ],
      "pdex": [
        "https://fhir.example.ca.gov/R4/PDex"
      ],
      "formulary": [
        "https://fhir.example.ca.gov/R4/Formulary"
      ],
      "chip": [],
      "capability_statement": [
        "https://fhir.example.ca.gov/R4/metadata"
      ],
      "sandbox": [
        "https://sandbox.fhir.example.ca.gov/R4"
      ]
    }
  },
  "provider_directory": {
    "status": "In Production",
    "implementation_date": "2024-07-01",
    "fhir_version": "4.0.1",
    "is_public": true,
    "refresh_frequency": "Weekly",
    "endpoints": {
      "production": [
        "https://pd.fhir.example.ca.gov/R4"
      ],
      "capability_statement": [
        "https://pd.fhir.example.ca.gov/R4/metadata"
      ],
      "sandbox": []
    }
  },
  "contacts": {
    "member_phone": "1-800-555-0100",
    "member_email": "members@example.ca.gov",
    "developer_contact": "developer@example.ca.gov",
    "pd_developer_contact": null,
    "registration_info": "https://developer.example.ca.gov/register",
    "pd_registration_info": null
  },
  "all_production_urls": [
    "https://fhir.example.ca.gov/R4/Claims",
    "https://fhir.example.ca.gov/R4/PDex",
    "https://fhir.example.ca.gov/R4/Formulary",
    "https://pd.fhir.example.ca.gov/R4"
  ],
  "meta": {
    "data_as_of": "2026-03-01T00:00:00Z",
    "source": "CMS SMA Endpoint Directory",
    "source_url": "https://github.com/CMSgov/SMA-Endpoint-Directory",
    "ingested_at": "2026-03-01T12:00:00Z"
  }
}
```

--------------------------------

### Quick Start with Node.js

Source: https://fhirfly.io/docs/search-apis/mvx

Initialize the FHIRfly client and perform a basic search for vaccine manufacturers by name.

```javascript
import { Fhirfly } from "@fhirfly-io/terminology";

const client = new Fhirfly({ apiKey: "YOUR_API_KEY" });

// Search for Pfizer
const results = await client.mvx.search({
  q: "pfizer"
});

console.log(`Found ${results.total} manufacturers`);
for (const item of results.items) {
  console.log(`${item.code}: ${item.display}`);
}
```

--------------------------------

### Serve SHLs locally with fhirfly-shl serve

Source: https://fhirfly.io/docs/shl/cli-reference

Starts a local HTTP server for serving SHLs. Options include --port and --dir.

```bash
fhirfly-shl serve [options]
```

--------------------------------

### HCPCS response shape examples

Source: https://fhirfly.io/docs/value-apis/hcpcs

Shows three GET requests to /v1/hcpcs/A0425 with different shape values: compact for minimal data, standard for default detail, and full for data with provenance. Use the shape query parameter to control response detail.

```HTTP
# Minimal data
GET /v1/hcpcs/A0425?shape=compact

# Standard data (default)
GET /v1/hcpcs/A0425?shape=standard

# Full data with provenance
GET /v1/hcpcs/A0425?shape=full
```

--------------------------------

### NDC API shape query parameter examples

Source: https://fhirfly.io/docs/value-apis/ndc

Shows three GET requests to the NDC API using the `shape` query parameter to request compact, standard (default), and full response shapes. The `compact` shape is for minimal data, `standard` is the default core structured data, and `full` includes provenance for AI agents.

```http
GET /v1/ndc/60505008100?shape=compact
```

```http
GET /v1/ndc/60505008100?shape=standard
```

```http
GET /v1/ndc/60505008100?shape=full
```

--------------------------------

### Single Drug DDI Reference Lookup (GET /v1/ddi/reference/:identifier)

Source: https://fhirfly.io/docs/value-apis/ddi

Use this Node.js fetch call to retrieve FDA interaction text and drug metadata for a single drug by RxCUI, NDC, or FDA set_id. The response includes drug classes, ingredients, and DailyMed links. The example uses ramipril (RxCUI 261962) and requires an API key.

```javascript
const response = await fetch(
  "https://api.fhirfly.io/v1/ddi/reference/261962",
  {
    method: "GET",
    headers: {
    "x-api-key": "YOUR_API_KEY",
  }
  }
);

const data = await response.json();
console.log(data);
```

```json
{
  "data": {
    "input": "261962",
    "status": "ok",
    "drug": {
      "rxcui": "261962",
      "name": "ramipril 10 MG Oral Capsule",
      "generic_name": [
        "RAMIPRIL"
      ],
      "brand_names": [],
      "substance_name": [
        "Ramipril"
      ],
      "pharm_class_epc": [
        "Angiotensin Converting Enzyme Inhibitor [EPC]"
      ],
      "drug_classes": [
        {
          "class_id": "N0000000181",
          "class_name": "Angiotensin-converting Enzyme Inhibitors [MoA]",
          "class_type": "MoA",
          "source": "med-rt"
        },
        {
          "class_id": "N0000178477",
          "class_name": "Decreased Blood Pressure [PE]",
          "class_type": "PE",
          "source": "med-rt"
        }
      ],
      "ingredients": []
    },
    "label": {
      "spl_id": "0bfa08c7-2c74-4436-aa35-8cd37a21bd75",
      "set_id": "e8d9a115-71a7-4580-abbd-865e98b5d3f6",
      "dailymed_url": "https://dailymed.nlm.nih.gov/dailymed/drugInfo.cfm?setid=e8d9a115-71a7-4580-abbd-865e98b5d3f6",
      "sections": {
        "drug_interactions": [
          "7 DRUG INTERACTIONS..."
        ]
      }
    }
  },
  "meta": {
    "legal": {
      "license": "public_domain",
      "attribution_required": false,
      "disclaimer": "Drug interaction data is sourced from FDA-approved labeling and NLM RxNorm. This is reference information only...",
      "sources": [
        {
          "name": "FDA openFDA Drug Labels",
          "url": "https://open.fda.gov/apis/drug/label/"
        },
        {
          "name": "NLM RxNorm",
          "url": "https://www.nlm.nih.gov/research/umls/rxnorm/"
        }
      ]
    }
  }
}
```

--------------------------------

### Import SDK and initialize FHIRfly client

Source: https://fhirfly.io/docs/shl/ehr-integration

Import the SDK classes and initialize the optional FHIRfly enrichment client. Without an API key, you must provide display names manually.

```javascript
import { IPS, SHL } from "@fhirfly-io/shl";
import Fhirfly from "@fhirfly-io/terminology";

// FHIRfly API enriches your codes with display names, SNOMED mappings, etc.
// Optional but recommended — without it, you provide display names manually.
const fhirfly = new Fhirfly({ apiKey: process.env.FHIRFLY_API_KEY });

```

--------------------------------

### Node.js Quick Start

Source: https://fhirfly.io/docs/search-apis/icd10

Initializes the FHIRfly client and performs a basic search for diabetes diagnosis codes.

```javascript
import { Fhirfly } from "@fhirfly-io/terminology";

const client = new Fhirfly({ apiKey: "YOUR_API_KEY" });

// Search for diabetes diagnosis codes
const results = await client.icd10.search({
  q: "diabetes",
  code_system: "CM"
});

console.log(`Found ${results.total} codes`);
for (const item of results.items) {
  console.log(`${item.code}: ${item.display}`);
}
```

--------------------------------

### Using the FHIRfly SDK for SMA API

Source: https://fhirfly.io/docs/sma/api-reference

Demonstrates initializing the client, listing implemented states, retrieving details for a specific state, and fetching aggregate statistics.

```javascript
import { Fhirfly } from "@fhirfly-io/terminology";

const client = new Fhirfly({ apiKey: "your-api-key" });

// List all implemented states
const list = await client.sma.listStates({ implemented: true });
console.log(`${list.total} states have FHIR endpoints`);

for (const state of list.states) {
  console.log(`${state.abbreviation}: ${state.api_vendor ?? "No vendor"}`);
}

// Get full details for California
const ca = await client.sma.getState("CA");
console.log(`Claims endpoints: ${ca.patient_access.endpoints.claims.length}`);
console.log(`Auth: ${ca.patient_access.auth_protocol}`);

// Get aggregate statistics
const stats = await client.sma.stats();
console.log(`${stats.summary.implemented} / ${stats.summary.total_states} states implemented`);
```

--------------------------------

### CLI Commands for SHL

Source: https://fhirfly.io/docs/shl/quickstart

Use the CLI for quick testing, creating SHLs from files, serving local data, validating bundles, or decoding SHL URLs.

```bash
# Full demo with sample patient data
npx @fhirfly-io/shl demo

# Create from an existing FHIR Bundle file
npx @fhirfly-io/shl create my-bundle.json --passcode 1234

# Start a local server
npx @fhirfly-io/shl serve --dir ./shl-data --port 3456

# Validate a FHIR Bundle against IPS
npx @fhirfly-io/shl validate bundle.json

# Decode an SHL URL
npx @fhirfly-io/shl decode shlink:/eyJ...
```

--------------------------------

### Fastify plugin setup for PSHD

Source: https://fhirfly.io/docs/shl/pshd

Registers the SHL plugin with a /shl prefix. The onAccess callback logs the access mode and SHL ID. Requires a storage adapter.

```JavaScript
// Fastify
import { fastifyPlugin } from "@fhirfly-io/shl/fastify";

app.register(fastifyPlugin({
  storage,
  onAccess: (event) => {
    console.log(`[SHL] ${event.mode} access to ${event.shlId}`);
  },
}), { prefix: "/shl" });
```

--------------------------------

### Error Response Example

Source: https://fhirfly.io/docs/value-apis/overview

Example of an error response body. The 'error' field contains the error code, and 'error_description' provides a human-readable message.

```json
{
  "error": "not_found",
  "error_description": "NDC code not found: 0000-0000-00"
}

```

--------------------------------

### HCPCS Search Endpoint: GET /v1/hcpcs/search

Source: https://fhirfly.io/docs/search-apis/hcpcs

The endpoint for searching CMS HCPCS Level II procedure and supply codes. Use GET with the path /v1/hcpcs/search.

```http
GET /v1/hcpcs/search
```

--------------------------------

### fhirfly-shl serve

Source: https://fhirfly.io/docs/shl/cli-reference

Starts a local HTTP server for serving SHLs. Supports port and storage directory configuration.

```APIDOC
## fhirfly-shl serve

### Description
Starts a local HTTP server for serving SHLs.

### Usage
fhirfly-shl serve [options]

### Options
- `--port <number>` - Port to listen on (default: `3456`)
- `--dir <path>` - Storage directory (default: `./shl-data`)

```

--------------------------------

### SHL CLI commands

Source: https://fhirfly.io/docs/shl/overview

Command-line workflows for validating bundles, creating and decoding SHLs, starting a local server, and running a demo. Use npx @fhirfly-io/shl with the appropriate command and arguments.

```bash
npx @fhirfly-io/shl validate bundle.json   # Validate a FHIR Bundle
npx @fhirfly-io/shl create bundle.json     # Create an SHL from a bundle
npx @fhirfly-io/shl decode shlink:/eyJ...  # Decode an SHL URL
npx @fhirfly-io/shl serve                  # Start a local SHL server
npx @fhirfly-io/shl demo                   # Full round-trip demo
```

--------------------------------

### GET /v1/mvx/:code

Source: https://fhirfly.io/docs/value-apis/mvx

Look up a single MVX code to get manufacturer details. This endpoint returns the manufacturer's display name, code system, FHIR coding, and other metadata.

```APIDOC
## GET /v1/mvx/:code

### Description
Look up a single MVX vaccine manufacturer code.

### Method
GET

### Endpoint
`/v1/mvx/:code`

### Parameters
#### Path Parameters
- **code** (string) - Required - The MVX code to look up (e.g., PFR).

#### Query Parameters
- **shape** (string) - Optional - Response shape: `compact`, `standard`, or `full`. Default is `standard`.

### Request Example
```
GET /v1/mvx/PFR?shape=standard
```

### Response
#### Success Response (200)
- **data** (object) - Contains the MVX code details.
  - **code** (string) - The MVX code.
  - **code_system** (string) - The code system URI.
  - **display** (string) - The manufacturer display name.
  - **fhir_coding** (object) - FHIR coding representation.
  - **last_updated_by_cdc** (string) - Date last updated by CDC.
  - **manufacturer_name** (string) - The manufacturer name.
  - **notes** (string) - Additional notes.
  - **status** (string) - Status of the code (e.g., active).
- **meta** (object) - Metadata including legal attribution.

#### Response Example
```json
{
  "data": {
    "code": "PFR",
    "code_system": "http://hl7.org/fhir/sid/mvx",
    "display": "Pfizer, Inc",
    "fhir_coding": {
      "code": "PFR",
      "display": "Pfizer, Inc",
      "system": "http://hl7.org/fhir/sid/mvx"
    },
    "last_updated_by_cdc": "2020-10-30",
    "manufacturer_name": "Pfizer, Inc",
    "notes": "COVID-19 vaccine in co-development with BioNTech. Pfizer includes Wyeth-Lederle Vaccines and Pediatrics, Wyeth Laboratories, Lederle Laboratories, and Praxis Biologics",
    "status": "active"
  },
  "meta": {
    "legal": {
      "attribution_required": false,
      "citation": "CDC National Center for Immunization and Respiratory Diseases. Accessed 2026-01-14 via FHIRfly.",
      "license": "public_domain",
      "source_name": "CDC Immunization"
    }
  }
}
```
```

--------------------------------

### MS-DRG search response example

Source: https://fhirfly.io/docs/search-apis/msdrg

Example JSON response from the MS-DRG search endpoint. Shows facets for MDC and type, items with DRG codes and titles, pagination fields, and legal metadata.

```json
{
  "facets": {
    "mdc": {
      "05": 92,
      "01": 45,
      "08": 38,
      "04": 32
    },
    "type": {
      "MED": 345,
      "SURG": 401
    }
  },
  "has_more": true,
  "items": [
    {
      "drg_code": "280",
      "title": "ACUTE MYOCARDIAL INFARCTION, DISCHARGED ALIVE WITH MCC",
      "mdc": "05",
      "type": "MED"
    },
    {
      "drg_code": "231",
      "title": "CORONARY BYPASS WITHOUT CARDIAC CATH WITH MCC",
      "mdc": "05",
      "type": "SURG"
    }
  ],
  "limit": 2,
  "meta": {
    "legal": {
      "attribution_required": false,
      "citation": "CMS MS-DRG Definitions Manual. CMS.gov. Accessed 2026-03-15 via FHIRfly.",
      "license": "public_domain",
      "source_name": "CMS MS-DRG"
    }
  },
  "page": 1,
  "total": 127,
  "total_capped": false
}
```

--------------------------------

### Get SMA details for California - Node.js request

Source: https://fhirfly.io/docs/sma/api-reference

Fetches state details for California using the GET /v1/sma/states/CA endpoint. Requires an API key in the x-api-key header. The response is logged to the console.

```Node.js
const response = await fetch(
  "https://api.fhirfly.io/v1/sma/states/CA",
  {
    method: "GET",
    headers: {
    "x-api-key": "YOUR_API_KEY",
  }
  }
);

const data = await response.json();
console.log(data);
```

--------------------------------

### Quick Start Node.js Search

Source: https://fhirfly.io/docs/search-apis/opcs4

Initializes the FHIRfly client and performs a basic search for hip replacement procedures.

```javascript
import { Fhirfly } from "@fhirfly-io/terminology";

const client = new Fhirfly({ apiKey: "YOUR_API_KEY" });

// Search for hip replacement procedures
const results = await client.opcs4.search({
  q: "hip replacement"
});

console.log(`Found ${results.total} procedures`);
for (const item of results.items) {
  console.log(`${item.code}: ${item.display}`);
}
```

--------------------------------

### NDC code format: 11-digit vs 10-digit

Source: https://fhirfly.io/docs/shl/troubleshooting

NDC codes must be 11 digits with leading zeros. The wrong example uses a 10-digit code; the right example pads to 5-4-2 format.

```javascript
// Wrong: 10-digit NDC
bundle.addMedication({ byNDC: "0071015523" });

// Right: 11-digit NDC (pad segment to 5-4-2)
bundle.addMedication({ byNDC: "00071015523" });
```

--------------------------------

### Configure Claude Desktop with npx

Source: https://fhirfly.io/docs/mcp/claude-desktop

Add the FHIRfly server to your claude_desktop_config.json file using npx. Replace ffly_your_api_key_here with your actual API key.

```json
{
  "mcpServers": {
    "fhirfly": {
      "command": "npx",
      "args": ["-y", "@fhirfly-io/mcp-server"],
      "env": {
        "FHIRFLY_API_KEY": "ffly_your_api_key_here"
      }
    }
  }
}
```