{ "openapi": "3.1.0", "info": { "title": "pharmacopeia API", "version": "v1", "description": "Developer-first reference API for medications. Educational / informational use only.\n\nAll GET responses are cached at the edge (`Cache-Control: public, s-maxage=3600, stale-while-revalidate=86400`) and ship a strong `ETag`. Clients can revalidate with `If-None-Match` and receive `304 Not Modified` on a hit." }, "servers": [ { "url": "https://pharmacopeia.dev" } ], "tags": [ { "name": "Drugs", "description": "Browse, fetch, and explore drugs. Includes per-drug interactions and structural neighbours." }, { "name": "Classes", "description": "RxClass-style drug classes (FDA EPC, WHO ATC, MoA, MeSH) and their members." }, { "name": "Ingredients", "description": "Active ingredients, the building blocks shared across drugs." }, { "name": "Brands", "description": "Brand → generic crosswalk across the dataset." }, { "name": "Search", "description": "Lookup by name or by 2D chemical structure (SMILES Tanimoto)." }, { "name": "Interactions", "description": "Multi-drug interaction checks. Severity-graded, with mechanism and source." }, { "name": "Shortages", "description": "FDA drug-shortage status crosswalk. Reference statistics only — for live status, consult the FDA shortages database directly." }, { "name": "AdverseEvents", "description": "Aggregate FAERS adverse-event report counts. Counts are reporting volume, NOT incidence rates, signals, or causality. Reference statistics only." }, { "name": "Reactions", "description": "MedDRA Preferred Terms reported to FAERS, transposed across the dataset. Each reaction lists the drugs that report it most, ranked by share of the drug's matched reports, plus related reactions by Jaccard similarity. Reference statistics only — NOT a symptom checker, NOT diagnostic." }, { "name": "Conditions", "description": "ICD-10-CM concepts joined to the drugs whose labeled indications map to them, via a conservative public-domain crosswalk. Each condition lists the drugs labeled for it (with the verbatim indication text) and related conditions by Jaccard similarity. A reference reverse index of labeled uses — NOT a treatment recommendation, formulary, or clinical guidance." }, { "name": "Literature", "description": "PubMed PMID crosswalks. Link drug records to canonical literature in PubMed." }, { "name": "Trials", "description": "ClinicalTrials.gov crosswalks. Registered studies naming a drug as an intervention, plus the registry's total match count. Registration is NOT evidence of efficacy or safety — reference crosswalk only." }, { "name": "Pharmacogenomics", "description": "CPIC-curated drug–gene pairs with evidence levels (CPIC A–D, ClinPGx 1A–4), FDA-label PGx annotations, and guideline links. Evidence metadata only — never testing or dosing guidance." }, { "name": "Retrieval", "description": "Meaning-based retrieval over drug-record passages. `/semantic-search` is free; `/grounded` is the key-gated tier that adds per-span citations with full provenance for LLM consumers." }, { "name": "Changelog", "description": "Record-level change feed. Typed mirror of `/feed.xml` and `/feed.json`." }, { "name": "Webhooks", "description": "Outbound webhooks on dataset changes. Deliveries are HMAC-SHA256 signed (`X-Pharmacopeia-Signature: t=,v1=` over `.`). Requires an API key." }, { "name": "System", "description": "Liveness, dataset counts, and version metadata." } ], "paths": { "/api/v1/drugs": { "get": { "operationId": "listDrugs", "summary": "List drugs (paginated), optionally filtered by class or ingredient.", "tags": [ "Drugs" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DrugListResponse" } } } }, "304": { "description": "Not Modified — the resource has not changed since the ETag in `If-None-Match`." }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size (1–200, default 50).", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based offset.", "schema": { "type": "integer" } }, { "name": "class", "in": "query", "required": false, "description": "Filter to drugs in this class slug.", "schema": { "type": "string" } }, { "name": "ingredient", "in": "query", "required": false, "description": "Filter to drugs containing this ingredient slug.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "description": "Case-insensitive substring filter over name, slug, synonyms, brands, and ingredient names.", "schema": { "type": "string" } }, { "name": "jurisdiction", "in": "query", "required": false, "description": "Filter by regulatory jurisdiction (US-FDA, EU-EMA, UK-MHRA, CA-HC). The v0 dataset is US-FDA only.", "schema": { "type": "string" } } ] } }, "/api/v1/drug/{slug}": { "get": { "operationId": "getDrug", "summary": "Fetch a single drug by slug.", "tags": [ "Drugs" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Drug" } } } }, "304": { "description": "Not Modified — the resource has not changed since the ETag in `If-None-Match`." }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "fields", "in": "query", "required": false, "description": "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.", "schema": { "type": "string" } }, { "name": "asOf", "in": "query", "required": false, "description": "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.", "schema": { "type": "string" } } ] } }, "/api/v1/drugs/batch": { "post": { "operationId": "getDrugsBatch", "summary": "Fetch up to 100 drug records in a single round-trip. Returns the full records found plus the slugs that did not resolve.", "tags": [ "Drugs" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DrugsBatchResponse" } } } }, "304": { "description": "Not Modified — the resource has not changed since the ETag in `If-None-Match`." }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DrugsBatchRequest" } } } } } }, "/api/v1/drug/{slug}/interactions": { "get": { "operationId": "getDrugInteractions", "summary": "List known interactions for a drug.", "tags": [ "Drugs" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DrugInteractionsResponse" } } } }, "304": { "description": "Not Modified — the resource has not changed since the ETag in `If-None-Match`." }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/drug/{slug}/history": { "get": { "operationId": "getDrugHistory", "summary": "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.", "tags": [ "Drugs" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DrugHistoryResponse" } } } }, "304": { "description": "Not Modified — the resource has not changed since the ETag in `If-None-Match`." }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "asOf", "in": "query", "required": false, "description": "ISO-8601 instant; only change events at or before it are returned, and the instant is echoed back in `asOf`.", "schema": { "type": "string" } } ] } }, "/api/v1/drug/{slug}/similar": { "get": { "operationId": "getSimilarDrugs", "summary": "Structurally similar drugs (Tanimoto over 2D fingerprints).", "tags": [ "Drugs" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimilarDrugsResponse" } } } }, "304": { "description": "Not Modified — the resource has not changed since the ETag in `If-None-Match`." }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/classes": { "get": { "operationId": "listClasses", "summary": "List drug classes (paginated).", "tags": [ "Classes" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClassListResponse" } } } }, "304": { "description": "Not Modified — the resource has not changed since the ETag in `If-None-Match`." }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size (1–200, default 50).", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based offset.", "schema": { "type": "integer" } }, { "name": "q", "in": "query", "required": false, "description": "Case-insensitive substring filter over name, slug, kind, and description.", "schema": { "type": "string" } } ] } }, "/api/v1/class/{slug}": { "get": { "operationId": "getClass", "summary": "Fetch a single drug class plus the drugs it contains.", "tags": [ "Classes" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClassDetailResponse" } } } }, "304": { "description": "Not Modified — the resource has not changed since the ETag in `If-None-Match`." }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/ingredients": { "get": { "operationId": "listIngredients", "summary": "List active ingredients (paginated).", "tags": [ "Ingredients" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IngredientListResponse" } } } }, "304": { "description": "Not Modified — the resource has not changed since the ETag in `If-None-Match`." }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size (1–200, default 50).", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based offset.", "schema": { "type": "integer" } }, { "name": "q", "in": "query", "required": false, "description": "Case-insensitive substring filter over name, slug, and synonyms.", "schema": { "type": "string" } } ] } }, "/api/v1/ingredient/{slug}": { "get": { "operationId": "getIngredient", "summary": "Fetch a single ingredient by slug.", "tags": [ "Ingredients" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ingredient" } } } }, "304": { "description": "Not Modified — the resource has not changed since the ETag in `If-None-Match`." }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/brands": { "get": { "operationId": "listBrands", "summary": "Brand → generic crosswalk for every brand in the dataset.", "tags": [ "Brands" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandsResponse" } } } }, "304": { "description": "Not Modified — the resource has not changed since the ETag in `If-None-Match`." }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/stats": { "get": { "operationId": "getStats", "summary": "Dataset counts and version metadata.", "tags": [ "System" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Stats" } } } }, "304": { "description": "Not Modified — the resource has not changed since the ETag in `If-None-Match`." }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/health": { "get": { "operationId": "getHealth", "summary": "Liveness + dataset-version probe. Tiny payload for monitors and clients.", "tags": [ "System" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } } }, "304": { "description": "Not Modified — the resource has not changed since the ETag in `If-None-Match`." }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/search": { "get": { "operationId": "search", "summary": "Full-text search across drugs, classes, and ingredients.", "tags": [ "Search" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } } }, "304": { "description": "Not Modified — the resource has not changed since the ETag in `If-None-Match`." }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Search query.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Max results (1–50, default 10).", "schema": { "type": "integer" } } ] } }, "/api/v1/interactions/check": { "post": { "operationId": "checkInteractions", "summary": "Check a set of 2–20 drug slugs for pairwise interactions.", "tags": [ "Interactions" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InteractionCheckResponse" } } } }, "304": { "description": "Not Modified — the resource has not changed since the ETag in `If-None-Match`." }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InteractionCheckRequest" } } } } } }, "/api/v1/structure-search": { "post": { "operationId": "structureSearch", "summary": "Rank drugs in the dataset by 2D Tanimoto similarity to a caller-supplied SMILES. Structural proximity only.", "tags": [ "Search" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StructureSearchResponse" } } } }, "304": { "description": "Not Modified — the resource has not changed since the ETag in `If-None-Match`." }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StructureSearchRequest" } } } } } }, "/api/v1/drug/{slug}/shortages": { "get": { "operationId": "getDrugShortages", "summary": "FDA shortage entries (active, resolved, discontinuation) for a drug. Reference statistics only.", "tags": [ "Shortages" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DrugShortagesResponse" } } } }, "304": { "description": "Not Modified — the resource has not changed since the ETag in `If-None-Match`." }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/shortages": { "get": { "operationId": "listShortages", "summary": "Every shortage entry across the dataset, sorted by drug then presentation.", "tags": [ "Shortages" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShortagesResponse" } } } }, "304": { "description": "Not Modified — the resource has not changed since the ETag in `If-None-Match`." }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/drug/{slug}/adverse-events": { "get": { "operationId": "getDrugAdverseEvents", "summary": "Aggregate FAERS report counts for a drug — top reactions by reporting volume. NOT incidence rates, signals, or causality.", "tags": [ "AdverseEvents" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdverseEventStatsResponse" } } } }, "304": { "description": "Not Modified — the resource has not changed since the ETag in `If-None-Match`." }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/drug/{slug}/literature": { "get": { "operationId": "getDrugLiterature", "summary": "Curated PubMed references for a drug, pinned to MeSH major topic at ingest time.", "tags": [ "Literature" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DrugLiteratureResponse" } } } }, "304": { "description": "Not Modified — the resource has not changed since the ETag in `If-None-Match`." }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/drug/{slug}/trials": { "get": { "operationId": "getDrugTrials", "summary": "ClinicalTrials.gov registrations naming the drug as an intervention — freshest sample plus total registry match count. NOT evidence of efficacy or safety.", "tags": [ "Trials" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DrugTrialsResponse" } } } }, "304": { "description": "Not Modified — the resource has not changed since the ETag in `If-None-Match`." }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/drug/{slug}/pharmacogenomics": { "get": { "operationId": "getDrugPharmacogenomics", "summary": "CPIC-curated drug–gene pairs with evidence levels and guideline links. Evidence metadata only — never testing or dosing guidance.", "tags": [ "Pharmacogenomics" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DrugPgxResponse" } } } }, "304": { "description": "Not Modified — the resource has not changed since the ETag in `If-None-Match`." }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/reactions": { "get": { "operationId": "listReactions", "summary": "Browse MedDRA Preferred Terms reported to FAERS across the dataset, ordered by total reporting volume. Reference statistics only — NOT a symptom checker.", "tags": [ "Reactions" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReactionsListResponse" } } } }, "304": { "description": "Not Modified — the resource has not changed since the ETag in `If-None-Match`." }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size (1–200, default 50).", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based offset.", "schema": { "type": "integer" } }, { "name": "q", "in": "query", "required": false, "description": "Case-insensitive substring filter over the reaction term, slug, and spelling aliases.", "schema": { "type": "string" } } ] } }, "/api/v1/reaction/{slug}": { "get": { "operationId": "getReaction", "summary": "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.", "tags": [ "Reactions" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReactionResponse" } } } }, "304": { "description": "Not Modified — the resource has not changed since the ETag in `If-None-Match`." }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/conditions": { "get": { "operationId": "listConditions", "summary": "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.", "tags": [ "Conditions" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConditionsListResponse" } } } }, "304": { "description": "Not Modified — the resource has not changed since the ETag in `If-None-Match`." }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size (1–200, default 50).", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based offset.", "schema": { "type": "integer" } }, { "name": "q", "in": "query", "required": false, "description": "Case-insensitive substring filter over the condition name, slug, ICD-10 code, and chapter.", "schema": { "type": "string" } } ] } }, "/api/v1/condition/{slug}": { "get": { "operationId": "getCondition", "summary": "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.", "tags": [ "Conditions" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConditionResponse" } } } }, "304": { "description": "Not Modified — the resource has not changed since the ETag in `If-None-Match`." }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/semantic-search": { "get": { "operationId": "semanticSearch", "summary": "Meaning-based retrieval over drug-record passages. Embedding-backed when available; lexical fallback otherwise — `method` in the response reports which.", "tags": [ "Retrieval" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SemanticSearchResponse" } } } }, "304": { "description": "Not Modified — the resource has not changed since the ETag in `If-None-Match`." }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Natural-language query (3–500 characters).", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Max passages (1–20, default 8).", "schema": { "type": "integer" } }, { "name": "sections", "in": "query", "required": false, "description": "Optional comma-separated list of drug-record sections to search (e.g. mechanism,dosing,boxed-warning).", "schema": { "type": "string" } } ] } }, "/api/v1/grounded": { "post": { "operationId": "groundedRetrieval", "summary": "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).", "tags": [ "Retrieval" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroundedResponse" } } } }, "304": { "description": "Not Modified — the resource has not changed since the ETag in `If-None-Match`." }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroundedRequest" } } } } } }, "/api/v1/webhooks": { "get": { "operationId": "listWebhooks", "summary": "List the webhook endpoints registered by the calling API key.", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhooksListResponse" } } } }, "304": { "description": "Not Modified — the resource has not changed since the ETag in `If-None-Match`." }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "operationId": "createWebhook", "summary": "Register a webhook endpoint. The response includes the HMAC signing secret exactly once — store it.", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointCreated" } } } }, "304": { "description": "Not Modified — the resource has not changed since the ETag in `If-None-Match`." }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreateRequest" } } } } } }, "/api/v1/webhooks/{id}": { "delete": { "operationId": "deleteWebhook", "summary": "Delete a webhook endpoint owned by the calling API key.", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeleteResponse" } } } }, "304": { "description": "Not Modified — the resource has not changed since the ETag in `If-None-Match`." }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/changelog": { "get": { "operationId": "listChangelog", "summary": "Recent record-level changes (typed mirror of /feed.xml and /feed.json).", "tags": [ "Changelog" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangelogResponse" } } } }, "304": { "description": "Not Modified — the resource has not changed since the ETag in `If-None-Match`." }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Max entries (1–200, default 50).", "schema": { "type": "integer" } }, { "name": "since", "in": "query", "required": false, "description": "ISO-8601 timestamp; only entries strictly after this are returned.", "schema": { "type": "string" } } ] } } }, "components": { "schemas": { "Jurisdiction": { "type": "string", "enum": [ "US-FDA", "EU-EMA", "UK-MHRA", "CA-HC" ] }, "Severity": { "type": "string", "enum": [ "contraindicated", "major", "moderate", "minor", "unknown" ] }, "DeaSchedule": { "type": "string", "enum": [ "I", "II", "III", "IV", "V" ] }, "DrugClassKind": { "type": "string", "enum": [ "atc", "moa", "epc", "pe", "pharm", "mesh" ] }, "Provenance": { "type": "object", "properties": { "sourceUrl": { "type": "string", "format": "uri" }, "sourceHash": { "type": "string", "minLength": 1 }, "extractedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "extractor": { "type": "string", "minLength": 1, "pattern": "^[a-z][a-z0-9-]*(@[a-z0-9.-]+)?$" }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "sourceUrl", "sourceHash", "extractedAt", "extractor", "confidence" ], "additionalProperties": false }, "Pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "offset": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "total", "limit", "offset" ], "additionalProperties": false }, "ApiError": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "not_found", "invalid_request", "unauthorized", "forbidden", "rate_limited", "not_configured", "internal_error" ] }, "message": { "type": "string" }, "details": {} }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false }, "DrugRef": { "type": "object", "properties": { "slug": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9][a-z0-9-]*$" }, "name": { "type": "string" } }, "required": [ "slug", "name" ], "additionalProperties": false }, "Indication": { "type": "object", "properties": { "text": { "type": "string" }, "icd10": { "default": [], "type": "array", "items": { "type": "string" } }, "snomed": { "default": [], "type": "array", "items": { "type": "string" } } }, "required": [ "text", "icd10", "snomed" ], "additionalProperties": false }, "Contraindication": { "type": "object", "properties": { "text": { "type": "string" }, "severity": { "$ref": "#/components/schemas/Severity" } }, "required": [ "text", "severity" ], "additionalProperties": false }, "Dosing": { "type": "object", "properties": { "route": { "type": "string", "enum": [ "oral", "iv", "im", "subcutaneous", "topical", "inhaled", "intranasal", "rectal", "ophthalmic", "otic", "transdermal", "other" ] }, "population": { "type": "string", "enum": [ "adult", "pediatric", "geriatric", "renal-impairment", "hepatic-impairment", "pregnancy" ] }, "condition": { "type": "string" }, "dose": { "type": "string" }, "frequency": { "type": "string" }, "maxDose": { "type": "string" }, "notes": { "type": "string" } }, "required": [ "route", "population", "dose" ], "additionalProperties": false }, "Pharmacokinetics": { "type": "object", "properties": { "halfLife": { "type": "string" }, "tMax": { "type": "string" }, "bioavailability": { "type": "string" }, "proteinBinding": { "type": "string" }, "metabolism": { "type": "string" }, "excretion": { "type": "string" } }, "additionalProperties": false }, "Mechanism": { "type": "object", "properties": { "summary": { "type": "string" }, "targets": { "default": [], "type": "array", "items": { "type": "string" } } }, "required": [ "summary", "targets" ], "additionalProperties": false }, "Approval": { "type": "object", "properties": { "date": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, "applicationNumber": { "type": "string" }, "type": { "type": "string", "enum": [ "NDA", "ANDA", "BLA", "OTC" ] }, "sponsor": { "type": "string" } }, "required": [ "date", "applicationNumber", "type" ], "additionalProperties": false }, "LabelSections": { "type": "object", "properties": { "boxedWarning": { "type": "string" }, "dosageAndAdministration": { "type": "string" }, "warningsAndPrecautions": { "type": "string" }, "adverseReactions": { "type": "string" }, "useInSpecificPopulations": { "type": "string" }, "overdosage": { "type": "string" } }, "additionalProperties": false }, "ControlledSubstance": { "type": "object", "properties": { "schedule": { "$ref": "#/components/schemas/DeaSchedule" }, "narcotic": { "type": "boolean" }, "description": { "type": "string" } }, "required": [ "schedule", "description" ], "additionalProperties": false }, "OrangeBook": { "type": "object", "properties": { "teCode": { "type": "string" }, "referenceListed": { "type": "boolean" }, "genericAvailable": { "type": "boolean" }, "description": { "type": "string" } }, "required": [ "genericAvailable", "description" ], "additionalProperties": false }, "Identifier": { "type": "object", "properties": { "rxcui": { "type": "string" }, "ndc": { "default": [], "type": "array", "items": { "type": "string" } }, "atc": { "default": [], "type": "array", "items": { "type": "string" } }, "drugbank": { "type": "string" }, "chembl": { "type": "string" }, "pubchem": { "type": "string" }, "unii": { "type": "string" } }, "required": [ "ndc", "atc" ], "additionalProperties": false }, "ChemicalStructure": { "type": "object", "properties": { "smiles": { "type": "string", "minLength": 1 }, "inchiKey": { "type": "string" }, "iupacName": { "type": "string" }, "pubchemCid": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "structureSvgPath": { "type": "string", "pattern": "^\\/structures\\/[a-z0-9-]+\\.svg$" }, "provenance": { "$ref": "#/components/schemas/Provenance" } }, "required": [ "smiles", "structureSvgPath", "provenance" ], "additionalProperties": false }, "DrugClassRef": { "type": "object", "properties": { "slug": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9][a-z0-9-]*$" }, "name": { "type": "string" }, "kind": { "$ref": "#/components/schemas/DrugClassKind" }, "code": { "type": "string" } }, "required": [ "slug", "name", "kind" ], "additionalProperties": false }, "DrugClassParent": { "type": "object", "properties": { "slug": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9][a-z0-9-]*$" }, "name": { "type": "string" } }, "required": [ "slug", "name" ], "additionalProperties": false }, "DrugClass": { "type": "object", "properties": { "slug": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9][a-z0-9-]*$" }, "name": { "type": "string" }, "kind": { "$ref": "#/components/schemas/DrugClassKind" }, "code": { "type": "string" }, "description": { "type": "string" }, "parent": { "anyOf": [ { "$ref": "#/components/schemas/DrugClassParent" }, { "type": "null" } ] }, "drugCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "provenance": { "$ref": "#/components/schemas/Provenance" } }, "required": [ "slug", "name", "kind", "drugCount", "provenance" ], "additionalProperties": false }, "IngredientRef": { "type": "object", "properties": { "slug": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9][a-z0-9-]*$" }, "name": { "type": "string" }, "strength": { "type": "string" } }, "required": [ "slug", "name" ], "additionalProperties": false }, "Ingredient": { "type": "object", "properties": { "slug": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9][a-z0-9-]*$" }, "name": { "type": "string" }, "synonyms": { "default": [], "type": "array", "items": { "type": "string" } }, "rxcui": { "type": "string" }, "unii": { "type": "string" }, "smiles": { "type": "string" }, "inchikey": { "type": "string" }, "molecularFormula": { "type": "string" }, "molecularWeight": { "type": "number", "exclusiveMinimum": 0 }, "drugCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "provenance": { "$ref": "#/components/schemas/Provenance" } }, "required": [ "slug", "name", "synonyms", "drugCount", "provenance" ], "additionalProperties": false }, "DrugSummary": { "type": "object", "properties": { "slug": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9][a-z0-9-]*$" }, "name": { "type": "string" }, "synonyms": { "default": [], "type": "array", "items": { "type": "string" } }, "jurisdiction": { "$ref": "#/components/schemas/Jurisdiction" }, "ingredients": { "type": "array", "items": { "$ref": "#/components/schemas/IngredientRef" } }, "brands": { "default": [], "type": "array", "items": { "type": "string" } }, "classes": { "default": [], "type": "array", "items": { "$ref": "#/components/schemas/DrugClassRef" } }, "shortDescription": { "type": "string" } }, "required": [ "slug", "name", "synonyms", "jurisdiction", "ingredients", "brands", "classes" ], "additionalProperties": false }, "Drug": { "type": "object", "properties": { "slug": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9][a-z0-9-]*$" }, "name": { "type": "string" }, "synonyms": { "default": [], "type": "array", "items": { "type": "string" } }, "jurisdiction": { "$ref": "#/components/schemas/Jurisdiction" }, "ingredients": { "type": "array", "items": { "$ref": "#/components/schemas/IngredientRef" } }, "brands": { "default": [], "type": "array", "items": { "type": "string" } }, "classes": { "default": [], "type": "array", "items": { "$ref": "#/components/schemas/DrugClassRef" } }, "shortDescription": { "type": "string" }, "mechanism": { "$ref": "#/components/schemas/Mechanism" }, "indications": { "default": [], "type": "array", "items": { "$ref": "#/components/schemas/Indication" } }, "contraindications": { "default": [], "type": "array", "items": { "$ref": "#/components/schemas/Contraindication" } }, "dosing": { "default": [], "type": "array", "items": { "$ref": "#/components/schemas/Dosing" } }, "pharmacokinetics": { "$ref": "#/components/schemas/Pharmacokinetics" }, "approvalHistory": { "default": [], "type": "array", "items": { "$ref": "#/components/schemas/Approval" } }, "patientSummary": { "type": "string" }, "interactionsNarrative": { "type": "string" }, "labelSections": { "$ref": "#/components/schemas/LabelSections" }, "controlledSubstance": { "$ref": "#/components/schemas/ControlledSubstance" }, "orangeBook": { "$ref": "#/components/schemas/OrangeBook" }, "identifiers": { "$ref": "#/components/schemas/Identifier" }, "chemical": { "$ref": "#/components/schemas/ChemicalStructure" }, "provenance": { "$ref": "#/components/schemas/Provenance" } }, "required": [ "slug", "name", "synonyms", "jurisdiction", "ingredients", "brands", "classes", "indications", "contraindications", "dosing", "approvalHistory", "identifiers", "provenance" ], "additionalProperties": false }, "DrugsBatchRequest": { "type": "object", "properties": { "slugs": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9][a-z0-9-]*$" } } }, "required": [ "slugs" ], "additionalProperties": false }, "DrugsBatchResponse": { "type": "object", "properties": { "found": { "type": "array", "items": { "$ref": "#/components/schemas/Drug" } }, "missing": { "type": "array", "items": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9][a-z0-9-]*$" } }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "found", "missing", "total" ], "additionalProperties": false }, "Interaction": { "type": "object", "properties": { "drugA": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9][a-z0-9-]*$" }, "drugB": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9][a-z0-9-]*$" }, "severity": { "$ref": "#/components/schemas/Severity" }, "mechanism": { "type": "string" }, "description": { "type": "string" }, "recommendation": { "type": "string" }, "evidenceSpan": { "type": "string" }, "provenance": { "$ref": "#/components/schemas/Provenance" } }, "required": [ "drugA", "drugB", "severity", "description", "provenance" ], "additionalProperties": false }, "InteractionSummary": { "type": "object", "properties": { "contraindicated": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "major": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "moderate": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "minor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "unknown": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "contraindicated", "major", "moderate", "minor", "unknown" ], "additionalProperties": false }, "InteractionCheckRequest": { "type": "object", "properties": { "drugs": { "minItems": 2, "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9][a-z0-9-]*$" } } }, "required": [ "drugs" ], "additionalProperties": false }, "InteractionCheckResponse": { "type": "object", "properties": { "input": { "type": "array", "items": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9][a-z0-9-]*$" } }, "pairs": { "type": "array", "items": { "$ref": "#/components/schemas/Interaction" } }, "summary": { "$ref": "#/components/schemas/InteractionSummary" } }, "required": [ "input", "pairs", "summary" ], "additionalProperties": false }, "Stats": { "type": "object", "properties": { "drugs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "classes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "ingredients": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "interactions": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "indications": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "version": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "drugs", "classes", "ingredients", "interactions", "indications", "version", "updatedAt" ], "additionalProperties": false }, "HealthResponse": { "type": "object", "properties": { "status": { "type": "string", "const": "ok" }, "version": { "type": "string" }, "updatedAt": { "type": "string" }, "time": { "type": "string" }, "uptime": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "repository": { "type": "string", "enum": [ "static", "supabase" ] }, "commit": { "type": "string" }, "region": { "type": "string" } }, "required": [ "status", "version", "updatedAt", "time", "repository" ], "additionalProperties": false }, "SimilarDrugResult": { "type": "object", "properties": { "slug": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9][a-z0-9-]*$" }, "name": { "type": "string" }, "score": { "type": "number" }, "className": { "type": "string" } }, "required": [ "slug", "name", "score" ], "additionalProperties": false }, "BrandEntry": { "type": "object", "properties": { "brand": { "type": "string" }, "drugs": { "type": "array", "items": { "$ref": "#/components/schemas/DrugRef" } } }, "required": [ "brand", "drugs" ], "additionalProperties": false }, "SearchResult": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "drug", "ingredient", "class" ] }, "description": { "type": "string" } }, "required": [ "slug", "name", "kind" ], "additionalProperties": false }, "DrugListResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/DrugSummary" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": [ "items", "pagination" ], "additionalProperties": false }, "ClassListResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/DrugClass" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": [ "items", "pagination" ], "additionalProperties": false }, "IngredientListResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Ingredient" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": [ "items", "pagination" ], "additionalProperties": false }, "DrugInteractionsResponse": { "type": "object", "properties": { "drug": { "$ref": "#/components/schemas/DrugRef" }, "interactions": { "type": "array", "items": { "$ref": "#/components/schemas/Interaction" } }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "drug", "interactions", "total" ], "additionalProperties": false }, "SimilarDrugsResponse": { "type": "object", "properties": { "drug": { "$ref": "#/components/schemas/DrugRef" }, "method": { "type": "string", "const": "tanimoto-2d-fingerprint" }, "similar": { "type": "array", "items": { "$ref": "#/components/schemas/SimilarDrugResult" } }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "drug", "method", "similar", "total" ], "additionalProperties": false }, "ClassDetailResponse": { "type": "object", "properties": { "slug": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9][a-z0-9-]*$" }, "name": { "type": "string" }, "kind": { "$ref": "#/components/schemas/DrugClassKind" }, "code": { "type": "string" }, "description": { "type": "string" }, "parent": { "anyOf": [ { "$ref": "#/components/schemas/DrugClassParent" }, { "type": "null" } ] }, "drugCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "provenance": { "$ref": "#/components/schemas/Provenance" }, "drugs": { "type": "array", "items": { "$ref": "#/components/schemas/DrugSummary" } } }, "required": [ "slug", "name", "kind", "drugCount", "provenance", "drugs" ], "additionalProperties": false }, "BrandsResponse": { "type": "object", "properties": { "brands": { "type": "array", "items": { "$ref": "#/components/schemas/BrandEntry" } }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "brands", "total" ], "additionalProperties": false }, "SearchResponse": { "type": "object", "properties": { "query": { "type": "string" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/SearchResult" } }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "query", "results", "total" ], "additionalProperties": false }, "StructureMatch": { "type": "object", "properties": { "slug": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9][a-z0-9-]*$" }, "name": { "type": "string" }, "score": { "type": "number" }, "className": { "type": "string" }, "smiles": { "type": "string" } }, "required": [ "slug", "name", "score", "smiles" ], "additionalProperties": false }, "StructureSearchRequest": { "type": "object", "properties": { "smiles": { "type": "string", "minLength": 1, "maxLength": 2000 }, "limit": { "default": 10, "type": "integer", "minimum": 1, "maximum": 50 }, "threshold": { "default": 0, "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "smiles", "limit", "threshold" ], "additionalProperties": false }, "StructureSearchResponse": { "type": "object", "properties": { "query": { "type": "object", "properties": { "smiles": { "type": "string" }, "limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "threshold": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "smiles", "limit", "threshold" ], "additionalProperties": false }, "method": { "type": "string", "const": "tanimoto-2d-fingerprint" }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/StructureMatch" } } }, "required": [ "query", "method", "total", "results" ], "additionalProperties": false }, "ChangelogKind": { "type": "string", "enum": [ "drug", "class", "ingredient", "interaction", "structure", "dataset", "endpoint" ] }, "ChangelogAction": { "type": "string", "enum": [ "added", "updated", "removed", "released" ] }, "ChangelogEntry": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9][a-z0-9-]*$" }, "kind": { "$ref": "#/components/schemas/ChangelogKind" }, "action": { "$ref": "#/components/schemas/ChangelogAction" }, "entitySlug": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9][a-z0-9-]*$" }, "title": { "type": "string", "minLength": 1 }, "summary": { "type": "string", "minLength": 1 }, "timestamp": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "url": { "type": "string", "pattern": "^\\/[a-z0-9/_#?=&.-]*$" }, "sources": { "default": [], "type": "array", "items": { "type": "string", "format": "uri" } }, "tags": { "default": [], "type": "array", "items": { "type": "string" } } }, "required": [ "id", "kind", "action", "title", "summary", "timestamp", "url", "sources", "tags" ], "additionalProperties": false }, "ChangelogResponse": { "type": "object", "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/ChangelogEntry" } }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "entries", "total" ], "additionalProperties": false }, "ShortageStatus": { "type": "string", "enum": [ "active", "resolved", "discontinuation", "to-be-discontinued" ] }, "ShortageEntry": { "type": "object", "properties": { "drug": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9][a-z0-9-]*$" }, "status": { "$ref": "#/components/schemas/ShortageStatus" }, "presentation": { "type": "string", "minLength": 1 }, "sponsor": { "type": "string" }, "reason": { "type": "string" }, "therapeuticCategory": { "type": "string" }, "fdaUpdatedAt": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, "provenance": { "$ref": "#/components/schemas/Provenance" } }, "required": [ "drug", "status", "presentation", "fdaUpdatedAt", "provenance" ], "additionalProperties": false }, "DrugShortagesResponse": { "type": "object", "properties": { "drug": { "type": "object", "properties": { "slug": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9][a-z0-9-]*$" }, "name": { "type": "string" } }, "required": [ "slug", "name" ], "additionalProperties": false }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/ShortageEntry" } }, "anyActive": { "type": "boolean" }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "drug", "entries", "anyActive", "total" ], "additionalProperties": false }, "ShortagesResponse": { "type": "object", "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/ShortageEntry" } }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "entries", "total" ], "additionalProperties": false }, "AdverseEventReport": { "type": "object", "properties": { "reaction": { "type": "string", "minLength": 1 }, "count": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reaction", "count" ], "additionalProperties": false }, "AdverseEventStats": { "type": "object", "properties": { "drug": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9][a-z0-9-]*$" }, "totalReports": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "topReactions": { "type": "array", "items": { "$ref": "#/components/schemas/AdverseEventReport" } }, "windowStart": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, "windowEnd": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, "disclaimer": { "type": "string" }, "provenance": { "$ref": "#/components/schemas/Provenance" } }, "required": [ "drug", "totalReports", "topReactions", "disclaimer", "provenance" ], "additionalProperties": false }, "AdverseEventStatsResponse": { "type": "object", "properties": { "drug": { "type": "object", "properties": { "slug": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9][a-z0-9-]*$" }, "name": { "type": "string" } }, "required": [ "slug", "name" ], "additionalProperties": false }, "stats": { "anyOf": [ { "$ref": "#/components/schemas/AdverseEventStats" }, { "type": "null" } ] } }, "required": [ "drug", "stats" ], "additionalProperties": false }, "LiteratureReference": { "type": "object", "properties": { "pmid": { "type": "string", "pattern": "^\\d{1,9}$" }, "title": { "type": "string", "minLength": 1 }, "journal": { "type": "string", "minLength": 1 }, "year": { "type": "integer", "minimum": 1800, "maximum": 2200 }, "authors": { "default": [], "type": "array", "items": { "type": "string" } }, "doi": { "type": "string" }, "pubmedUrl": { "type": "string", "format": "uri" } }, "required": [ "pmid", "title", "journal", "year", "authors", "pubmedUrl" ], "additionalProperties": false }, "DrugLiteratureResponse": { "type": "object", "properties": { "drug": { "type": "object", "properties": { "slug": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9][a-z0-9-]*$" }, "name": { "type": "string" } }, "required": [ "slug", "name" ], "additionalProperties": false }, "references": { "type": "array", "items": { "$ref": "#/components/schemas/LiteratureReference" } }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "drug", "references", "total" ], "additionalProperties": false }, "TrialEntry": { "type": "object", "properties": { "nctId": { "type": "string", "pattern": "^NCT\\d{8}$" }, "title": { "type": "string", "minLength": 1 }, "overallStatus": { "type": "string", "minLength": 1 }, "phases": { "default": [], "type": "array", "items": { "type": "string" } }, "studyType": { "type": "string" }, "conditions": { "default": [], "type": "array", "items": { "type": "string" } }, "leadSponsor": { "type": "string" }, "startDate": { "type": "string" }, "lastUpdateDate": { "type": "string" }, "enrollment": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "url": { "type": "string", "format": "uri" } }, "required": [ "nctId", "title", "overallStatus", "phases", "conditions", "url" ], "additionalProperties": false }, "DrugTrialsResponse": { "type": "object", "properties": { "drug": { "type": "object", "properties": { "slug": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9][a-z0-9-]*$" }, "name": { "type": "string" } }, "required": [ "slug", "name" ], "additionalProperties": false }, "trials": { "type": "array", "items": { "$ref": "#/components/schemas/TrialEntry" } }, "totalCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "sampled": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "disclaimer": { "type": "string" } }, "required": [ "drug", "trials", "totalCount", "sampled", "disclaimer" ], "additionalProperties": false }, "DrugHistoryResponse": { "type": "object", "properties": { "drug": { "type": "object", "properties": { "slug": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9][a-z0-9-]*$" }, "name": { "type": "string" } }, "required": [ "slug", "name" ], "additionalProperties": false }, "provenance": { "$ref": "#/components/schemas/Provenance" }, "asOf": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/ChangelogEntry" } }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "drug", "provenance", "events", "total" ], "additionalProperties": false }, "PgxPair": { "type": "object", "properties": { "gene": { "type": "string", "minLength": 1 }, "cpicLevel": { "type": "string" }, "clinpgxLevel": { "type": "string" }, "fdaLabelTesting": { "type": "string" }, "guidelineName": { "type": "string" }, "guidelineUrl": { "type": "string", "format": "uri" }, "citations": { "default": [], "type": "array", "items": { "type": "string" } }, "provisional": { "default": false, "type": "boolean" } }, "required": [ "gene", "citations", "provisional" ], "additionalProperties": false }, "DrugPgxResponse": { "type": "object", "properties": { "drug": { "type": "object", "properties": { "slug": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9][a-z0-9-]*$" }, "name": { "type": "string" } }, "required": [ "slug", "name" ], "additionalProperties": false }, "pairs": { "type": "array", "items": { "$ref": "#/components/schemas/PgxPair" } }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "disclaimer": { "type": "string" } }, "required": [ "drug", "pairs", "total", "disclaimer" ], "additionalProperties": false }, "ReactionSummary": { "type": "object", "properties": { "slug": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9][a-z0-9-]*$" }, "name": { "type": "string", "minLength": 1 }, "aliases": { "default": [], "type": "array", "items": { "type": "string" } }, "drugCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalReports": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "slug", "name", "aliases", "drugCount", "totalReports" ], "additionalProperties": false }, "ReactionDrugRow": { "type": "object", "properties": { "drug": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9][a-z0-9-]*$" }, "name": { "type": "string", "minLength": 1 }, "count": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "share": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "null" } ] }, "drugTotalReports": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "drug", "name", "count", "share", "drugTotalReports" ], "additionalProperties": false }, "RelatedReaction": { "type": "object", "properties": { "slug": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9][a-z0-9-]*$" }, "name": { "type": "string", "minLength": 1 }, "sharedDrugs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "similarity": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "slug", "name", "sharedDrugs", "similarity" ], "additionalProperties": false }, "MeshTreeNode": { "type": "object", "properties": { "uid": { "type": "string", "minLength": 1 }, "descriptorId": { "type": "string", "pattern": "^D\\d{6,9}$" }, "name": { "type": "string", "minLength": 1 } }, "required": [ "uid", "descriptorId", "name" ], "additionalProperties": false }, "ReactionMeta": { "type": "object", "properties": { "meshDescriptorId": { "type": "string", "pattern": "^D\\d{6,9}$" }, "meshUid": { "type": "string", "minLength": 1 }, "meshDescriptorName": { "type": "string", "minLength": 1 }, "meshEntryTerms": { "default": [], "type": "array", "items": { "type": "string" } }, "scopeNote": { "type": "string", "minLength": 1 }, "treeNumbers": { "minItems": 1, "type": "array", "items": { "type": "string" } }, "parents": { "default": [], "type": "array", "items": { "$ref": "#/components/schemas/MeshTreeNode" } }, "meshBrowserUrl": { "type": "string", "format": "uri" }, "references": { "default": [], "type": "array", "items": { "$ref": "#/components/schemas/LiteratureReference" } }, "provenance": { "$ref": "#/components/schemas/Provenance" } }, "required": [ "meshDescriptorId", "meshUid", "meshDescriptorName", "meshEntryTerms", "scopeNote", "treeNumbers", "parents", "meshBrowserUrl", "references", "provenance" ], "additionalProperties": false }, "Reaction": { "type": "object", "properties": { "slug": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9][a-z0-9-]*$" }, "name": { "type": "string", "minLength": 1 }, "aliases": { "default": [], "type": "array", "items": { "type": "string" } }, "drugCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalReports": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "drugs": { "type": "array", "items": { "$ref": "#/components/schemas/ReactionDrugRow" } }, "relatedReactions": { "type": "array", "items": { "$ref": "#/components/schemas/RelatedReaction" } }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/ReactionMeta" }, { "type": "null" } ] }, "disclaimer": { "type": "string" } }, "required": [ "slug", "name", "aliases", "drugCount", "totalReports", "drugs", "relatedReactions", "meta", "disclaimer" ], "additionalProperties": false }, "ReactionsListResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ReactionSummary" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": [ "items", "pagination" ], "additionalProperties": false }, "ReactionResponse": { "type": "object", "properties": { "slug": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9][a-z0-9-]*$" }, "name": { "type": "string", "minLength": 1 }, "aliases": { "default": [], "type": "array", "items": { "type": "string" } }, "drugCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalReports": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "drugs": { "type": "array", "items": { "$ref": "#/components/schemas/ReactionDrugRow" } }, "relatedReactions": { "type": "array", "items": { "$ref": "#/components/schemas/RelatedReaction" } }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/ReactionMeta" }, { "type": "null" } ] }, "disclaimer": { "type": "string" } }, "required": [ "slug", "name", "aliases", "drugCount", "totalReports", "drugs", "relatedReactions", "meta", "disclaimer" ], "additionalProperties": false }, "ConditionSummary": { "type": "object", "properties": { "slug": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9][a-z0-9-]*$" }, "name": { "type": "string", "minLength": 1 }, "icd10": { "type": "string", "minLength": 1 }, "category": { "type": "string", "minLength": 1 }, "drugCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "slug", "name", "icd10", "category", "drugCount" ], "additionalProperties": false }, "ConditionDrugRow": { "type": "object", "properties": { "slug": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9][a-z0-9-]*$" }, "name": { "type": "string", "minLength": 1 }, "indications": { "minItems": 1, "type": "array", "items": { "type": "string" } } }, "required": [ "slug", "name", "indications" ], "additionalProperties": false }, "RelatedCondition": { "type": "object", "properties": { "slug": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9][a-z0-9-]*$" }, "name": { "type": "string", "minLength": 1 }, "sharedDrugs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "similarity": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "slug", "name", "sharedDrugs", "similarity" ], "additionalProperties": false }, "Condition": { "type": "object", "properties": { "slug": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9][a-z0-9-]*$" }, "name": { "type": "string", "minLength": 1 }, "icd10": { "type": "string", "minLength": 1 }, "category": { "type": "string", "minLength": 1 }, "drugCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "drugs": { "type": "array", "items": { "$ref": "#/components/schemas/ConditionDrugRow" } }, "relatedConditions": { "type": "array", "items": { "$ref": "#/components/schemas/RelatedCondition" } }, "disclaimer": { "type": "string" } }, "required": [ "slug", "name", "icd10", "category", "drugCount", "drugs", "relatedConditions", "disclaimer" ], "additionalProperties": false }, "ConditionsListResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ConditionSummary" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": [ "items", "pagination" ], "additionalProperties": false }, "ConditionResponse": { "type": "object", "properties": { "slug": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9][a-z0-9-]*$" }, "name": { "type": "string", "minLength": 1 }, "icd10": { "type": "string", "minLength": 1 }, "category": { "type": "string", "minLength": 1 }, "drugCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "drugs": { "type": "array", "items": { "$ref": "#/components/schemas/ConditionDrugRow" } }, "relatedConditions": { "type": "array", "items": { "$ref": "#/components/schemas/RelatedCondition" } }, "disclaimer": { "type": "string" } }, "required": [ "slug", "name", "icd10", "category", "drugCount", "drugs", "relatedConditions", "disclaimer" ], "additionalProperties": false }, "PassageSection": { "type": "string", "enum": [ "overview", "mechanism", "indications", "contraindications", "dosing", "pharmacokinetics", "interactions", "boxed-warning", "dosage-and-administration", "warnings-and-precautions", "adverse-reactions", "use-in-specific-populations", "overdosage", "patient-summary" ] }, "RetrievalMethod": { "type": "string", "enum": [ "embedding", "lexical" ] }, "SemanticPassage": { "type": "object", "properties": { "id": { "type": "string" }, "drug": { "type": "object", "properties": { "slug": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9][a-z0-9-]*$" }, "name": { "type": "string" } }, "required": [ "slug", "name" ], "additionalProperties": false }, "section": { "$ref": "#/components/schemas/PassageSection" }, "chunk": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "text": { "type": "string" }, "score": { "type": "number" }, "provenance": { "$ref": "#/components/schemas/Provenance" } }, "required": [ "id", "drug", "section", "chunk", "text", "score", "provenance" ], "additionalProperties": false }, "SemanticSearchResponse": { "type": "object", "properties": { "query": { "type": "string" }, "method": { "$ref": "#/components/schemas/RetrievalMethod" }, "model": { "type": "string" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/SemanticPassage" } }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "disclaimer": { "type": "string" } }, "required": [ "query", "method", "results", "total", "disclaimer" ], "additionalProperties": false }, "GroundedRequest": { "type": "object", "properties": { "query": { "type": "string", "minLength": 3, "maxLength": 500 }, "limit": { "default": 8, "type": "integer", "minimum": 1, "maximum": 20 }, "sections": { "type": "array", "items": { "$ref": "#/components/schemas/PassageSection" } } }, "required": [ "query", "limit" ], "additionalProperties": false }, "GroundedCitation": { "type": "object", "properties": { "id": { "type": "string" }, "drug": { "type": "object", "properties": { "slug": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9][a-z0-9-]*$" }, "name": { "type": "string" } }, "required": [ "slug", "name" ], "additionalProperties": false }, "section": { "$ref": "#/components/schemas/PassageSection" }, "passageId": { "type": "string" }, "url": { "type": "string" }, "provenance": { "$ref": "#/components/schemas/Provenance" } }, "required": [ "id", "drug", "section", "passageId", "url", "provenance" ], "additionalProperties": false }, "GroundingSpan": { "type": "object", "properties": { "start": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "end": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "citationId": { "type": "string" } }, "required": [ "start", "end", "citationId" ], "additionalProperties": false }, "GroundedPassage": { "type": "object", "properties": { "id": { "type": "string" }, "citationId": { "type": "string" }, "drug": { "type": "object", "properties": { "slug": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9][a-z0-9-]*$" }, "name": { "type": "string" } }, "required": [ "slug", "name" ], "additionalProperties": false }, "section": { "$ref": "#/components/schemas/PassageSection" }, "chunk": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "text": { "type": "string" }, "score": { "type": "number" }, "grounding": { "type": "array", "items": { "$ref": "#/components/schemas/GroundingSpan" } } }, "required": [ "id", "citationId", "drug", "section", "chunk", "text", "score", "grounding" ], "additionalProperties": false }, "GroundedResponse": { "type": "object", "properties": { "query": { "type": "string" }, "method": { "$ref": "#/components/schemas/RetrievalMethod" }, "model": { "type": "string" }, "passages": { "type": "array", "items": { "$ref": "#/components/schemas/GroundedPassage" } }, "citations": { "type": "array", "items": { "$ref": "#/components/schemas/GroundedCitation" } }, "usage": { "type": "object", "properties": { "tier": { "type": "string" }, "requestCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "tier" ], "additionalProperties": false }, "disclaimer": { "type": "string" } }, "required": [ "query", "method", "passages", "citations", "usage", "disclaimer" ], "additionalProperties": false }, "WebhookEventName": { "type": "string", "enum": [ "drug.created", "drug.updated", "drug.deleted", "dataset.refreshed" ] }, "WebhookDrugChange": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "sourceHash": { "type": "string" }, "changedSections": { "type": "array", "items": { "type": "string" } } }, "required": [ "slug" ], "additionalProperties": false }, "WebhookEventPayload": { "type": "object", "properties": { "id": { "type": "string" }, "event": { "$ref": "#/components/schemas/WebhookEventName" }, "timestamp": { "type": "string" }, "datasetVersion": { "type": "string" }, "drugs": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDrugChange" } }, "summary": { "type": "object", "properties": { "created": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "updated": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "deleted": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "created", "updated", "deleted" ], "additionalProperties": false } }, "required": [ "id", "event", "timestamp" ], "additionalProperties": false }, "WebhookEndpoint": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEventName" } }, "active": { "type": "boolean" }, "createdAt": { "type": "string" }, "failureCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "lastStatus": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "lastDeliveryAt": { "type": "string" } }, "required": [ "id", "url", "events", "active", "createdAt", "failureCount" ], "additionalProperties": false }, "WebhookCreateRequest": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "events": { "default": [ "drug.created", "drug.updated", "drug.deleted", "dataset.refreshed" ], "minItems": 1, "type": "array", "items": { "$ref": "#/components/schemas/WebhookEventName" } } }, "required": [ "url", "events" ], "additionalProperties": false }, "WebhookEndpointCreated": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEventName" } }, "active": { "type": "boolean" }, "createdAt": { "type": "string" }, "failureCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "lastStatus": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "lastDeliveryAt": { "type": "string" }, "secret": { "type": "string" } }, "required": [ "id", "url", "events", "active", "createdAt", "failureCount", "secret" ], "additionalProperties": false }, "WebhooksListResponse": { "type": "object", "properties": { "endpoints": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" } }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "endpoints", "total" ], "additionalProperties": false }, "WebhookDeleteResponse": { "type": "object", "properties": { "deleted": { "type": "boolean", "const": true }, "id": { "type": "string" } }, "required": [ "deleted", "id" ], "additionalProperties": false } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API key for the grounded tier and webhook management (`Authorization: Bearer pk_live_...`)." } } }, "x-tagGroups": [ { "name": "Catalog", "tags": [ "Drugs", "Classes", "Ingredients", "Brands" ] }, { "name": "Tools", "tags": [ "Search", "Interactions", "Shortages", "AdverseEvents", "Reactions", "Conditions", "Literature", "Trials", "Pharmacogenomics", "Retrieval" ] }, { "name": "Platform", "tags": [ "Changelog", "Webhooks", "System" ] } ] }