Using the API

Endpoint reference: 52 operations.

52 operations across 45 paths. Everything below is generated from the OpenAPI 3.1 document this API serves, so it cannot drift from what the server actually does.

Base URL is https://drug-database.com/v1. Every operation takes Authorization: Bearer dd_(live|test)_… unless it is marked public. Scopes are explained in Authentication; status codes in Errors.

Prefer the machine-readable form

/api/v1/openapi.json is public and needs no key. Point a client generator at it rather than transcribing this page. To run a call without writing any code, use the explorer.

drugs

Marketed products, per jurisdiction. Search, resolve an identifier, read the full record.

GET/v1/drugsdrugs:read

Search drugs (typeahead).

Typeahead across all loaded jurisdictions. Filter by `country` (CH/GB/FR/DE/IT/AT/ES/DK/SE/FI/NO/NL/BE/IE/PT/US). Scope: `drugs:read`.

Query parameters

qstring
A name OR any code. Codes are tried first: ATC (C10AA05, or a class prefix like C10AA), NDC (dashed, 10- or 11-digit), GTIN-8/12/13/14, CIP13/CIP7, AIC, PZN, Swissmedic and other national pack/registration numbers, FDA UNII, RxCUI (`rxcui:83367`). Otherwise an ilike match on product_name OR substance_name, so an INN finds the brands that carry it. Each row and the response carry `matched_by`.
countrystringdefault CH
ISO 3166-1 alpha-2, or `ALL` for every register. Name search defaults to CH on /v1 (deprecated; responses without an explicit country carry a `Deprecation` header) — pass `country=ALL` for a global search. A code match is only narrowed by an explicit country.
atcstring
Prefix filter on atc_code.
limitintegerdefault 20

Responses200401403422

Example request
curl
curl -s 'https://drug-database.com/v1/drugs' \
  -H 'Authorization: Bearer dd_live_YOUR_KEY'
GET/v1/drugs/{id}drugs:read

Full drug record.

Full drug record + identifiers + ATC parent chain + monograph language availability. `?format=fhir` returns a FHIR R4 Medication. Scope: `drugs:read`.

Path parameters

idstring (uuid)required

Query parameters

formatstringdefault json
json · fhir

Responses200304401403404422

Example request
curl
curl -s 'https://drug-database.com/v1/drugs/YOUR_ID' \
  -H 'Authorization: Bearer dd_live_YOUR_KEY'

The same medicine in every other country.

Products in every register with the same active substance(s), strength, dose form and route (`same_medicine`, the pharmaceutical product) and with the same active substance(s) in any form (`same_substance`), grouped by country with exact counts. `basis` is `identity` (substance layer: UNII-keyed substances, salts folded to the active moiety), `atc` (fallback: same level-5 ATC class) or `none`. Scope: `drugs:read`.

Path parameters

idstring (uuid)required

Query parameters

per_countryintegerdefault 3
Products listed per country.

Responses200404

Example request
curl
curl -s 'https://drug-database.com/v1/drugs/YOUR_ID/equivalents' \
  -H 'Authorization: Bearer dd_live_YOUR_KEY'

AIPS monograph in the requested language.

Swiss AIPS monograph text for a drug in the requested language. Scope: `drugs:read`.

Path parameters

idstring (uuid)required

Query parameters

langstringdefault de
de · fr · it

Responses200401403404422

Example request
curl
curl -s 'https://drug-database.com/v1/drugs/YOUR_ID/monograph' \
  -H 'Authorization: Bearer dd_live_YOUR_KEY'

Everything view for one drug.

The core record plus drug information texts (indications, contraindications, warnings, boxed warning, adverse reactions, drug interactions), Switzerland (BAG SL) + US (NADAC) pricing and this product’s own pack prices, known interactions for its ATC, a substance adverse-event signal, and cross-country availability. Each section is best-effort and may be null/empty. Scope: `drugs:read`.

Path parameters

idstring (uuid)required

Responses200401403404422

Example request
curl
curl -s 'https://drug-database.com/v1/drugs/YOUR_ID/profile' \
  -H 'Authorization: Bearer dd_live_YOUR_KEY'
GET/v1/drugs/lookupdrugs:read

Resolve an identifier to the canonical drug record.

Resolve any pack-level identifier (GTIN, Pharmacode, CIP-13, PZN, Swissmedic-No, EAN, NDC11, dm+d AMPPID) to the canonical drug record. Scope: `drugs:read`.

Query parameters

systemstringrequired
gtin · pharmacode · cip13 · pzn · swissmedic_no · ean · ndc11 · dmd_amppid · aic · be_apb · cbg_meb_id · cima_codigo · cz_kod_sukl · dk_varenummer · fi_myyntilupa · ie_pa_number · no_merkevare_id · no_varenummer · se_varunummer
codestringrequired

Responses200401403404422

Example request
curl
curl -s 'https://drug-database.com/v1/drugs/lookup?system=gtin&code=YOUR_CODE' \
  -H 'Authorization: Bearer dd_live_YOUR_KEY'

Pack lookup by identifier (path-shaped alias of /v1/drugs/lookup).

Resolve a pack-level identifier (GTIN, Pharmacode, CIP-13, PZN, Swissmedic-No, EAN, NDC11, dm+d AMPPID) to the canonical drug record. Same resolver as /v1/drugs/lookup; the identifier system is explicit in the URL path for cleaner integrations. Scope: `drugs:read`.

Path parameters

systemstringrequired
gtin · pharmacode · cip13 · pzn · swissmedic_no · ean · ndc11 · dmd_amppid · aic · be_apb · cbg_meb_id · cima_codigo · cz_kod_sukl · dk_varenummer · fi_myyntilupa · ie_pa_number · no_merkevare_id · no_varenummer · se_varunummer
codestringrequired

Responses200401403404422

Example request
curl
curl -s 'https://drug-database.com/v1/packs/gtin/YOUR_CODE' \
  -H 'Authorization: Bearer dd_live_YOUR_KEY'

substances

Active ingredients keyed by FDA UNII, and cross-registry identifiers for them.

Substance-level details by FDA UNII.

Returns the substance view (names across INN / RxNorm / EMA SPOR / CAS-RN, drugs that contain it, chemistry, ATC classes) keyed by FDA UNII. Scope: `drugs:read`.

Path parameters

uniistringrequired
FDA Unique Ingredient Identifier (e.g. WK2XYI10QM for ibuprofen).

Responses200401403404422

Example request
curl
curl -s 'https://drug-database.com/v1/substances/YOUR_UNII' \
  -H 'Authorization: Bearer dd_live_YOUR_KEY'
GET/v1/substances/xrefdrugs:read

Resolve a substance name to a UNII + cross-vocabulary codes.

Resolve a substance NAME to its FDA UNII, cross-vocabulary codes, and chemical structure via NCATS Inxight / GSRS. Scope: `drugs:read`.

Query parameters

namestringrequired
Substance name, e.g. ibuprofen.

Responses200401403404422

Example request
curl
curl -s 'https://drug-database.com/v1/substances/xref?name=YOUR_NAME' \
  -H 'Authorization: Bearer dd_live_YOUR_KEY'

atc

The WHO ATC tree — one node, its children, and the products under it.

GET/v1/atc/{code}atc:read

ATC node + parent chain.

WHO ATC node + parent chain + labels + DDD. Scope: `atc:read`.

Path parameters

codestringrequired

Responses200304401403404422

Example request
curl
curl -s 'https://drug-database.com/v1/atc/YOUR_CODE' \
  -H 'Authorization: Bearer dd_live_YOUR_KEY'

Direct children of an ATC node.

Direct children of an ATC node. Scope: `atc:read`.

Path parameters

codestringrequired

Responses200304401403404422

Example request
curl
curl -s 'https://drug-database.com/v1/atc/YOUR_CODE/children' \
  -H 'Authorization: Bearer dd_live_YOUR_KEY'

Drugs in this ATC subtree (descendants included).

All drugs in the ATC subtree (prefix match), paginated. Scope: `atc:read`.

Path parameters

codestringrequired

Query parameters

countrystringdefault CH
ISO 3166-1 alpha-2, or `ALL` for every register (default CH on /v1).
limitintegerdefault 50
offsetintegerdefault 0

Responses200304401403404422

Example request
curl
curl -s 'https://drug-database.com/v1/atc/YOUR_CODE/drugs' \
  -H 'Authorization: Bearer dd_live_YOUR_KEY'

Therapeutic class lookup (alias of /v1/atc/{code}).

Developer-friendly alias for /v1/atc/{code}. Same response shape — "therapy" reads more naturally to non-pharma callers ("which drugs treat asthma? GET /v1/therapies/R03"). Scope: `atc:read`.

Path parameters

codestringrequired

Responses200304401403404422

Example request
curl
curl -s 'https://drug-database.com/v1/therapies/YOUR_CODE' \
  -H 'Authorization: Bearer dd_live_YOUR_KEY'

classes

Therapeutic classes on every axis: WHO ATC plus the FDA pharmacologic classes.

GET/v1/classesatc:read

Browse / search therapeutic classes across every axis.

Therapeutic classes on all axes — WHO ATC (levels 1–5) plus the FDA pharmacologic classes from RxClass (EPC / MoA / PE / CS) and MeSH pharmacologic actions. Every row carries its rollup (drug / substance / market counts), so "statins → how many products, in how many markets" is one call. Scope: `atc:read`.

Query parameters

systemstring
Restrict to one classification axis. Omit for all axes.atc · epc · moa · pe · cs · mesh_pa
qstring
Free-text match on label (substring) or code (prefix).
levelinteger
ATC level 1–5. The FDA/MeSH axes are flat and carry no level.
min_drugsinteger
Only classes with at least this many drugs.
marketstring
ISO 3166-1 alpha-2. Only classes with products in that market.
sortstringdefault drugs
drugs · markets · code · label
limitintegerdefault 50
offsetintegerdefault 0

Responses200304401403422

Example request
curl
curl -s 'https://drug-database.com/v1/classes' \
  -H 'Authorization: Bearer dd_live_YOUR_KEY'

One therapeutic class + hierarchy + cross-axis references.

A single class with its rollup, ancestor chain, direct children, a sample of member substances, and the classes on OTHER axes that share those substances. Scope: `atc:read`.

Path parameters

systemstringrequired
atc · epc · moa · pe · cs · mesh_pa
codestringrequired
ATC code (uppercased) or the opaque RxClass class id, e.g. `N0000175655`.

Responses200304401403404422

Example request
curl
curl -s 'https://drug-database.com/v1/classes/atc/YOUR_CODE' \
  -H 'Authorization: Bearer dd_live_YOUR_KEY'

Products in a therapeutic class, on any axis.

The drugs in a class, paginated. ATC is a prefix scan on the subtree; the FDA/MeSH axes walk class → substances → ATC codes → drugs. `country` is optional (unlike /v1/atc/{code}/drugs, which defaults to CH) because a class rollup is cross-market by nature. Scope: `atc:read`.

Path parameters

systemstringrequired
atc · epc · moa · pe · cs · mesh_pa
codestringrequired

Query parameters

countrystring
ISO 3166-1 alpha-2. Omit for all jurisdictions.
limitintegerdefault 50
offsetintegerdefault 0

Responses200304401403404422

Example request
curl
curl -s 'https://drug-database.com/v1/classes/atc/YOUR_CODE/drugs' \
  -H 'Authorization: Bearer dd_live_YOUR_KEY'

interactions

Pairwise and N-way interaction screening across jurisdictions.

POST/v1/interactions/checkany valid key

Pairwise + N-way interaction check across an ATC-mapped drug list.

N-way ATC interaction check; resolves each drug reference to an ATC and checks unique sorted pairs. Any key: non-commercially licensed rows (DDInter, CC BY-NC 4.0) are returned to every plan, unmetered, each with its `licence` and `attributions`. Commercially licensed rows (mechanism + management) need `interactions:write` (growth+) and quota left; otherwise they are withheld and counted in `locked.count` (`locked.why`: `plan_does_not_include` | `no_credit_left`).

Request body application/json — required.

Responses200401403422

Example request
curl
curl -s 'https://drug-database.com/v1/interactions/check' \
  -X POST \
  -H 'Authorization: Bearer dd_live_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ }'

markets

One comparable price per market for the same substance.

Cross-market price-per-DDD comparison for a substance.

Substance-centric market comparison. `q` accepts ANY drug identifier — substance/INN, brand name, internal UUID, pharmacode / GTIN / NDC / CIP13 / PZN, or ATC code — and resolves it to the substance ATC, returning one comparable price-per-DDD (USD) per market. The price basis is reported explicitly per market (`per_ddd` / `per_unit` / `per_pack` / `none`): a gradient value is emitted ONLY where a true WHO DDD normalization was possible, so the number never over-claims comparability. Scope: `drugs:read`.

Query parameters

qstringrequired
Substance, brand, UUID, pharmacode/GTIN/NDC/CIP13/PZN, or ATC code.
countriesstringdefault all
"all" (default) or a comma list, e.g. CH,US,FR.

Responses200401403404422

Example request
curl
curl -s 'https://drug-database.com/v1/markets/overview?q=YOUR_Q' \
  -H 'Authorization: Bearer dd_live_YOUR_KEY'

changes

The diff feed — what moved in the registers, since a timestamp.

GET/v1/changeschanges:read

Cross-source diff feed. Cursor-paginated.

Cross-source change feed, cursor-paginated over (occurred_at, id). Scope: `changes:read`.

Query parameters

sincestring (date-time)
cursorstring
Opaque continuation token from previous response.
limitintegerdefault 100

Responses200401403422

Example request
curl
curl -s 'https://drug-database.com/v1/changes' \
  -H 'Authorization: Bearer dd_live_YOUR_KEY'

webhooks

Push subscriptions for the change feed.

POST/v1/webhookswebhooks:write

Create a webhook subscription on the /v1/changes feed.

Create a webhook subscription on the changes feed. The signing `secret` is returned exactly ONCE in the 201 body. Scope: `webhooks:write`.

Request body application/json — required.

Responses201401403422

Example request
curl
curl -s 'https://drug-database.com/v1/webhooks' \
  -X POST \
  -H 'Authorization: Bearer dd_live_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ }'
DELETE/v1/webhookswebhooks:write

Delete a webhook subscription.

Delete a tenant-scoped webhook subscription by id. Scope: `webhooks:write`.

Query parameters

idstring (uuid)required

Responses204401403404422

Example request
curl
curl -s 'https://drug-database.com/v1/webhooks?id=YOUR_ID' \
  -X DELETE \
  -H 'Authorization: Bearer dd_live_YOUR_KEY'

rxnorm

RxNorm concept resolution and the UMLS-licensed crosswalk.

GET/v1/rxnorm/{rxcui}drugs:read

On-demand RxNorm enrichment by rxcui.

Enriches one RxNorm concept from the public RxNav API (name, ingredients, brands, dose-form drugs, ATC class, NDCs) and — when a UMLS license key is configured server-side — the licensed SNOMED CT / MeSH crosswalk. Each upstream degrades to partial data on failure. Scope: `drugs:read`.

Path parameters

rxcuistringrequired
RxNorm concept identifier (e.g. 617310 for atorvastatin 20 MG Oral Tablet).

Responses200401403404422

Example request
curl
curl -s 'https://drug-database.com/v1/rxnorm/YOUR_RXCUI' \
  -H 'Authorization: Bearer dd_live_YOUR_KEY'
GET/v1/rxnorm/resolvedrugs:read

Resolve a drug name to an RxNorm rxcui.

Maps a free-text name (substance, brand, or full product string) to an rxcui via RxNav — exact normalized match first, then approximate matching. Pair with /v1/rxnorm/{rxcui} for full enrichment. Scope: `drugs:read`.

Query parameters

namestringrequired
Drug name, e.g. atorvastatin.

Responses200401403404422

Example request
curl
curl -s 'https://drug-database.com/v1/rxnorm/resolve?name=YOUR_NAME' \
  -H 'Authorization: Bearer dd_live_YOUR_KEY'

enrichment

On-demand passthrough resolvers over external public APIs.

GET/v1/assessmentdrugs:read

Drug × indication feasibility assessment (composed).

One-call go/no-go view for a (drug, indication) pair — composes the evidence layers so you don't stitch /v1/targets → /v1/targets/genetics → /v1/signatures → /v1/guidelines → /v1/hta by hand. Returns the drug's targets each with human-genetic association + directionality-**concordance** (does the mechanism phenocopy protective genetics?) + a de-risking profile (essentiality, LoF constraint, tractability, safety liabilities); a curated LINCS reversal for the indication (flagging whether the drug itself is a reverser); clinical guidelines + HTA decisions; and a `summary` rollup for scoring. Each sub-signal is individually cached. Scope: `drugs:read`.

Query parameters

drugstringrequired
Drug name (e.g. evolocumab).
indicationstringrequired
Disease label or ontology id (e.g. familial hypercholesterolemia).

Responses200401403404422

Example request
curl
curl -s 'https://drug-database.com/v1/assessment?drug=YOUR_DRUG&indication=YOUR_INDICATION' \
  -H 'Authorization: Bearer dd_live_YOUR_KEY'
GET/v1/chembldrugs:read

ChEMBL molecule enrichment.

On-demand molecule enrichment from the EBI ChEMBL REST API, by ChEMBL id or substance name. Scope: `drugs:read`.

Query parameters

chembl_idstring
ChEMBL molecule id (e.g. CHEMBL521). Provide this OR `name`.
namestring
Substance name. Provide this OR `chembl_id`.

Responses200401403404422

Example request
curl
curl -s 'https://drug-database.com/v1/chembl' \
  -H 'Authorization: Bearer dd_live_YOUR_KEY'
GET/v1/drugsfdadrugs:read

Drugs@FDA approvals.

FDA approval history from the openFDA drugsfda endpoint, by name. Scope: `drugs:read`.

Query parameters

namestringrequired
Substance / drug name.

Responses200401403404422

Example request
curl
curl -s 'https://drug-database.com/v1/drugsfda?name=YOUR_NAME' \
  -H 'Authorization: Bearer dd_live_YOUR_KEY'
GET/v1/gtopdbdrugs:read

Guide to Pharmacology target affinities.

Target affinities for a ligand from the IUPHAR/BPS Guide to Pharmacology, by substance name. Scope: `drugs:read`.

Query parameters

namestringrequired
Ligand / substance name.

Responses200401403404422

Example request
curl
curl -s 'https://drug-database.com/v1/gtopdb?name=YOUR_NAME' \
  -H 'Authorization: Bearer dd_live_YOUR_KEY'
GET/v1/guidelinesdrugs:read

Clinical-guideline pathway nodes (NCCN/ESMO/NICE).

Line-of-therapy recommendations from ingested clinical guidelines — NOT ATC classification (cf. /v1/therapies). Filter by indication, ATC, or source; at least one required. **Coverage:** this catalogue is licensing-gated (NCCN licensed, NICE syndication key) and may not yet be populated — an empty match returns a `coverage` note rather than a 404. Scope: `drugs:read`.

Query parameters

indicationstring
Condition / disease (substring match).
atcstring
ATC code the recommendation concerns.
sourcestring
Issuing body (nccn | esmo | nice | asco).

Responses200401403422

Example request
curl
curl -s 'https://drug-database.com/v1/guidelines' \
  -H 'Authorization: Bearer dd_live_YOUR_KEY'
GET/v1/htadrugs:read

HTA cost-effectiveness decisions (NICE/ICER/CADTH/IQWiG).

Health-technology-assessment decisions with cost-effectiveness economics — ICER/QALY ratios, reimbursement decisions, AND the ICER Health-Benefit Price Benchmark (hbpb_low/hbpb_high = the value-based price range, with list_price for the value gap). The layer that list prices and a boolean reimbursement flag cannot express (cf. /v1/ch/price-comparison). Filter by drug, indication, country, or source; at least one required. Seeded with verified ICER assessments; NICE/CADTH population is licensing-gated. An empty match returns a `coverage` note rather than a 404. Scope: `drugs:read`.

Query parameters

drugstring
Drug name (substring match).
indicationstring
Condition / disease (substring match).
countrystring
ISO-3166 alpha-2 country of the HTA body (GB/US/CA/DE).
sourcestring
HTA body (nice | icer | cadth | iqwig | smc).

Responses200401403422

Example request
curl
curl -s 'https://drug-database.com/v1/hta' \
  -H 'Authorization: Bearer dd_live_YOUR_KEY'
GET/v1/openfdadrugs:read

openFDA NDC drug classification.

Pharmacologic class + labelling metadata from the openFDA NDC endpoint, by name. Scope: `drugs:read`.

Query parameters

namestringrequired
Substance / drug name.

Responses200401403404422

Example request
curl
curl -s 'https://drug-database.com/v1/openfda?name=YOUR_NAME' \
  -H 'Authorization: Bearer dd_live_YOUR_KEY'
GET/v1/pgxdrugs:read

CPIC pharmacogenomics guidance.

CPIC pharmacogenomic guideline data for a drug, by name. Scope: `drugs:read`.

Query parameters

namestringrequired
Drug name.

Responses200401403404422

Example request
curl
curl -s 'https://drug-database.com/v1/pgx?name=YOUR_NAME' \
  -H 'Authorization: Bearer dd_live_YOUR_KEY'
GET/v1/signaturesdrugs:read

LINCS reversal for a curated disease signature (by indication).

Option-B lookup: resolve a curated per-indication disease signature from the drug-database (seeded from published GEO differential-expression studies) and run the same LINCS reversal scoring as the POST path — so you can ask "what reverses endometriosis?" without supplying a gene set. Returns the resolved `signature` (provenance + gene counts) alongside reverser/mimicker results. A 404 lists the indications currently curated. Scope: `drugs:read`.

Query parameters

indicationstring
Curated indication label (e.g. endometriosis).
efostring
EFO/ontology id (e.g. EFO_0001065). One of indication/efo is required.

Responses200401403404422

Example request
curl
curl -s 'https://drug-database.com/v1/signatures' \
  -H 'Authorization: Bearer dd_live_YOUR_KEY'
POST/v1/signaturesdrugs:read

LINCS / CMap signature-reversal scoring for a disease signature.

Score a caller-supplied disease expression signature (up- and down-regulated gene symbols) against LINCS L1000 (L1000FWD): which compounds REVERSE the signature (candidate therapeutics — a mechanism-agnostic efficacy signal independent of the target hypothesis) and which MIMIC it. Returns the top reversers/mimickers with a signed connectivity score and resolved compound identity (Broad BRD id + best-effort drug name, cell line, dose). Cached by the order-independent gene set. Scope: `drugs:read`.

Request body application/json — required.

Responses200401403404422

Example request
curl
curl -s 'https://drug-database.com/v1/signatures' \
  -X POST \
  -H 'Authorization: Bearer dd_live_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ }'
GET/v1/targetsdrugs:read

Open Targets associations for a drug.

Drug → target associations from the Open Targets GraphQL platform, by name. Scope: `drugs:read`.

Query parameters

namestringrequired
Drug name.

Responses200401403404422

Example request
curl
curl -s 'https://drug-database.com/v1/targets?name=YOUR_NAME' \
  -H 'Authorization: Bearer dd_live_YOUR_KEY'

Open Targets Genetics — L2G, direction of effect, drug concordance.

Human-genetic causal layer for a (gene, disease) pair from the Open Targets GraphQL platform: genetic-association score, per-datasource evidence with Locus-to-Gene scores and direction of effect (LoF/GoF on the target, risk/protect on the trait), and a summarised protective target direction. When `drug` is supplied, adds a directionality-**concordance** verdict — whether the drug's mechanism phenocopies the protective human genetics (`concordant`, de-risking) or opposes it (`discordant`, red flag). Scope: `drugs:read`.

Query parameters

genestringrequired
Gene symbol or Ensembl id (e.g. PCSK9 or ENSG00000169174).
diseasestringrequired
Disease label or ontology id (e.g. "familial hypercholesterolemia" or MONDO_0005439).
drugstring
Optional drug name — enables the directionality-concordance verdict against the drug's mechanism of action.

Responses200401403404422

Example request
curl
curl -s 'https://drug-database.com/v1/targets/genetics?gene=YOUR_GENE&disease=YOUR_DISEASE' \
  -H 'Authorization: Bearer dd_live_YOUR_KEY'

Target protein structure (UniProt + RCSB PDB).

Resolves a gene symbol to its UniProt record and known RCSB PDB structures. Scope: `drugs:read`.

Query parameters

symbolstringrequired
Gene / protein symbol (e.g. PTGS2).
organism_idintegerdefault 9606
NCBI taxonomy id (default 9606, human).

Responses200401403404422

Example request
curl
curl -s 'https://drug-database.com/v1/targets/structure?symbol=YOUR_SYMBOL' \
  -H 'Authorization: Bearer dd_live_YOUR_KEY'

prescriptions

Non-identifying prescription screening. Processes no PHI.

POST/v1/prescriptions/validateinteractions:write

Prescription interaction validation (in-project).

Validates a proposed prescription against a patient’s current medications entirely in-project, over our own reviewed interaction data — no external gateway. Scope: `interactions:write` (growth+). Processes and stores no protected health information (PHI): it accepts only drug identifiers plus coarse, non-identifying context (age band, sex, pregnancy, eGFR band, conditions, allergies). A defense-in-depth scrubber rejects any request body carrying identifying PHI fields (name, dob, mrn, email, ssn, ahv, address, …) with `422 phi_field_rejected`. On success the interaction decision is returned with `200`.

Request body application/json — required.

Responses200401403422

Example request
curl
curl -s 'https://drug-database.com/v1/prescriptions/validate' \
  -X POST \
  -H 'Authorization: Bearer dd_live_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ }'

ch

Swiss reimbursement pre-validation. Stateless and PHI-free.

Switzerland reimbursement pre-validation.

Stateless, PHI-free Swiss reimbursement pre-validation: on the SL list? capped price? Limitatio conditions? co-insurance? Also handles the MiGeL (`lima`) medical-aid path. Scope: `ch:claims` (growth+).

Request body application/json — required.

Responses200401403422

Example request
curl
curl -s 'https://drug-database.com/v1/ch/claims/validate' \
  -X POST \
  -H 'Authorization: Bearer dd_live_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ }'

Cheaper Swiss SL substitutes in the same ATC + pack size.

Finds cheaper SL substitutes in the same ATC and pack size (with substance/strength signature when available), including savings and co-insurance delta. Scope: `ch:claims` (growth+).

Request body application/json — required.

Responses200401403422

Example request
curl
curl -s 'https://drug-database.com/v1/ch/price-comparison' \
  -X POST \
  -H 'Authorization: Bearer dd_live_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ }'

byol

Bring-your-own-licence credential vault for sources we cannot redistribute.

GET/v1/byol/{provider}byol:write

Check BYOL configuration status for a provider.

Returns configuration metadata only (never plaintext credentials). Scope: `byol:write` (growth+).

Responses200401403422

Example request
curl
curl -s 'https://drug-database.com/v1/byol/{provider}' \
  -H 'Authorization: Bearer dd_live_YOUR_KEY'
POST/v1/byol/{provider}any valid key

Not supported — use PUT / GET / DELETE.

POST is not a valid method on this resource; use PUT to store, GET to check status, DELETE to remove.

Responses404

Example request
curl
curl -s 'https://drug-database.com/v1/byol/{provider}' \
  -X POST \
  -H 'Authorization: Bearer dd_live_YOUR_KEY'
PUT/v1/byol/{provider}byol:write

Store BYOL credentials for a provider.

Encrypt and store the tenant’s bring-your-own-licence credentials for a licensed data provider. Scope: `byol:write` (growth+).

Request body application/json — required.

Responses200401403422503

Example request
curl
curl -s 'https://drug-database.com/v1/byol/{provider}' \
  -X PUT \
  -H 'Authorization: Bearer dd_live_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ }'
DELETE/v1/byol/{provider}byol:write

Delete BYOL credentials for a provider.

Remove the tenant’s stored credentials for a provider. Scope: `byol:write` (growth+).

Responses204401403422503

Example request
curl
curl -s 'https://drug-database.com/v1/byol/{provider}' \
  -X DELETE \
  -H 'Authorization: Bearer dd_live_YOUR_KEY'

BYOL live passthrough query.

Runs one authenticated call against the tenant’s OWN licensed provider using the stored credential and returns the provider payload under a uniform envelope. The plaintext credential is decrypted inside the vault RPC, used for this single outbound request, and never logged, cached, or shared cross-tenant. Scope: `byol:write` (growth+).

Query parameters

qstring
Free-text lookup term.
idstring
Provider-specific record id.
pathstring
Provider-specific sub-resource, e.g. `products`.

Responses200401403404422502503

Example request
curl
curl -s 'https://drug-database.com/v1/byol/{provider}/query' \
  -H 'Authorization: Bearer dd_live_YOUR_KEY'
POST/v1/byol/{provider}/queryany valid key

Not supported — use GET.

POST is not valid here; use GET /v1/byol/{provider}/query?q=… to run a passthrough lookup.

Responses404

Example request
curl
curl -s 'https://drug-database.com/v1/byol/{provider}/query' \
  -X POST \
  -H 'Authorization: Bearer dd_live_YOUR_KEY'

chat

Natural-language questions over the catalogue, token-metered.

POST/v1/chatchat:write

Ask the Drug Database AI assistant.

Bearer-authed assistant over the Drug Database corpus. Non-streaming: the upstream token stream is consumed server-side so the real token count is known, then returned as one JSON object. Each turn draws on the monthly AI answer allowance included in the plan (Free 3, Pro 50, Starter 150, Growth 750), then on prepaid pack credits; an unusually long turn can count as more than one answer. When both are spent the turn is refused up front with `402 ai_allowance_exhausted` — nothing is ever billed as overage. Scope: `chat:write`, on every tier.

Request body application/json — required.

Responses200400401402403429502503

Example request
curl
curl -s 'https://drug-database.com/v1/chat' \
  -X POST \
  -H 'Authorization: Bearer dd_live_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ }'
POST/v1/chat/packschat:write

Buy a prepaid AI answer pack.

One-off Stripe Checkout for a prepaid pack of AI answers: 100 for $15 or 500 for $60. Paid plans only (Free gets `403 upgrade_required`). Pack credits carry over month to month and are drawn down after the monthly allowance. Scope: `chat:write`.

Request body application/json — required.

Responses200400401403404

Example request
curl
curl -s 'https://drug-database.com/v1/chat/packs' \
  -X POST \
  -H 'Authorization: Bearer dd_live_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ }'
POST/v1/chat/subscribeany valid key

Retired — chat plans are now included in every plan.

Separate chat plans (basic/pro/enterprise) are retired: AI answers are included in every API plan. Always returns 410 with a pointer to /pricing; use POST /v1/chat/packs to top up on a paid plan.

Responses410

Example request
curl
curl -s 'https://drug-database.com/v1/chat/subscribe' \
  -X POST \
  -H 'Authorization: Bearer dd_live_YOUR_KEY'

graphql

One POST endpoint and the schema behind it.

GET/v1/graphqlany valid key

GraphQL schema (SDL).

Returns the GraphQL schema as SDL (`application/graphql`). Requires any valid bearer token (any tier); the schema is not public. No scope beyond authentication.

Responses200401

Example request
curl
curl -s 'https://drug-database.com/v1/graphql' \
  -H 'Authorization: Bearer dd_live_YOUR_KEY'
POST/v1/graphqlgraphql:query

Execute a GraphQL query.

Hand-rolled GraphQL executor over the drug catalogue. Supported root query fields: `drugs`, `drug`, `drugByCode`, `atc`, `changes`, `rxnorm`. Fragments, multiple operations, directives, full introspection, mutations, and subscriptions are NOT supported. Scope: `graphql:query` (pro+).

Request body application/json — required.

Responses200400401403

Example request
curl
curl -s 'https://drug-database.com/v1/graphql' \
  -X POST \
  -H 'Authorization: Bearer dd_live_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ }'

meta

The OpenAPI document itself.

This OpenAPI 3.1 specification.

This document. Public — no authentication required.

Responses200

Example request
curl
curl -s 'https://drug-database.com/v1/openapi.json'

mcp

POST/v1/mcpany valid key

Hosted MCP server (Streamable HTTP, JSON-RPC 2.0).

The same tool catalogue as the `@drug-database/mcp-server` npm package, served at a URL so remote agents can attach. Stateless: one JSON-RPC request, or a batch of up to 20, per POST, answered as plain JSON (no stream, no session). Methods: `initialize`, `ping`, `tools/list`, `tools/call`. `initialize`, `ping` and `tools/list` are not metered; `tools/list` returns only the tools the key's scopes can run. Each `tools/call` runs the matching /v1 endpoint with the caller's key, so it is scoped, quota-checked and counted as one request. Tool results over 60,000 characters are truncated.

Request body application/json — required.

Responses200202400401

Example request
curl
curl -s 'https://drug-database.com/v1/mcp' \
  -X POST \
  -H 'Authorization: Bearer dd_live_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ }'

Conventions

A few things hold across the whole surface and are not repeated per endpoint:

  • Envelope. Responses derived from ingested registers carry _meta.sources — one entry per contributing source with last_synced_at and schema_state of ok, stale or never_run.
  • Caching. Cacheable GETs return an etag. Send it back as if-none-match to get a 304 and save your quota.
  • Enrichment freshness. Passthrough resolvers add x-drug-database-cache — db, live or stale — so you can tell a fresh upstream fetch from a cached copy served because the upstream was down.
  • Aliases. /v1/drugs/lookup and /v1/packs/{system}/{code} are the same resolver in two URL shapes, as are /v1/atc/{code} and /v1/therapies/{code}. Both stay live; pick whichever reads better in your code.