# FHIRfly

> Healthcare reference data APIs for clinical coding, drug information, and provider lookup.

FHIRfly provides real-time access to NDC, NPI, RxNorm, LOINC, ICD-10, CVX, MVX, FDA Labels, SNOMED CT, UCUM, RxClass, HCPCS, MS-DRG, POS, J-Code/NDC Crosswalk, HCC, OPCS-4, dm+d, Connectivity, Claims Intelligence, and State Medicaid Agency data.

## Authentication

All API requests require an API key passed as `x-api-key` header or OAuth2 Bearer token.

Free tier: 10,000 requests/month, no credit card required.
Sign up: https://fhirfly.io/dashboard

## Quick Start (Node.js SDK)

npm install @fhirfly-io/terminology

import { Fhirfly } from "@fhirfly-io/terminology";
const client = new Fhirfly({ apiKey: "ffly_your_key" });
const med = await client.ndc.lookup("0069-0151-01");

## Quick Start (REST API)

curl -H "x-api-key: YOUR_KEY" https://api.fhirfly.io/v1/ndc/0069-0151-01

## Quick Start (MCP for Claude Desktop)

npx @fhirfly-io/mcp-server

## Resources

- OpenAPI spec: https://fhirfly.io/openapi.yaml
- SDK docs: https://fhirfly.io/docs/getting-started/quickstart
- API reference: https://fhirfly.io/docs/api-reference
- npm: https://www.npmjs.com/package/@fhirfly-io/terminology
- GitHub: https://github.com/FHIRfly-io

## Full API Specification (OpenAPI 3.1)

openapi: 3.1.0
info:
  title: FHIRfly API
  version: 1.0.0
  description: |
    Healthcare reference data APIs for clinical coding, drug information, and provider lookup.

    FHIRfly provides unified, developer-friendly access to:
    - **NDC** - National Drug Codes for medications
    - **NPI** - National Provider Identifier registry
    - **RxNorm** - Standardized drug nomenclature
    - **LOINC** - Laboratory and clinical observation codes
    - **ICD-10** - Diagnosis and procedure codes
    - **CVX** - Vaccine administered codes
    - **MVX** - Vaccine manufacturer codes
    - **FDA Labels** - Drug labeling information
    - **SNOMED CT** - Clinical terminology (IPS free set)
    - **UCUM** - Unified Code for Units of Measure (validation, conversion, search)
    - **RxClass** - Drug classification hierarchies (ATC, EPC, MOA, VA, and more)
    - **HCPCS** - HCPCS Level II procedure and supply codes (CMS)
    - **MS-DRG** - Medicare Severity Diagnosis Related Groups (CMS IPPS)
    - **POS** - Place of Service codes for claims submission
    - **J-Code/NDC Crosswalk** - Bidirectional HCPCS J-code to NDC mapping (CMS ASP)
    - **Connectivity** - FHIR endpoints and Direct addresses for providers
    - **SMA** - State Medicaid Agency FHIR endpoint directory
    - **Claims** - NCCI edits, MUE limits, Physician Fee Schedule, Coverage determinations

    ## Authentication

    All API requests require authentication via API key or Bearer token:
    ```
    x-api-key: YOUR_API_KEY
    ```
    or
    ```
    Authorization: Bearer YOUR_ACCESS_TOKEN
    ```

    ## Response Shapes

    All lookup endpoints support a `shape` query parameter:
    - `compact` - Minimal fields for quick lookups
    - `standard` - Balanced detail (default)
    - `full` - Complete data with all available fields

    ## Display Fields

    Add `include=display` to include pre-formatted display strings.

    ## Search APIs

    Most code systems support full-text search via `/v1/{system}/search` endpoints
    with filtering, pagination, and sorting.

  contact:
    name: FHIRfly Support
    email: support@fhirfly.io
    url: https://fhirfly.io
  license:
    name: Proprietary
    url: https://fhirfly.io/docs/legal/terms

servers:
  - url: https://api.fhirfly.io
    description: Production
  - url: https://devapi.fhirfly.io
    description: Development

security:
  - bearerAuth: []
  - apiKeyAuth: []

tags:
  - name: NDC
    description: National Drug Code lookups
  - name: NPI
    description: National Provider Identifier lookups
  - name: RxNorm
    description: RxNorm drug nomenclature lookups
  - name: LOINC
    description: LOINC observation code lookups
  - name: ICD-10
    description: ICD-10-CM/PCS code lookups
  - name: CVX
    description: Vaccine code lookups
  - name: MVX
    description: Vaccine manufacturer lookups
  - name: FDA Labels
    description: FDA drug label lookups
  - name: SNOMED CT
    description: SNOMED CT clinical terminology lookups (IPS free set)
  - name: UCUM
    description: Unified Code for Units of Measure lookups, validation, and conversion
  - name: RxClass
    description: Drug classification hierarchy lookups (ATC, EPC, MOA, VA, and more)
  - name: Connectivity
    description: FHIR endpoints and Direct addresses for providers
  - name: SMA
    description: State Medicaid Agency FHIR endpoint directory
  - name: Claims
    description: NCCI edits, MUE limits, fee schedule, and coverage determinations
  - name: HCPCS
    description: HCPCS Level II procedure and supply code lookups (CMS)
  - name: MS-DRG
    description: Medicare Severity Diagnosis Related Group lookups (CMS IPPS)
  - name: POS
    description: Place of Service code lookups for claims submission
  - name: J-Code
    description: Bidirectional HCPCS J-code to NDC crosswalk (CMS ASP)
  - name: Search
    description: Full-text search across code systems

paths:
  # ==========================================================================
  # NDC Endpoints
  # ==========================================================================
  /v1/ndc/{code}:
    get:
      tags: [NDC]
      summary: Look up NDC code
      description: |
        Retrieve drug information for a National Drug Code (NDC).
        Accepts 10-digit, 11-digit, or hyphenated formats.
      operationId: getNdc
      parameters:
        - $ref: '#/components/parameters/ndcCode'
        - $ref: '#/components/parameters/shape'
        - $ref: '#/components/parameters/include'
      responses:
        '200':
          description: NDC found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NdcResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v1/ndc/_batch:
    post:
      tags: [NDC]
      summary: Batch NDC lookup
      description: Look up multiple NDC codes in a single request (max 500).
      operationId: getNdcBatch
      parameters:
        - $ref: '#/components/parameters/shape'
        - $ref: '#/components/parameters/include'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchRequest'
      responses:
        '200':
          description: Batch results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v1/ndc/search:
    get:
      tags: [NDC, Search]
      summary: Search NDC drug products
      description: |
        Full-text search across drug products by name, ingredient, strength,
        route, dosage form, labeler, and more. Supports pagination and sorting.
      operationId: searchNdc
      parameters:
        - $ref: '#/components/parameters/searchQuery'
        - name: name
          in: query
          schema:
            type: string
          description: Filter by brand or generic name
        - name: labeler
          in: query
          schema:
            type: string
          description: Filter by labeler/manufacturer name
        - name: ingredient
          in: query
          schema:
            type: string
          description: Filter by active ingredient
        - name: route
          in: query
          schema:
            type: string
          description: Filter by route of administration
        - name: form
          in: query
          schema:
            type: string
          description: Filter by dosage form
        - $ref: '#/components/parameters/shape'
        - $ref: '#/components/parameters/searchLimit'
        - $ref: '#/components/parameters/searchPage'
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  # ==========================================================================
  # NPI Endpoints
  # ==========================================================================
  /v1/npi/{npi}:
    get:
      tags: [NPI]
      summary: Look up NPI
      description: |
        Retrieve provider information for a National Provider Identifier.
        NPI must be exactly 10 digits.
      operationId: getNpi
      parameters:
        - $ref: '#/components/parameters/npiNumber'
        - $ref: '#/components/parameters/shape'
        - $ref: '#/components/parameters/include'
      responses:
        '200':
          description: NPI found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NpiResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v1/npi/_batch:
    post:
      tags: [NPI]
      summary: Batch NPI lookup
      description: Look up multiple NPIs in a single request (max 500).
      operationId: getNpiBatch
      parameters:
        - $ref: '#/components/parameters/shape'
        - $ref: '#/components/parameters/include'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchRequest'
      responses:
        '200':
          description: Batch results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v1/npi/search:
    get:
      tags: [NPI, Search]
      summary: Search healthcare providers
      description: |
        Full-text search across the NPI registry by name, specialty, taxonomy,
        location, and more. Supports pagination and sorting.
      operationId: searchNpi
      parameters:
        - $ref: '#/components/parameters/searchQuery'
        - name: name
          in: query
          schema:
            type: string
          description: Filter by provider name
        - name: first_name
          in: query
          schema:
            type: string
          description: Filter by first name (individual providers)
        - name: last_name
          in: query
          schema:
            type: string
          description: Filter by last name (individual providers)
        - name: organization
          in: query
          schema:
            type: string
          description: Filter by organization name
        - name: taxonomy
          in: query
          schema:
            type: string
          description: Filter by taxonomy code
        - name: specialty
          in: query
          schema:
            type: string
          description: Filter by specialty description
        - name: state
          in: query
          schema:
            type: string
          description: Filter by state (2-letter abbreviation)
        - name: city
          in: query
          schema:
            type: string
          description: Filter by city
        - name: entity_type
          in: query
          schema:
            type: string
            enum: [individual, organization]
          description: Filter by entity type
        - $ref: '#/components/parameters/shape'
        - $ref: '#/components/parameters/searchLimit'
        - $ref: '#/components/parameters/searchPage'
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v1/npi/{npi}/connectivity:
    get:
      tags: [Connectivity]
      summary: Get connectivity options for a provider
      description: |
        Returns FHIR endpoints, Direct addresses, and other connectivity options
        for reaching a healthcare provider by their NPI. Includes endpoint URLs,
        FHIR versions, and connection methods.
      operationId: getNpiConnectivity
      parameters:
        - $ref: '#/components/parameters/npiNumber'
      responses:
        '200':
          description: Connectivity information found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectivityResponse'
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'

  # ==========================================================================
  # RxNorm Endpoints
  # ==========================================================================
  /v1/rxnorm/{rxcui}:
    get:
      tags: [RxNorm]
      summary: Look up RxCUI
      description: |
        Retrieve drug information for an RxNorm Concept Unique Identifier (RxCUI).
      operationId: getRxnorm
      parameters:
        - $ref: '#/components/parameters/rxcui'
        - $ref: '#/components/parameters/shape'
        - $ref: '#/components/parameters/include'
      responses:
        '200':
          description: RxCUI found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RxNormResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v1/rxnorm/_batch:
    post:
      tags: [RxNorm]
      summary: Batch RxNorm lookup
      description: Look up multiple RxCUIs in a single request (max 500).
      operationId: getRxnormBatch
      parameters:
        - $ref: '#/components/parameters/shape'
        - $ref: '#/components/parameters/include'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchRequest'
      responses:
        '200':
          description: Batch results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v1/rxnorm/search:
    get:
      tags: [RxNorm, Search]
      summary: Search RxNorm drug terminology
      description: |
        Full-text search across RxNorm concepts by name, ingredient, brand,
        and term type. Supports pagination and sorting.
      operationId: searchRxnorm
      parameters:
        - $ref: '#/components/parameters/searchQuery'
        - name: name
          in: query
          schema:
            type: string
          description: Filter by drug name
        - name: ingredient
          in: query
          schema:
            type: string
          description: Filter by ingredient
        - name: brand
          in: query
          schema:
            type: string
          description: Filter by brand name
        - name: tty
          in: query
          schema:
            type: string
          description: Filter by term type (SCD, SBD, etc.)
        - $ref: '#/components/parameters/shape'
        - $ref: '#/components/parameters/searchLimit'
        - $ref: '#/components/parameters/searchPage'
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  # ==========================================================================
  # LOINC Endpoints
  # ==========================================================================
  /v1/loinc/{code}:
    get:
      tags: [LOINC]
      summary: Look up LOINC code
      description: |
        Retrieve observation information for a LOINC code.
        Format: NNNNN-N (e.g., 2345-7)
      operationId: getLoinc
      parameters:
        - $ref: '#/components/parameters/loincCode'
        - $ref: '#/components/parameters/shape'
        - $ref: '#/components/parameters/include'
      responses:
        '200':
          description: LOINC code found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoincResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v1/loinc/_batch:
    post:
      tags: [LOINC]
      summary: Batch LOINC lookup
      description: Look up multiple LOINC codes in a single request (max 500).
      operationId: getLoincBatch
      parameters:
        - $ref: '#/components/parameters/shape'
        - $ref: '#/components/parameters/include'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchRequest'
      responses:
        '200':
          description: Batch results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v1/loinc/search:
    get:
      tags: [LOINC, Search]
      summary: Search LOINC codes
      description: |
        Full-text search across LOINC codes by component, class, system,
        and more. Supports pagination and sorting.
      operationId: searchLoinc
      parameters:
        - $ref: '#/components/parameters/searchQuery'
        - name: component
          in: query
          schema:
            type: string
          description: Filter by component
        - name: class
          in: query
          schema:
            type: string
          description: Filter by class
        - name: system
          in: query
          schema:
            type: string
          description: Filter by system
        - $ref: '#/components/parameters/shape'
        - $ref: '#/components/parameters/searchLimit'
        - $ref: '#/components/parameters/searchPage'
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  # ==========================================================================
  # ICD-10 Endpoints
  # ==========================================================================
  /v1/icd10/{code}:
    get:
      tags: [ICD-10]
      summary: Look up ICD-10 code
      description: |
        Retrieve diagnosis or procedure information for an ICD-10-CM or ICD-10-PCS code.
      operationId: getIcd10
      parameters:
        - $ref: '#/components/parameters/icd10Code'
        - $ref: '#/components/parameters/shape'
        - $ref: '#/components/parameters/include'
      responses:
        '200':
          description: ICD-10 code found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Icd10Response'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v1/icd10/_batch:
    post:
      tags: [ICD-10]
      summary: Batch ICD-10 lookup
      description: Look up multiple ICD-10 codes in a single request (max 500).
      operationId: getIcd10Batch
      parameters:
        - $ref: '#/components/parameters/shape'
        - $ref: '#/components/parameters/include'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchRequest'
      responses:
        '200':
          description: Batch results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v1/icd10/search:
    get:
      tags: [ICD-10, Search]
      summary: Search ICD-10 codes
      description: |
        Full-text search across ICD-10-CM and ICD-10-PCS codes by description.
        Supports pagination and sorting.
      operationId: searchIcd10
      parameters:
        - $ref: '#/components/parameters/searchQuery'
        - $ref: '#/components/parameters/shape'
        - $ref: '#/components/parameters/searchLimit'
        - $ref: '#/components/parameters/searchPage'
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  # ==========================================================================
  # CVX Endpoints
  # ==========================================================================
  /v1/cvx/{code}:
    get:
      tags: [CVX]
      summary: Look up CVX code
      description: |
        Retrieve vaccine information for a CVX (vaccine administered) code.
      operationId: getCvx
      parameters:
        - $ref: '#/components/parameters/cvxCode'
        - $ref: '#/components/parameters/shape'
        - $ref: '#/components/parameters/include'
      responses:
        '200':
          description: CVX code found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CvxResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v1/cvx/_batch:
    post:
      tags: [CVX]
      summary: Batch CVX lookup
      description: Look up multiple CVX codes in a single request (max 500).
      operationId: getCvxBatch
      parameters:
        - $ref: '#/components/parameters/shape'
        - $ref: '#/components/parameters/include'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchRequest'
      responses:
        '200':
          description: Batch results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v1/cvx/search:
    get:
      tags: [CVX, Search]
      summary: Search vaccine codes
      description: Search CVX vaccine codes including COVID-19 vaccines.
      operationId: searchCvx
      parameters:
        - $ref: '#/components/parameters/searchQuery'
        - $ref: '#/components/parameters/shape'
        - $ref: '#/components/parameters/searchLimit'
        - $ref: '#/components/parameters/searchPage'
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  # ==========================================================================
  # MVX Endpoints
  # ==========================================================================
  /v1/mvx/{code}:
    get:
      tags: [MVX]
      summary: Look up MVX code
      description: |
        Retrieve manufacturer information for an MVX (vaccine manufacturer) code.
      operationId: getMvx
      parameters:
        - $ref: '#/components/parameters/mvxCode'
        - $ref: '#/components/parameters/shape'
        - $ref: '#/components/parameters/include'
      responses:
        '200':
          description: MVX code found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MvxResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v1/mvx/_batch:
    post:
      tags: [MVX]
      summary: Batch MVX lookup
      description: Look up multiple MVX codes in a single request (max 500).
      operationId: getMvxBatch
      parameters:
        - $ref: '#/components/parameters/shape'
        - $ref: '#/components/parameters/include'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchRequest'
      responses:
        '200':
          description: Batch results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v1/mvx/search:
    get:
      tags: [MVX, Search]
      summary: Search vaccine manufacturer codes
      description: Search MVX vaccine manufacturer codes.
      operationId: searchMvx
      parameters:
        - $ref: '#/components/parameters/searchQuery'
        - $ref: '#/components/parameters/shape'
        - $ref: '#/components/parameters/searchLimit'
        - $ref: '#/components/parameters/searchPage'
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  # ==========================================================================
  # FDA Label Endpoints
  # ==========================================================================
  /v1/fda-label/{id}:
    get:
      tags: [FDA Labels]
      summary: Look up FDA drug label
      description: |
        Retrieve FDA drug labeling information by application number or set ID.
      operationId: getFdaLabel
      parameters:
        - $ref: '#/components/parameters/fdaLabelId'
        - $ref: '#/components/parameters/shape'
        - $ref: '#/components/parameters/include'
      responses:
        '200':
          description: FDA label found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FdaLabelResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v1/fda-label/search:
    get:
      tags: [FDA Labels, Search]
      summary: Search FDA drug labels
      description: Search FDA drug labels by name, manufacturer, route, and more.
      operationId: searchFdaLabels
      parameters:
        - $ref: '#/components/parameters/searchQuery'
        - name: name
          in: query
          schema:
            type: string
          description: Filter by brand or generic name
        - name: manufacturer
          in: query
          schema:
            type: string
          description: Filter by manufacturer name
        - name: route
          in: query
          schema:
            type: string
          description: Filter by route of administration
        - $ref: '#/components/parameters/shape'
        - $ref: '#/components/parameters/searchLimit'
        - $ref: '#/components/parameters/searchPage'
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  # ==========================================================================
  # SNOMED CT Endpoints
  # ==========================================================================
  /v1/snomed/{concept_id}:
    get:
      tags: [SNOMED CT]
      summary: Look up SNOMED CT concept
      description: |
        Retrieve clinical concept information for a SNOMED CT concept ID
        from the IPS (International Patient Summary) free set.
      operationId: getSnomedConcept
      parameters:
        - name: concept_id
          in: path
          required: true
          schema:
            type: string
          description: SNOMED CT concept ID
          example: "73211009"
        - $ref: '#/components/parameters/shape'
        - $ref: '#/components/parameters/include'
      responses:
        '200':
          description: Concept found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SnomedResponse'
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v1/snomed/_batch:
    post:
      tags: [SNOMED CT]
      summary: Batch SNOMED CT lookup
      description: Look up multiple SNOMED CT concept IDs in a single request (max 100).
      operationId: getSnomedBatch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchRequest'
      responses:
        '200':
          description: Batch results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v1/snomed/{concept_id}/mappings:
    get:
      tags: [SNOMED CT]
      summary: Get mappings for a SNOMED CT concept
      description: |
        Returns cross-mappings from a SNOMED CT concept to other code systems
        (e.g., ICD-10, LOINC).
      operationId: getSnomedMappings
      parameters:
        - name: concept_id
          in: path
          required: true
          schema:
            type: string
          description: SNOMED CT concept ID
          example: "73211009"
      responses:
        '200':
          description: Mappings found
          content:
            application/json:
              schema:
                type: object
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v1/snomed/categories:
    get:
      tags: [SNOMED CT]
      summary: List SNOMED CT IPS categories
      description: Returns the available IPS categories for SNOMED CT concepts.
      operationId: getSnomedCategories
      responses:
        '200':
          description: Categories list
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v1/snomed/search:
    get:
      tags: [SNOMED CT, Search]
      summary: Search SNOMED CT concepts
      description: |
        Full-text search across SNOMED CT IPS concepts by text, category,
        and semantic tag.
      operationId: searchSnomed
      parameters:
        - $ref: '#/components/parameters/searchQuery'
        - name: ips_category
          in: query
          schema:
            type: string
          description: Filter by IPS category
        - name: semantic_tag
          in: query
          schema:
            type: string
          description: Filter by semantic tag
        - $ref: '#/components/parameters/searchLimit'
        - $ref: '#/components/parameters/searchPage'
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  # ==========================================================================
  # UCUM Endpoints
  # ==========================================================================
  /v1/ucum/{code}:
    get:
      tags: [UCUM]
      summary: Look up UCUM unit
      description: |
        Retrieve unit information for a UCUM (Unified Code for Units of Measure) code.
        Returns unit name, symbol, property, and classification.
      operationId: getUcum
      parameters:
        - $ref: '#/components/parameters/ucumCode'
        - $ref: '#/components/parameters/shape'
        - $ref: '#/components/parameters/include'
      responses:
        '200':
          description: UCUM unit found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UcumResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v1/ucum/_batch:
    post:
      tags: [UCUM]
      summary: Batch UCUM lookup
      description: Look up multiple UCUM codes in a single request (max 500).
      operationId: getUcumBatch
      parameters:
        - $ref: '#/components/parameters/shape'
        - $ref: '#/components/parameters/include'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchRequest'
      responses:
        '200':
          description: Batch results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v1/ucum/validate/{expression}:
    get:
      tags: [UCUM]
      summary: Validate a UCUM expression
      description: |
        Validate whether a string is a valid UCUM unit expression.
        Returns validity status and parsed unit details if valid.
      operationId: validateUcum
      parameters:
        - name: expression
          in: path
          required: true
          schema:
            type: string
          description: UCUM unit expression to validate
          example: "mg/dL"
      responses:
        '200':
          description: Validation result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UcumValidateResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v1/ucum/convert:
    get:
      tags: [UCUM]
      summary: Convert between UCUM units
      description: |
        Convert a value from one UCUM unit to another. Both units must be
        commensurable (same dimension). Returns the converted value and units.
      operationId: convertUcum
      parameters:
        - name: value
          in: query
          required: true
          schema:
            type: number
          description: Numeric value to convert
          example: 100
        - name: from
          in: query
          required: true
          schema:
            type: string
          description: Source UCUM unit
          example: "mg"
        - name: to
          in: query
          required: true
          schema:
            type: string
          description: Target UCUM unit
          example: "g"
      responses:
        '200':
          description: Conversion result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UcumConvertResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v1/ucum/search:
    get:
      tags: [UCUM, Search]
      summary: Search UCUM units
      description: |
        Full-text search across UCUM units by name, symbol, property, and class.
        Supports pagination and sorting.
      operationId: searchUcum
      parameters:
        - $ref: '#/components/parameters/searchQuery'
        - name: property
          in: query
          schema:
            type: string
          description: Filter by property (e.g., "length", "mass", "volume")
        - name: class
          in: query
          schema:
            type: string
          description: Filter by unit class (e.g., "si", "customary", "clinical")
        - $ref: '#/components/parameters/shape'
        - $ref: '#/components/parameters/searchLimit'
        - $ref: '#/components/parameters/searchPage'
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  # ==========================================================================
  # RxClass Endpoints
  # ==========================================================================
  /v1/rxclass/{classId}:
    get:
      tags: [RxClass]
      summary: Look up RxClass drug class
      description: |
        Retrieve drug classification information for an RxClass class ID.
        Covers ATC, EPC, MOA, PE, VA, DISEASE, CHEM, SCHEDULE, and other class types.
      operationId: getRxclass
      parameters:
        - $ref: '#/components/parameters/rxclassId'
        - $ref: '#/components/parameters/shape'
        - $ref: '#/components/parameters/include'
      responses:
        '200':
          description: RxClass found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RxClassResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v1/rxclass/_batch:
    post:
      tags: [RxClass]
      summary: Batch RxClass lookup
      description: Look up multiple RxClass class IDs in a single request (max 500).
      operationId: getRxclassBatch
      parameters:
        - $ref: '#/components/parameters/shape'
        - $ref: '#/components/parameters/include'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchRequest'
      responses:
        '200':
          description: Batch results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v1/rxclass/{classId}/members:
    get:
      tags: [RxClass]
      summary: Get members of a drug class
      description: |
        Returns the drugs (RxNorm concepts) that belong to a given drug class.
        Includes RxCUI, drug name, and relationship type.
      operationId: getRxclassMembers
      parameters:
        - $ref: '#/components/parameters/rxclassId'
        - $ref: '#/components/parameters/searchLimit'
        - $ref: '#/components/parameters/searchPage'
      responses:
        '200':
          description: Class members found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RxClassMembersResponse'
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v1/rxclass/search:
    get:
      tags: [RxClass, Search]
      summary: Search drug classes
      description: |
        Full-text search across RxClass drug classifications by name, class type,
        and source. Supports pagination and sorting.
      operationId: searchRxclass
      parameters:
        - $ref: '#/components/parameters/searchQuery'
        - name: class_type
          in: query
          schema:
            type: string
          description: Filter by class type (ATC, EPC, MOA, PE, VA, DISEASE, CHEM, SCHEDULE)
        - name: source
          in: query
          schema:
            type: string
          description: Filter by source vocabulary
        - $ref: '#/components/parameters/shape'
        - $ref: '#/components/parameters/searchLimit'
        - $ref: '#/components/parameters/searchPage'
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  # ==========================================================================
  # SMA Endpoints
  # ==========================================================================
  /v1/sma/states:
    get:
      tags: [SMA]
      summary: List all states with SMA endpoint status
      description: |
        Returns all U.S. states and territories with their State Medicaid Agency
        FHIR endpoint implementation status. Supports filtering by implementation
        status, vendor, and FHIR version.
      operationId: listSmaStates
      parameters:
        - name: implemented
          in: query
          schema:
            type: boolean
          description: Filter by implementation status
        - name: vendor
          in: query
          schema:
            type: string
          description: Filter by API vendor (e.g., "Epic")
        - name: fhir_version
          in: query
          schema:
            type: string
          description: Filter by FHIR version (e.g., "4.0.1")
      responses:
        '200':
          description: List of states with SMA endpoint status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SmaStatesListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v1/sma/states/{state}:
    get:
      tags: [SMA]
      summary: Get SMA details for a specific state
      description: |
        Returns full SMA endpoint details for a specific state including patient
        access endpoints, provider directory endpoints, and contacts. Accepts
        state abbreviation (CA), underscore ID (california), or display name.
      operationId: getSmaState
      parameters:
        - name: state
          in: path
          required: true
          schema:
            type: string
          description: State abbreviation (CA), ID (california), or name
          example: "CA"
      responses:
        '200':
          description: State SMA endpoint details
          content:
            application/json:
              schema:
                type: object
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v1/sma/stats:
    get:
      tags: [SMA]
      summary: Get aggregate SMA statistics
      description: |
        Returns aggregate statistics across all SMA endpoint implementations
        including counts by vendor, FHIR version, and implementation status.
      operationId: getSmaStats
      responses:
        '200':
          description: Aggregate SMA statistics
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'

  # ==========================================================================
  # Claims Intelligence Endpoints
  # ==========================================================================
  /v1/ncci/validate:
    get:
      tags: [Claims]
      summary: Validate NCCI code pair
      description: |
        Validate whether two CPT/HCPCS codes can be billed together according to
        CMS National Correct Coding Initiative edits.
      operationId: validateNcci
      parameters:
        - name: code1
          in: query
          required: true
          schema:
            type: string
          description: First CPT/HCPCS code
          example: "99213"
        - name: code2
          in: query
          required: true
          schema:
            type: string
          description: Second CPT/HCPCS code
          example: "99214"
        - name: claim_type
          in: query
          schema:
            type: string
          description: Claim type filter
      responses:
        '200':
          description: Validation result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NcciValidationResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v1/mue/{hcpcs}:
    get:
      tags: [Claims]
      summary: Look up MUE limit
      description: |
        Look up the Medically Unlikely Edit (MUE) limit for an HCPCS code.
        Returns the maximum units of service unlikely to be billed correctly
        by a single provider for a single patient on a single date.
      operationId: getMue
      parameters:
        - name: hcpcs
          in: path
          required: true
          schema:
            type: string
          description: HCPCS code
          example: "99213"
        - name: service_type
          in: query
          schema:
            type: string
          description: Service type filter
      responses:
        '200':
          description: MUE data found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MueResponse'
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v1/mue/_batch:
    post:
      tags: [Claims]
      summary: Batch MUE lookup
      description: Look up MUE limits for multiple HCPCS codes (max 100).
      operationId: getMueBatch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchRequest'
      responses:
        '200':
          description: Batch results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v1/pfs/{hcpcs}:
    get:
      tags: [Claims]
      summary: Look up Physician Fee Schedule
      description: |
        Look up Medicare Physician Fee Schedule and RVU (Relative Value Unit) data
        for an HCPCS code.
      operationId: getPfs
      parameters:
        - name: hcpcs
          in: path
          required: true
          schema:
            type: string
          description: HCPCS code
          example: "99213"
      responses:
        '200':
          description: PFS data found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PfsResponse'
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v1/pfs/_batch:
    post:
      tags: [Claims]
      summary: Batch PFS lookup
      description: Look up PFS/RVU data for multiple HCPCS codes (max 100).
      operationId: getPfsBatch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchRequest'
      responses:
        '200':
          description: Batch results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v1/coverage/check:
    get:
      tags: [Claims]
      summary: Check coverage determination
      description: |
        Check LCD (Local Coverage Determination) coverage for an HCPCS code.
        Returns applicable coverage policies and determination status.
      operationId: checkCoverage
      parameters:
        - name: hcpcs
          in: query
          required: true
          schema:
            type: string
          description: HCPCS code to check coverage for
          example: "99213"
        - name: active
          in: query
          schema:
            type: boolean
          description: Filter to active determinations only
      responses:
        '200':
          description: Coverage determination results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CoverageCheckResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  # ==========================================================================
  # HCPCS Level II Endpoints
  # ==========================================================================
  /v1/hcpcs/{code}:
    get:
      tags: [HCPCS]
      summary: Look up HCPCS Level II code
      description: |
        Retrieve procedure or supply information for an HCPCS Level II code.
        Format: one letter (A-V) followed by four digits (e.g., A0425, E0100).
      operationId: getHcpcs
      parameters:
        - $ref: '#/components/parameters/hcpcsCode'
        - $ref: '#/components/parameters/shape'
        - $ref: '#/components/parameters/include'
      responses:
        '200':
          description: HCPCS code found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HcpcsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v1/hcpcs/_batch:
    post:
      tags: [HCPCS]
      summary: Batch HCPCS lookup
      description: Look up multiple HCPCS Level II codes in a single request (max 100).
      operationId: getHcpcsBatch
      parameters:
        - $ref: '#/components/parameters/shape'
        - $ref: '#/components/parameters/include'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchRequest'
      responses:
        '200':
          description: Batch results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v1/hcpcs/modifier/{code}:
    get:
      tags: [HCPCS]
      summary: Look up HCPCS modifier
      description: |
        Retrieve modifier information for a 2-character HCPCS modifier code (e.g., 25, TC, 59).
      operationId: getHcpcsModifier
      parameters:
        - name: code
          in: path
          required: true
          schema:
            type: string
            pattern: '^[A-Z0-9]{2}$'
          description: 2-character HCPCS modifier code
          example: "25"
        - $ref: '#/components/parameters/shape'
        - $ref: '#/components/parameters/include'
      responses:
        '200':
          description: Modifier found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HcpcsModifierResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v1/hcpcs/search:
    get:
      tags: [HCPCS, Search]
      summary: Search HCPCS Level II codes
      description: |
        Full-text search across HCPCS Level II codes by description, code, and category.
        Supports pagination and sorting.
      operationId: searchHcpcs
      parameters:
        - $ref: '#/components/parameters/searchQuery'
        - name: category
          in: query
          schema:
            type: string
          description: Filter by category letter (A-V)
        - name: status_code
          in: query
          schema:
            type: string
            enum: [A, T]
          description: Filter by status (A=active, T=terminated)
        - $ref: '#/components/parameters/shape'
        - $ref: '#/components/parameters/searchLimit'
        - $ref: '#/components/parameters/searchPage'
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  # ==========================================================================
  # MS-DRG Endpoints
  # ==========================================================================
  /v1/msdrg/{code}:
    get:
      tags: [MS-DRG]
      summary: Look up MS-DRG code
      description: |
        Retrieve diagnosis related group information for an MS-DRG code.
        Accepts 1-3 digit codes (e.g., 470, 1). Auto-pads to 3 digits.
      operationId: getMsdrg
      parameters:
        - $ref: '#/components/parameters/msdrgCode'
        - $ref: '#/components/parameters/shape'
        - $ref: '#/components/parameters/include'
      responses:
        '200':
          description: MS-DRG code found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MsdrgResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v1/msdrg/_batch:
    post:
      tags: [MS-DRG]
      summary: Batch MS-DRG lookup
      description: Look up multiple MS-DRG codes in a single request (max 100).
      operationId: getMsdrgBatch
      parameters:
        - $ref: '#/components/parameters/shape'
        - $ref: '#/components/parameters/include'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchRequest'
      responses:
        '200':
          description: Batch results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v1/msdrg/search:
    get:
      tags: [MS-DRG, Search]
      summary: Search MS-DRG codes
      description: |
        Full-text search across MS-DRG codes by title, MDC, and type.
        Supports pagination and sorting.
      operationId: searchMsdrg
      parameters:
        - $ref: '#/components/parameters/searchQuery'
        - name: mdc
          in: query
          schema:
            type: string
          description: Filter by Major Diagnostic Category
        - name: type
          in: query
          schema:
            type: string
            enum: [SURG, MED]
          description: Filter by type (surgical or medical)
        - $ref: '#/components/parameters/shape'
        - $ref: '#/components/parameters/searchLimit'
        - $ref: '#/components/parameters/searchPage'
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  # ==========================================================================
  # POS (Place of Service) Endpoints
  # ==========================================================================
  /v1/pos/{code}:
    get:
      tags: [POS]
      summary: Look up Place of Service code
      description: |
        Retrieve Place of Service information for a POS code.
        Accepts 1-2 digit codes (e.g., 11, 1). Auto-pads to 2 digits.
      operationId: getPos
      parameters:
        - $ref: '#/components/parameters/posCode'
        - $ref: '#/components/parameters/shape'
        - $ref: '#/components/parameters/include'
      responses:
        '200':
          description: POS code found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PosResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v1/pos/_batch:
    post:
      tags: [POS]
      summary: Batch POS lookup
      description: Look up multiple POS codes in a single request (max 100).
      operationId: getPosBatch
      parameters:
        - $ref: '#/components/parameters/shape'
        - $ref: '#/components/parameters/include'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchRequest'
      responses:
        '200':
          description: Batch results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v1/pos/list:
    get:
      tags: [POS]
      summary: List all Place of Service codes
      description: Returns all ~52 Place of Service codes. No pagination needed.
      operationId: listPos
      parameters:
        - $ref: '#/components/parameters/shape'
      responses:
        '200':
          description: All POS codes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PosListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'

  # ==========================================================================
  # J-Code/NDC Crosswalk Endpoints
  # ==========================================================================
  /v1/jcode/by-hcpcs/{code}:
    get:
      tags: [J-Code]
      summary: Look up NDCs for a J-code
      description: |
        Given an HCPCS J-code (or Q/A/C code), returns all NDC codes mapped to it
        with drug name, labeler, dosage, and billing units.
      operationId: getJcodeByHcpcs
      parameters:
        - name: code
          in: path
          required: true
          schema:
            type: string
          description: HCPCS code (J, Q, A, or C codes, or 5-digit numeric)
          example: "J9035"
      responses:
        '200':
          description: J-code crosswalk results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JcodeByHcpcsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v1/jcode/by-ndc/{ndc}:
    get:
      tags: [J-Code]
      summary: Look up HCPCS codes for an NDC
      description: |
        Given an NDC code, returns all HCPCS codes (J-codes, Q-codes, etc.)
        mapped to it. Reverse lookup from NDC to billing codes.
      operationId: getJcodeByNdc
      parameters:
        - name: ndc
          in: path
          required: true
          schema:
            type: string
          description: NDC code (11 digits or hyphenated)
          example: "00004110002"
      responses:
        '200':
          description: NDC to J-code crosswalk results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JcodeByNdcResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: OAuth2 access token from FHIRfly
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key from FHIRfly dashboard

  parameters:
    shape:
      name: shape
      in: query
      description: Response detail level
      required: false
      schema:
        type: string
        enum: [compact, standard, full]
        default: standard

    include:
      name: include
      in: query
      description: Additional fields to include (e.g., "display")
      required: false
      schema:
        type: string
        enum: [display]

    searchQuery:
      name: q
      in: query
      description: Full-text search query
      required: false
      schema:
        type: string
      example: "aspirin"

    searchLimit:
      name: limit
      in: query
      description: Maximum number of results to return (default 25, max 100)
      required: false
      schema:
        type: integer
        default: 25
        maximum: 100

    searchPage:
      name: page
      in: query
      description: Page number for pagination (1-based)
      required: false
      schema:
        type: integer
        default: 1

    ndcCode:
      name: code
      in: path
      description: NDC code (10-digit, 11-digit, or hyphenated)
      required: true
      schema:
        type: string
      example: "0069-0770-01"

    npiNumber:
      name: npi
      in: path
      description: 10-digit National Provider Identifier
      required: true
      schema:
        type: string
        pattern: '^\d{10}$'
      example: "1234567890"

    rxcui:
      name: rxcui
      in: path
      description: RxNorm Concept Unique Identifier
      required: true
      schema:
        type: string
      example: "161"

    loincCode:
      name: code
      in: path
      description: LOINC code (format NNNNN-N)
      required: true
      schema:
        type: string
      example: "2345-7"

    icd10Code:
      name: code
      in: path
      description: ICD-10-CM or ICD-10-PCS code
      required: true
      schema:
        type: string
      example: "J06.9"

    cvxCode:
      name: code
      in: path
      description: CVX vaccine code
      required: true
      schema:
        type: string
      example: "208"

    mvxCode:
      name: code
      in: path
      description: MVX manufacturer code
      required: true
      schema:
        type: string
      example: "PFR"

    fdaLabelId:
      name: id
      in: path
      description: FDA application number or set ID
      required: true
      schema:
        type: string
      example: "NDA021457"

    ucumCode:
      name: code
      in: path
      description: UCUM unit code
      required: true
      schema:
        type: string
      example: "mg"

    rxclassId:
      name: classId
      in: path
      description: RxClass class identifier
      required: true
      schema:
        type: string
      example: "N0000175503"

    hcpcsCode:
      name: code
      in: path
      description: HCPCS Level II code (letter A-V + 4 digits)
      required: true
      schema:
        type: string
        pattern: '^[A-V]\d{4}$'
      example: "A0425"

    msdrgCode:
      name: code
      in: path
      description: MS-DRG code (1-3 digits, auto-padded)
      required: true
      schema:
        type: string
      example: "470"

    posCode:
      name: code
      in: path
      description: Place of Service code (1-2 digits, auto-padded)
      required: true
      schema:
        type: string
      example: "11"

  schemas:
    BatchRequest:
      type: object
      required:
        - codes
      properties:
        codes:
          type: array
          items:
            type: string
          maxItems: 500
          description: Array of codes to look up
          example: ["0069-0770-01", "0002-4462-02"]

    BatchResponse:
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/ResponseMeta'
        results:
          type: array
          items:
            type: object
        errors:
          type: array
          items:
            $ref: '#/components/schemas/BatchError'

    BatchError:
      type: object
      properties:
        code:
          type: string
        error:
          type: string
        message:
          type: string

    ResponseMeta:
      type: object
      properties:
        shape:
          type: string
          enum: [compact, standard, full]
        include:
          type: array
          items:
            type: string
        timing_ms:
          type: number

    SearchResponse:
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/ResponseMeta'
        results:
          type: array
          items:
            type: object
        total:
          type: integer
          description: Total number of matching results
        page:
          type: integer
        limit:
          type: integer

    NdcResponse:
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/ResponseMeta'
        ndc:
          type: string
        product_ndc:
          type: string
        package_ndc:
          type: string
        brand_name:
          type: string
        generic_name:
          type: string
        labeler_name:
          type: string
        dosage_form:
          type: string
        route:
          type: array
          items:
            type: string
        marketing_status:
          type: string

    NpiResponse:
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/ResponseMeta'
        npi:
          type: string
        entity_type:
          type: string
          enum: [individual, organization]
        name:
          type: object
        address:
          type: object
        taxonomies:
          type: array
          items:
            type: object
        status:
          type: string

    ConnectivityResponse:
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/ResponseMeta'
        npi:
          type: string
        endpoints:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                description: Endpoint type (FHIR, Direct, etc.)
              url:
                type: string
              fhir_version:
                type: string

    RxNormResponse:
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/ResponseMeta'
        rxcui:
          type: string
        name:
          type: string
        tty:
          type: string
          description: Term type
        suppress:
          type: string

    LoincResponse:
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/ResponseMeta'
        loinc_num:
          type: string
        long_common_name:
          type: string
        component:
          type: string
        property:
          type: string
        time_aspect:
          type: string
        system:
          type: string
        scale_type:
          type: string
        method_type:
          type: string
        class:
          type: string
        status:
          type: string

    Icd10Response:
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/ResponseMeta'
        code:
          type: string
        description:
          type: string
        type:
          type: string
          enum: [cm, pcs]
        is_header:
          type: boolean
        parent_code:
          type: string

    CvxResponse:
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/ResponseMeta'
        cvx_code:
          type: string
        short_description:
          type: string
        full_vaccine_name:
          type: string
        notes:
          type: string
        status:
          type: string
        last_updated:
          type: string

    MvxResponse:
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/ResponseMeta'
        mvx_code:
          type: string
        manufacturer_name:
          type: string
        notes:
          type: string
        status:
          type: string
        last_updated:
          type: string

    FdaLabelResponse:
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/ResponseMeta'
        set_id:
          type: string
        application_number:
          type: string
        brand_name:
          type: string
        generic_name:
          type: string
        manufacturer:
          type: string
        effective_date:
          type: string
        sections:
          type: object
          additionalProperties:
            type: string

    SnomedResponse:
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/ResponseMeta'
        concept_id:
          type: string
        term:
          type: string
        semantic_tag:
          type: string
        ips_category:
          type: string
        active:
          type: boolean

    UcumResponse:
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/ResponseMeta'
        code:
          type: string
        name:
          type: string
        symbol:
          type: string
        property:
          type: string
          description: Physical property (e.g., length, mass, volume)
        class:
          type: string
          description: Unit class (e.g., si, customary, clinical)
        is_metric:
          type: boolean
        is_arbitrary:
          type: boolean

    UcumValidateResponse:
      type: object
      properties:
        expression:
          type: string
        is_valid:
          type: boolean
        unit_name:
          type: string
          description: Resolved unit name if valid
        message:
          type: string
          description: Validation error message if invalid

    UcumConvertResponse:
      type: object
      properties:
        from_value:
          type: number
        from_unit:
          type: string
        to_value:
          type: number
        to_unit:
          type: string
        factor:
          type: number
          description: Conversion factor applied

    RxClassResponse:
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/ResponseMeta'
        class_id:
          type: string
        class_name:
          type: string
        class_type:
          type: string
          description: Classification type (ATC, EPC, MOA, PE, VA, DISEASE, CHEM, SCHEDULE)
        source:
          type: string
        parent_class_id:
          type: string
        children_count:
          type: integer

    RxClassMembersResponse:
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/ResponseMeta'
        class_id:
          type: string
        class_name:
          type: string
        members:
          type: array
          items:
            type: object
            properties:
              rxcui:
                type: string
              name:
                type: string
              relationship:
                type: string
        total:
          type: integer
        page:
          type: integer
        limit:
          type: integer

    SmaStatesListResponse:
      type: object
      properties:
        states:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              state:
                type: string
              abbreviation:
                type: string
              is_implemented:
                type: boolean
              api_vendor:
                type: string
        total:
          type: integer

    NcciValidationResponse:
      type: object
      properties:
        code1:
          type: string
        code2:
          type: string
        is_valid:
          type: boolean
          description: Whether the code pair can be billed together
        edit_type:
          type: string
        modifier_allowed:
          type: boolean

    MueResponse:
      type: object
      properties:
        hcpcs:
          type: string
        mue_value:
          type: integer
          description: Maximum units of service
        rationale:
          type: string
        service_type:
          type: string

    PfsResponse:
      type: object
      properties:
        hcpcs:
          type: string
        description:
          type: string
        work_rvu:
          type: number
        pe_rvu:
          type: number
        mp_rvu:
          type: number
        total_rvu:
          type: number
        conversion_factor:
          type: number

    CoverageCheckResponse:
      type: object
      properties:
        hcpcs:
          type: string
        determinations:
          type: array
          items:
            type: object
            properties:
              lcd_id:
                type: string
              title:
                type: string
              status:
                type: string
              contractor:
                type: string

    HcpcsResponse:
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/ResponseMeta'
        code:
          type: string
        short_description:
          type: string
        long_description:
          type: string
        category:
          type: string
        status_code:
          type: string
          enum: [A, T]
        fhir_coding:
          type: object
          properties:
            system:
              type: string
            code:
              type: string
            display:
              type: string

    HcpcsModifierResponse:
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/ResponseMeta'
        code:
          type: string
        short_description:
          type: string
        long_description:
          type: string
        status_code:
          type: string

    MsdrgResponse:
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/ResponseMeta'
        drg_code:
          type: string
        title:
          type: string
        mdc:
          type: string
          description: Major Diagnostic Category
        type:
          type: string
          enum: [SURG, MED]
        weight:
          type: number
        geometric_mean_los:
          type: number
        arithmetic_mean_los:
          type: number
        fhir_coding:
          type: object

    PosResponse:
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/ResponseMeta'
        code:
          type: string
        name:
          type: string
        description:
          type: string
        fhir_coding:
          type: object

    PosListResponse:
      type: object
      properties:
        codes:
          type: array
          items:
            $ref: '#/components/schemas/PosResponse'
        total:
          type: integer

    JcodeByHcpcsResponse:
      type: object
      properties:
        hcpcs_code:
          type: string
        hcpcs_description:
          type: string
        ndc_count:
          type: integer
        entries:
          type: array
          items:
            type: object
            properties:
              ndc:
                type: string
              drug_name:
                type: string
              labeler_name:
                type: string
              hcpcs_dosage:
                type: string
              bill_units:
                type: number

    JcodeByNdcResponse:
      type: object
      properties:
        ndc:
          type: string
        hcpcs_codes:
          type: array
          items:
            type: object
            properties:
              hcpcs_code:
                type: string
              hcpcs_description:
                type: string
              drug_name:
                type: string
              hcpcs_dosage:
                type: string
              bill_units:
                type: number

    Error:
      type: object
      required:
        - error
        - message
      properties:
        error:
          type: string
          description: Error code
        message:
          type: string
          description: Human-readable error message
        details:
          type: object
          description: Additional error context

  responses:
    BadRequest:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: "invalid_format"
            message: "Invalid code format"

    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: "not_found"
            message: "Code not found"

    Unauthorized:
      description: Missing or invalid authentication
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: "unauthorized"
            message: "Invalid or missing API key"