API Reference

REST API

A structured, versioned API for querying the full TwinFyRx drug intelligence platform. All endpoints return JSON and follow consistent patterns for pagination, errors, and resource nesting.

Setup

Authentication

All API requests require an API key passed via the X-API-Key header.

curl -H "X-API-Key: your_api_key" \
  https://api.twinfyrx.com/v1/drugs/search?q=atorvastatin

API keys are issued during onboarding. Request access to get started. Demo endpoints (/v1/demo/*) are publicly accessible without authentication.

Setup

Base URL

https://api.twinfyrx.com

All endpoints are versioned under /v1.

Setup

Error Handling

All error responses follow a consistent structure:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Drug with rxcui 999999 not found"
  }
}

Status	Code	Meaning
401	UNAUTHORIZED	Missing or invalid API key
404	NOT_FOUND	Resource not found
422	VALIDATION_ERROR	Invalid query parameters
500	INTERNAL_ERROR	Unexpected server error

Core

Drugs

Search, retrieve, and explore the drug concept hierarchy. Every response anchors to a canonical RxNorm drug concept.

GET/v1/drugs/search

Search drugs by name, ingredient, or brand name. Returns paginated results.

Parameters

qstringREQUIREDSearch query (min 2 characters)

limitintegerResults per page (1–100, default 20)

offsetintegerPagination offset

Response

results[]DrugSummaryArray of matching drugs

.rxcuiintegerRxNorm concept ID (drug_id)

.drug_namestringFull clinical drug name

.ingredientstringActive ingredient(s)

.is_genericbooleanWhether this is a generic concept

totalintegerTotal matching results

Example Response

{
  "results": [
    {
      "rxcui": 617314,
      "drug_name": "atorvastatin 20 MG Oral Tablet",
      "ingredient": "atorvastatin",
      "dose_form": "Oral Tablet",
      "clinical_drug_form": "atorvastatin Oral Tablet",
      "brand_name": null,
      "is_generic": true
    }
  ],
  "total": 12,
  "limit": 20,
  "offset": 0
}

GET/v1/drugs/{rxcui}

Full drug detail including RxNorm hierarchy, therapy attributes, and branded variants.

Parameters

rxcuiintegerREQUIREDRxNorm concept ID (path parameter)

Response

rxcuiintegerDrug concept ID

drug_namestringFull drug name

ingredient_rxcuiintegerIngredient concept ID

clinical_drug_form_rxcuiintegerDrug form concept ID

therapy_patternstringTherapy behavior enum

specialty_flagbooleanSpecialty drug indicator

benefit_channelstringPharmacy, medical, or dual

GET/v1/drugs/{rxcui}/icd10-volumes

Utilization-weighted drug-to-diagnosis mappings with percent volume estimates.

Response

drugDrugSummaryDrug summary object

is_single_indication_drugbooleanWhether drug maps to a single diagnosis

icd10_volumes[]ICD10VolumeDiagnoses sorted by volume

.icd10_codestringICD-10-CM code

.pct_volumedecimalEstimated % of prescriptions for this diagnosis

.is_dominant_indicationbooleanWhether this is the primary indication

GET/v1/drugs/{rxcui}/suspecting-rules

All active suspecting rules for a drug. Each rule contains structured JSON logic for execution.

Response

drugDrugSummaryDrug summary

rule_countintegerTotal rules returned

rules[]SuspectingRuleArray of executable rules

.rule_categorystringprescriber_specialty, concurrent_rx, compound, etc.

.rule_strengthstringstrong_prior, weak_prior, or exclusion

.rule_logicobjectStructured logic for SQL generation

.confidencedecimalBase confidence score (0–1)

Market Intelligence

Pricing

NADAC acquisition costs (weekly cadence) and Medicare Part B ASP payment limits (quarterly). Both resolve through the drug concept hierarchy.

GET/v1/drugs/{rxcui}/pricing

Current pricing snapshot — latest NADAC week and latest ASP quarter for a drug.

Response

drugDrugSummaryDrug summary

nadacNADACSnapshot | nullLatest NADAC pricing (if available)

.median_per_unitdecimalMedian acquisition cost per unit

.pricing_unitstringUnit label (e.g., 'EACH', 'ML')

aspASPSnapshot | nullLatest ASP pricing (if available)

.median_payment_limitdecimalMedian Part B payment limit

GET/v1/drugs/{rxcui}/nadac

Historical NADAC pricing with weekly granularity. Defaults to 2 years of history.

Parameters

startdateStart date (YYYY-MM-DD, default: 2 years ago)

enddateEnd date (YYYY-MM-DD, default: today)

Response

pricing_unitstringUnit of measure

weeks[]NADACWeekWeekly pricing data points

.as_of_datedateEffective date

.median_per_unitdecimalMedian cost per unit

.ndc_countintegerNDCs contributing to this aggregate

Example Response

{
  "drug": { "rxcui": 617314, "drug_name": "atorvastatin 20 MG Oral Tablet" },
  "pricing_unit": "EACH",
  "weeks": [
    { "as_of_date": "2026-03-05", "median_per_unit": 0.0412, "min_per_unit": 0.0389, "max_per_unit": 0.0445, "ndc_count": 14 },
    { "as_of_date": "2026-02-26", "median_per_unit": 0.0415, "min_per_unit": 0.0391, "max_per_unit": 0.0448, "ndc_count": 14 }
  ]
}

GET/v1/drugs/{rxcui}/asp

Historical ASP (Medicare Part B) payment limits by quarter with HCPCS code mappings.

Response

quarters[]ASPQuarterQuarterly ASP data points

.effective_quarterstringe.g., '2026Q1'

.median_payment_limitdecimalMedian payment limit per unit

.hcpcs_codesstring[]Associated HCPCS codes

Reference

Diagnoses

Search and explore ICD-10-CM diagnoses with reverse drug mappings — find which drugs are most commonly prescribed for a given condition.

GET/v1/diagnoses/search

Search ICD-10 diagnoses by code or description text.

Parameters

qstringREQUIREDICD-10 code or description text

limitintegerResults per page (default 20)

Response

results[]DiseaseSummaryMatching diagnoses

.icd10_codestringICD-10-CM code

.diagnosisstringDiagnosis description

.is_billablebooleanWhether this is a billable code

GET/v1/diagnoses/{icd10_code}

Full diagnosis detail including ICD-10 hierarchy and top 20 drugs prescribed for this condition.

Response

icd10_codestringICD-10-CM code

diagnosisstringFull description

chapter_namestringICD-10 chapter

is_billablebooleanBillable indicator

top_drugs[]DrugForDiseaseTop 20 drugs by prescribing volume

.pct_volumedecimalEstimated share of prescriptions

Reference

Classification & Identifiers

ATC therapeutic classification hierarchy and NDC identifier resolution.

GET/v1/atc/search

Search ATC classification codes by code or name.

Parameters

qstringREQUIREDATC code or therapeutic class name

GET/v1/atc/{atc_code_5}

Full 5-level ATC hierarchy for a given code.

Response

atc_code_1 → atc_code_5stringAll 5 ATC hierarchy levels

atc_name_1 → atc_name_5stringNames for each level

GET/v1/drugs/{rxcui}/atc

All ATC classifications for a drug concept.

GET/v1/ndc/{ndc_code}

Resolve an NDC code to its drug concept with therapy attributes and specialty flags.

Response

ndcstringInput NDC code

rxcuiintegerResolved drug concept ID

drug_namestringDrug name

therapy_patternstringTherapy behavior classification

specialty_flagbooleanSpecialty drug indicator

Patterns

Pagination

List endpoints return paginated responses with a consistent envelope:

{
  "results": [ ... ],
  "total": 142,
  "limit": 20,
  "offset": 0
}

Use limit and offset query parameters to page through results.

Patterns

Rate Limits

Rate limits are enforced per API key. Current limits are communicated during onboarding. If you receive a 429 response, back off and retry after the period indicated in the response headers.

Developer Hub SDK Guide