# pharmacopeia — full reference > Long-form companion to `/llms.txt`. Every public v1 endpoint, with its parameters and response schema, inlined so an LLM can answer API-usage questions without an extra fetch. Dataset snapshot: `v0.2.0-scale` (updated 2026-06-12T13:44:16.505Z). Counts: 2577 drugs, 2208 classes, 2577 ingredients, 0 interactions, 2522 indications. Base URL: `https://pharmacopeia.dev/api/v1` (path prefix `/api/v1`). ## Conventions - **Slugs are forever.** Every entity is keyed by a stable lowercase-with-hyphens slug. Slugs never change. Numeric IDs are never exposed. - **Versioned URLs.** All public routes live under `/api/v1`. Breaking changes ship as `/api/v2`. - **Zod-validated.** Request bodies and response payloads share the same Zod schemas the SDK clients and the OpenAPI document are generated from. - **Cache-Control.** `GET` responses ship `public, s-maxage=3600, stale-while-revalidate=86400` and a strong `ETag`. Honor `If-None-Match` for cheap revalidation. - **Provenance everywhere.** Every record carries a `provenance` object: `sourceUrl`, `sourceHash`, `extractedAt`, `extractor`, `confidence`. - **Jurisdiction-tagged.** Every drug carries `jurisdiction`. v0 is `US-FDA` only. - **No auth in v0.** Rate limits apply. Use `User-Agent` to identify yourself. - **Errors.** Failures return `{ "error": { "code", "message", "details?" } }` with appropriate HTTP status. `code` is one of `not_found`, `invalid_request`, `internal_error`. ## Endpoints ### `GET /api/v1/drugs` List drugs (paginated), optionally filtered by class or ingredient. Query parameters: - `limit`: number — Page size (1–200, default 50). - `offset`: number — Zero-based offset. - `class`: string — Filter to drugs in this class slug. - `ingredient`: string — Filter to drugs containing this ingredient slug. - `q`: string — Case-insensitive substring filter over name, slug, synonyms, brands, and ingredient names. - `jurisdiction`: string — Filter by regulatory jurisdiction (US-FDA, EU-EMA, UK-MHRA, CA-HC). The v0 dataset is US-FDA only. Response schema: `DrugListResponse`. Try it: https://pharmacopeia.dev/api/v1/drugs ### `GET /api/v1/drug/{slug}` Fetch a single drug by slug. Path parameters: - `slug` — string slug. Query parameters: - `fields`: string — Optional comma-separated list of sections to include (mechanism, indications, contraindications, dosing, pharmacokinetics, interactions, labelSections, approvalHistory, chemical, patientSummary). Identity fields are always returned. Omit for the full record. - `asOf`: string — Dataset time-travel: ISO-8601 instant. Records are a single newest snapshot, so this gates by extraction time — a drug extracted after this instant 404s (it was not yet in the dataset). See /drug/{slug}/history for the full change timeline. Response schema: `Drug`. Try it: https://pharmacopeia.dev/api/v1/drug/metformin ### `POST /api/v1/drugs/batch` Fetch up to 100 drug records in a single round-trip. Returns the full records found plus the slugs that did not resolve. Request body schema: `DrugsBatchRequest`. Response schema: `DrugsBatchResponse`. Try it: https://pharmacopeia.dev/api/v1/drugs/batch ### `GET /api/v1/drug/{slug}/interactions` List known interactions for a drug. Path parameters: - `slug` — string slug. Response schema: `DrugInteractionsResponse`. Try it: https://pharmacopeia.dev/api/v1/drug/metformin/interactions ### `GET /api/v1/drug/{slug}/history` Dataset time-travel: the drug's current-snapshot provenance plus its change-event timeline (newest first). Pin ?asOf= to trim the timeline to a past instant. Leans on provenance + the changelog; no separate version store. Path parameters: - `slug` — string slug. Query parameters: - `asOf`: string — ISO-8601 instant; only change events at or before it are returned, and the instant is echoed back in `asOf`. Response schema: `DrugHistoryResponse`. Try it: https://pharmacopeia.dev/api/v1/drug/metformin/history ### `GET /api/v1/drug/{slug}/similar` Structurally similar drugs (Tanimoto over 2D fingerprints). Path parameters: - `slug` — string slug. Response schema: `SimilarDrugsResponse`. Try it: https://pharmacopeia.dev/api/v1/drug/metformin/similar ### `GET /api/v1/classes` List drug classes (paginated). Query parameters: - `limit`: number — Page size (1–200, default 50). - `offset`: number — Zero-based offset. - `q`: string — Case-insensitive substring filter over name, slug, kind, and description. Response schema: `ClassListResponse`. Try it: https://pharmacopeia.dev/api/v1/classes ### `GET /api/v1/class/{slug}` Fetch a single drug class plus the drugs it contains. Path parameters: - `slug` — string slug. Response schema: `ClassDetailResponse`. Try it: https://pharmacopeia.dev/api/v1/class/metformin ### `GET /api/v1/ingredients` List active ingredients (paginated). Query parameters: - `limit`: number — Page size (1–200, default 50). - `offset`: number — Zero-based offset. - `q`: string — Case-insensitive substring filter over name, slug, and synonyms. Response schema: `IngredientListResponse`. Try it: https://pharmacopeia.dev/api/v1/ingredients ### `GET /api/v1/ingredient/{slug}` Fetch a single ingredient by slug. Path parameters: - `slug` — string slug. Response schema: `Ingredient`. Try it: https://pharmacopeia.dev/api/v1/ingredient/metformin ### `GET /api/v1/brands` Brand → generic crosswalk for every brand in the dataset. Response schema: `BrandsResponse`. Try it: https://pharmacopeia.dev/api/v1/brands ### `GET /api/v1/stats` Dataset counts and version metadata. Response schema: `Stats`. Try it: https://pharmacopeia.dev/api/v1/stats ### `GET /api/v1/health` Liveness + dataset-version probe. Tiny payload for monitors and clients. Response schema: `HealthResponse`. Try it: https://pharmacopeia.dev/api/v1/health ### `GET /api/v1/search` Full-text search across drugs, classes, and ingredients. Query parameters: - `q`: string (required) — Search query. - `limit`: number — Max results (1–50, default 10). Response schema: `SearchResponse`. Try it: https://pharmacopeia.dev/api/v1/search ### `POST /api/v1/interactions/check` Check a set of 2–20 drug slugs for pairwise interactions. Request body schema: `InteractionCheckRequest`. Response schema: `InteractionCheckResponse`. Try it: https://pharmacopeia.dev/api/v1/interactions/check ### `POST /api/v1/structure-search` Rank drugs in the dataset by 2D Tanimoto similarity to a caller-supplied SMILES. Structural proximity only. Request body schema: `StructureSearchRequest`. Response schema: `StructureSearchResponse`. Try it: https://pharmacopeia.dev/api/v1/structure-search ### `GET /api/v1/drug/{slug}/shortages` FDA shortage entries (active, resolved, discontinuation) for a drug. Reference statistics only. Path parameters: - `slug` — string slug. Response schema: `DrugShortagesResponse`. Try it: https://pharmacopeia.dev/api/v1/drug/metformin/shortages ### `GET /api/v1/shortages` Every shortage entry across the dataset, sorted by drug then presentation. Response schema: `ShortagesResponse`. Try it: https://pharmacopeia.dev/api/v1/shortages ### `GET /api/v1/drug/{slug}/adverse-events` Aggregate FAERS report counts for a drug — top reactions by reporting volume. NOT incidence rates, signals, or causality. Path parameters: - `slug` — string slug. Response schema: `AdverseEventStatsResponse`. Try it: https://pharmacopeia.dev/api/v1/drug/metformin/adverse-events ### `GET /api/v1/drug/{slug}/literature` Curated PubMed references for a drug, pinned to MeSH major topic at ingest time. Path parameters: - `slug` — string slug. Response schema: `DrugLiteratureResponse`. Try it: https://pharmacopeia.dev/api/v1/drug/metformin/literature ### `GET /api/v1/drug/{slug}/trials` ClinicalTrials.gov registrations naming the drug as an intervention — freshest sample plus total registry match count. NOT evidence of efficacy or safety. Path parameters: - `slug` — string slug. Response schema: `DrugTrialsResponse`. Try it: https://pharmacopeia.dev/api/v1/drug/metformin/trials ### `GET /api/v1/drug/{slug}/pharmacogenomics` CPIC-curated drug–gene pairs with evidence levels and guideline links. Evidence metadata only — never testing or dosing guidance. Path parameters: - `slug` — string slug. Response schema: `DrugPgxResponse`. Try it: https://pharmacopeia.dev/api/v1/drug/metformin/pharmacogenomics ### `GET /api/v1/reactions` Browse MedDRA Preferred Terms reported to FAERS across the dataset, ordered by total reporting volume. Reference statistics only — NOT a symptom checker. Query parameters: - `limit`: number — Page size (1–200, default 50). - `offset`: number — Zero-based offset. - `q`: string — Case-insensitive substring filter over the reaction term, slug, and spelling aliases. Response schema: `ReactionsListResponse`. Try it: https://pharmacopeia.dev/api/v1/reactions ### `GET /api/v1/reaction/{slug}` Fetch one MedDRA Preferred Term with its per-drug breakdown (count + share of matched FAERS reports), related reactions ranked by Jaccard similarity over the drug-id sets, and optional reference metadata — NLM MeSH descriptor id, scope note, tree position, and recent PubMed papers on the term as a MeSH major topic. Alias slugs 301-redirect to canonical. Path parameters: - `slug` — string slug. Response schema: `ReactionResponse`. Try it: https://pharmacopeia.dev/api/v1/reaction/metformin ### `GET /api/v1/conditions` Browse ICD-10-CM conditions joined to the drugs labeled for them, ordered by number of labeled drugs. A reference reverse index of labeled uses — NOT a treatment recommendation. Query parameters: - `limit`: number — Page size (1–200, default 50). - `offset`: number — Zero-based offset. - `q`: string — Case-insensitive substring filter over the condition name, slug, ICD-10 code, and chapter. Response schema: `ConditionsListResponse`. Try it: https://pharmacopeia.dev/api/v1/conditions ### `GET /api/v1/condition/{slug}` Fetch one ICD-10-CM condition with the drugs labeled for it (each carrying the verbatim indication text that produced the link) and related conditions ranked by Jaccard similarity over the drug-id sets. Path parameters: - `slug` — string slug. Response schema: `ConditionResponse`. Try it: https://pharmacopeia.dev/api/v1/condition/metformin ### `GET /api/v1/semantic-search` Meaning-based retrieval over drug-record passages. Embedding-backed when available; lexical fallback otherwise — `method` in the response reports which. Query parameters: - `q`: string (required) — Natural-language query (3–500 characters). - `limit`: number — Max passages (1–20, default 8). - `sections`: string — Optional comma-separated list of drug-record sections to search (e.g. mechanism,dosing,boxed-warning). Response schema: `SemanticSearchResponse`. Try it: https://pharmacopeia.dev/api/v1/semantic-search ### `POST /api/v1/grounded` Key-gated retrieval tier for LLM consumers: same passages as /semantic-search plus per-span citations carrying full provenance (source URL, content hash, extraction timestamp, confidence). Request body schema: `GroundedRequest`. Response schema: `GroundedResponse`. Try it: https://pharmacopeia.dev/api/v1/grounded ### `GET /api/v1/webhooks` List the webhook endpoints registered by the calling API key. Response schema: `WebhooksListResponse`. Try it: https://pharmacopeia.dev/api/v1/webhooks ### `POST /api/v1/webhooks` Register a webhook endpoint. The response includes the HMAC signing secret exactly once — store it. Request body schema: `WebhookCreateRequest`. Response schema: `WebhookEndpointCreated`. Try it: https://pharmacopeia.dev/api/v1/webhooks ### `DELETE /api/v1/webhooks/{id}` Delete a webhook endpoint owned by the calling API key. Path parameters: - `id` — string slug. Response schema: `WebhookDeleteResponse`. Try it: https://pharmacopeia.dev/api/v1/webhooks/{id} ### `GET /api/v1/changelog` Recent record-level changes (typed mirror of /feed.xml and /feed.json). Query parameters: - `limit`: number — Max entries (1–200, default 50). - `since`: string — ISO-8601 timestamp; only entries strictly after this are returned. Response schema: `ChangelogResponse`. Try it: https://pharmacopeia.dev/api/v1/changelog ## Machine-readable specs - OpenAPI 3.1: https://pharmacopeia.dev/api/v1/openapi.json - Interactive reference (Scalar): https://pharmacopeia.dev/reference - Health probe: https://pharmacopeia.dev/api/v1/health - Stats: https://pharmacopeia.dev/api/v1/stats ## Browsable reference pages - Docs: https://pharmacopeia.dev/docs - Drugs: https://pharmacopeia.dev/drugs - Classes: https://pharmacopeia.dev/classes - Ingredients: https://pharmacopeia.dev/ingredients - Brands: https://pharmacopeia.dev/brands - ATC explorer: https://pharmacopeia.dev/atc - Interactions: https://pharmacopeia.dev/interactions - Mechanism graph: https://pharmacopeia.dev/moa - FAQ: https://pharmacopeia.dev/faq - Glossary: https://pharmacopeia.dev/glossary - Roadmap: https://pharmacopeia.dev/roadmap ## Disclaimer pharmacopeia is for educational and informational use only. It is **not** medical advice, a diagnosis, a treatment recommendation, a clinical decision-support tool, or a substitute for consultation with a qualified clinician. Always verify against the canonical `provenance.sourceUrl` before acting on any field.