API Reference · v1
A small HTTP API that normalizes a drug name against RxNorm, pulls the matching openFDA record, and returns an AI plain-language summary alongside the primary sources. Issued to a handful of people directly — no public signup.
https://api.rxclarity.app
Section 01
Every request needs an X-API-Key header. Keys are issued individually — ask for one if you don't have it yet. There's no OAuth flow, no signup form; it's a flat shared secret per caller.
curl \ -H "X-API-Key: YOUR_KEY" \ "https://api.rxclarity.app/medication/ibuprofen"
A missing or unrecognized key returns 401 before any lookup work happens. The failed attempt is still recorded — see Errors.
Section 02
Looks up a medication by name. {name} is matched against RxNorm first (typos and brand names both resolve — Advil resolves the same as ibuprofen), then the normalized generic name is used to query the requested openFDA dataset.
| Parameter | Type | Description |
|---|---|---|
| name | path | Drug name, brand or generic. URL-encode spaces and punctuation. |
| source | query, optional | label (default) · ndc · drugsfda — which openFDA dataset to summarize. |
source=label — safety & usage, from the FDA drug label (indications, dosage, warnings, pregnancy/pediatric guidance, overdose).
source=ndc — packaging & product details, from the NDC directory.
source=drugsfda — approval history and regulatory status, from Drugs@FDA.
| Response field | Type | Description |
|---|---|---|
| medication | string | The name exactly as you sent it. |
| normalized_name | string | The RxNorm-resolved generic name actually looked up. |
| source | string | Echoes the source you requested. |
| summary | string | The AI plain-language summary, in short paragraphs separated by blank lines. |
| raw_fda_text | string | null | The unedited source text the summary was built from. |
| source_url | string | null | DailyMed (label/ndc) or Drugs@FDA (drugsfda) link to verify the primary record. |
| medlineplus_url | string | null | MedlinePlus consumer drug page. Only populated for source=label. |
Example — GET /medication/ibuprofen?source=label:
{
"medication": "ibuprofen",
"normalized_name": "ibuprofen",
"source": "label",
"summary": "What it's used for:\nIbuprofen is a pain reliever and fever reducer. It temporarily helps with headaches, toothaches, backaches…", // truncated for this example
"raw_fda_text": "Indications and usage:\nUses temporarily relieves minor aches and pains…", // truncated
"source_url": "https://dailymed.nlm.nih.gov/dailymed/drugInfo.cfm?setid=00653b7c-7099-487e-9a01-e89781c21323",
"medlineplus_url": "https://medlineplus.gov/druginfo/meds/a682159.html"
}
Returns aggregate call counts per key and the 50 most recent requests (successes, failures, and rejected auth attempts). Same X-API-Key header, any valid key can read it.
{
"counts_by_caller": [
{ "caller": "andy", "count": 5, "failures": 1, "total_tokens": 22556, "avg_latency_ms": 6152 }
],
"recent": [
{ "caller": "andy", "medication": "atorvastatin", "source": "label",
"ok": true, "error": null, "latency_ms": 8851, "total_tokens": 9187,
"client_ip": "107.213.134.25", "created_at": "2026-09-21T01:19:41Z" }
]
}
Section 03
20 requests per 60 seconds, per source IP, across all endpoints. It resets on a rolling window, not a fixed clock — there's no bulk quota beyond that.
Every request also calls a paid model to generate its summary (cached results are free and near-instant — repeat lookups of the same drug/source return in well under a second). A cold lookup typically takes 4–10 seconds; occasionally longer under load.
Section 04
Error bodies are always { "detail": "…" }. Status codes used:
source has no data for it. RxNorm has no match, or openFDA has nothing on file.
Section 05
Calls the live API straight from this page with your own key. Nothing you enter here is sent anywhere but the API itself; the key is kept only in this browser tab's session storage.