REST API

Data endpoints require an X-API-Key header; a small set of public endpoints needs none. A missing or wrong key returns 401.

Once you have a key, include it on every request to the data endpoints. In the interactive docs at /docs, click Authorize and paste it once:

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

https://api.twinfyrx.com

All endpoints are versioned under /v1.

Every response carries three diagnostic headers:

Supply your own X-Request-ID on outbound calls to correlate requests across your own logs. X-Schema-Version and X-Data-As-Of are exposed via CORS so browser clients can read them.

All error responses follow a consistent structure. The request_id field matches the X-Request-ID header and is the primary reference for support:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Drug with drug_id 999999 not found",
    "request_id": "a3f2c1d8-7b4e-4e2a-9c1f-0d5e8a3b2f91"
  }
}

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

{
  "results": [
    {
      "drug_id": 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
}

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

{
  "drug": { "drug_id": 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 }
  ]
}

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

ATC therapeutic classification hierarchy and NDC identifier resolution.

Medicare Part D prescribing per NPI (2024), mapped onto RxNorm ingredients and WHO ATC classes: who prescribes a class or ingredient, how much, and each prescriber's specialty and volume decile. Claims are counted at ingredient and ATC levels 2–4 — CMS drug names carry no strength or form. CMS suppresses rows under 11 claims, so volumes are lower bounds.

{
  "npi": "1234567893",
  "first_name": "JANE",
  "last_name": "DOE",
  "city": "BOSTON",
  "state": "MA",
  "specialty": {
    "provider_type": "physician",
    "specialty_key": "cardiology",
    "specialty_name": "Cardiology",
    "practice_setting": "office",
    "specialty_confidence": "high",
    "cms_prescriber_type": "Cardiology"
  },
  "prescribing": {
    "data_year": 2024,
    "claims": 9120,
    "drug_cost": 1840250.12,
    "n_ingredients": 64,
    "n_atc4": 41,
    "brand_claim_share": 0.21,
    "top_atc2": "C10",
    "top_atc2_share": 0.27,
    "deciles": { "national": 10, "prescriber_type": 8, "state": 9 }
  }
}

List endpoints return a consistent envelope. The response also carries an X-Total-Count header with the untruncated count, useful for building UI paginators without parsing the body:

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

# Response header:
X-Total-Count: 142

Rate limits are enforced per API key. Specific limits are communicated during onboarding and vary by tier. When a limit is exceeded, the API returns 429 Too Many Requests with a Retry-After header indicating how many seconds to wait before retrying.

HTTP/1.1 429 Too Many Requests
Retry-After: 30
X-Request-ID: a3f2c1d8-7b4e-4e2a-9c1f-0d5e8a3b2f91

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Retry after 30 seconds.",
    "request_id": "a3f2c1d8-7b4e-4e2a-9c1f-0d5e8a3b2f91"
  }
}