# pharmacopeia

> Developer-first JSON reference API for medications. Stable slugs, versioned routes, per-record provenance, and Zod-validated payloads. Educational / informational use only — never a clinical or decision-support tool.

Dataset snapshot `v0.2.0-scale` (updated 2026-06-12T13:44:16.505Z). 2577 drugs, 2208 classes, 2577 ingredients, 0 interactions, 2522 indications.

Conventions:

- Every entity is keyed by a stable lowercase-with-hyphens slug. Slugs never change.
- All public routes live under `/api/v1`. Breaking changes ship as `/api/v2`.
- Responses are `application/json; charset=utf-8` and validated against the same Zod schemas at runtime.
- `GET` responses ship `Cache-Control: public, s-maxage=3600, stale-while-revalidate=86400` and a strong `ETag`. Clients can revalidate with `If-None-Match` for `304 Not Modified`.
- Every record carries a `provenance` object (`sourceUrl`, `sourceHash`, `extractedAt`, `extractor`, `confidence`).

## Machine-readable surfaces

- [OpenAPI 3.1 document](https://pharmacopeia.dev/api/v1/openapi.json): the source of truth for endpoints, parameters, and response schemas
- [Interactive API reference](https://pharmacopeia.dev/reference): Scalar-rendered, try-it browser over the OpenAPI spec
- [Health & dataset version](https://pharmacopeia.dev/api/v1/health): tiny liveness + snapshot version envelope
- [Dataset stats](https://pharmacopeia.dev/api/v1/stats): counts and current snapshot version
- [Long-form llms file](https://pharmacopeia.dev/llms-full.txt): fuller index with every endpoint and its description inlined

## Core API endpoints

- [GET /api/v1/drugs](https://pharmacopeia.dev/api/v1/drugs): list drugs (paginated; filter by `?class=`, `?ingredient=`)
- [GET /api/v1/drug/{slug}](https://pharmacopeia.dev/api/v1/drug/metformin): full drug record (mechanism, indications, label sections, identifiers, provenance)
- [GET /api/v1/drug/{slug}/interactions](https://pharmacopeia.dev/api/v1/drug/metformin/interactions): all known interactions for a drug
- [GET /api/v1/drug/{slug}/similar](https://pharmacopeia.dev/api/v1/drug/metformin/similar): structurally similar drugs (Tanimoto over 2D fingerprints)
- [GET /api/v1/classes](https://pharmacopeia.dev/api/v1/classes): list pharmacological classes (ATC, EPC, MoA, MeSH)
- [GET /api/v1/class/{slug}](https://pharmacopeia.dev/api/v1/class/biguanides): class detail + drugs in the class
- [GET /api/v1/ingredients](https://pharmacopeia.dev/api/v1/ingredients): list active ingredients with chemistry identifiers
- [GET /api/v1/ingredient/{slug}](https://pharmacopeia.dev/api/v1/ingredient/metformin-hydrochloride): ingredient detail (RxCUI, UNII, SMILES, InChIKey)
- [GET /api/v1/brands](https://pharmacopeia.dev/api/v1/brands): brand → generic crosswalk
- [GET /api/v1/atc](https://pharmacopeia.dev/api/v1/atc): WHO ATC hierarchy as a nested tree (levels 1–5)
- [GET /api/v1/mechanisms/graph](https://pharmacopeia.dev/api/v1/mechanisms/graph): drug ↔ MoA ↔ molecular target graph
- [GET /api/v1/search?q=...](https://pharmacopeia.dev/api/v1/search?q=blood+thinner): full-text search across drugs, classes, ingredients
- [POST /api/v1/interactions/check](https://pharmacopeia.dev/api/v1/interactions/check): pairwise interaction check; body `{ drugs: string[] }`

## Browsable reference (HTML)

- [Docs](https://pharmacopeia.dev/docs): endpoint reference + conventions + indicator legend
- [Methodology](https://pharmacopeia.dev/methodology): data sources, provenance model, review process, and limitations
- [Drugs](https://pharmacopeia.dev/drugs)
- [Classes](https://pharmacopeia.dev/classes)
- [Ingredients](https://pharmacopeia.dev/ingredients)
- [Brands](https://pharmacopeia.dev/brands)
- [Conditions](https://pharmacopeia.dev/conditions): ICD-10-CM concepts → drugs labeled for them
- [ATC explorer](https://pharmacopeia.dev/atc)
- [Interactions](https://pharmacopeia.dev/interactions)
- [Compare drugs](https://pharmacopeia.dev/compare/atorvastatin-vs-rosuvastatin): side-by-side drug-vs-drug contrasts at /compare/{a}-vs-{b} (slugs in alphabetical order)
- [FAQ](https://pharmacopeia.dev/faq)
- [Glossary](https://pharmacopeia.dev/glossary)
- [Roadmap](https://pharmacopeia.dev/roadmap)

## SDKs

- TypeScript and Python clients are generated from the same Zod schemas the API validates against. See `sdk/` in the source repository.

## Optional

- This project is **not** a clinical decision-support tool, EHR/FHIR layer, symptom checker, diagnostic API, or a wrapper around paid feeds. Always verify against the canonical `provenance.sourceUrl` before acting on any field.