Drugs
Overview
US drug labels by set id: what a drug is approved to do, and what it must warn about.
- status
- live
- document id
set_ide.g.f5e548d0-cc79-4c34-a3f5-e20a5b8b6564- citation
[openFDA SPL f5e548d0…]- updated
- 2026-10
Common calls
Find labels
POST /v1/drugs/search {"query": "GLP-1 受体激动剂 减重", "filters": {"has_boxed_warning": true}}Read one label
GET /v1/drugs/read/<set_id>Filter by class
GET /v1/drugs/facets?field=pharm_class_epcThe fine print
- 67% (171,903) are product_type=UNMAPPED: those SPLs have no openfda mapping block, so generic name / route / pharmacologic class may be empty — use spl_name for the product name.
- Only the latest version per set_id is kept; no label history.
- Indications and contraindications are extracted highlights; go back to the label for prescribing decisions.
- Not medical advice.
- The index holds no full text: level=full is not available yet (the label sections live on NAS (openfda/label); the index carries only section names and token counts).
Search
POST
/v1/drugs/searchHybrid retrieval, one card per hit. 2 credits. Free sample:
semaglutide weight loss.Filter fields
| field | type · ops | meaning |
|---|---|---|
| route | keyword · eq anyORAL · TOPICAL · INTRAVENOUS · INTRAMUSCULAR · SUBCUTANEOUS · OPHTHALMIC … 13 values, /facets lists them all | Route of administration |
| product_type | keyword · eq anyHUMAN PRESCRIPTION DRUG · HUMAN OTC DRUG · CELLULAR THERAPY · UNMAPPED | Product type; UNMAPPED = the SPL has no openfda mapping block |
| is_rx | bool · eq | Prescription-only |
| has_boxed_warning | bool · eq | Has a boxed warning |
| pharm_class_epc | keyword · eq any | Pharmacologic class (EPC) |
| effective_year | integer · eq range | Label version year, range |
8 more, all usable
| field | type · ops | meaning |
|---|---|---|
| generic_name | keyword · eq any | Generic name (exact) |
| substance_names | keyword · eq any | Active substances |
| pharm_class_moa | keyword · eq any | Pharmacologic class (mechanism of action) |
| manufacturer | keyword · eq any | Labeler / manufacturer (exact) |
| rxcui | keyword · eq any | RxNorm concept id |
| unii | keyword · eq any | Substance UNII |
| product_ndc | keyword · eq any | NDC product code |
| application_number | keyword · eq any | FDA application number (NDA / ANDA / BLA) |
Parameters
| Parameter | Type | Description |
|---|---|---|
| query REQUIRED | string | 1–1000 characters. Or an array of up to 5 (batch; hits become results[]). |
| top_k | integer= 10 | 1–100. |
| fields | brief · head= brief | head costs one more credit and returns the head view per hit. |
| filters | json | Filter DSL object (see Getting started); declared fields are listed above. |
| mode | hybrid · dense · bm25= hybrid | Retrieval mode. Leave it out to use the first. |
| offset | integer= 0 | Pagination. |
Example
{ "domain": "drugs", "query": "…", "hits": [ { "id": "f5e548d0-cc79-4c34-a3f5-e20a5b8b6564", "score": 0.83, "brief": { … } } ], "total": null, "coverage": …, "warnings": [],
"meta": { "request_id": "req_…", "credits": { "charged": 2, "balance": 1998, "pool": "allowance" }, "latency_ms": 41, "cached": false } } Undeclared filter fields return 400 rather than being ignored silently. Filters combine with AND;
_or / _not are available.Read
GET
/v1/drugs/read/{set_id}Three depths.
detail is the default. Free sample: f5e548d0-cc79-4c34-a3f5-e20a5b8b6564.Levels
| level | credits | returns |
|---|---|---|
| brief | 1 | Card: the fields needed to triage, same as in search hits |
| detail (default) | 2 | Every structured field (rule-derived plus model-generated; model fields are listed in _enrich.fields) |
| full | 5 | Full text (not available yet: the label sections live on NAS (openfda/label); the index carries only section names and token counts) |
Parameters
| Parameter | Type | Description |
|---|---|---|
| set_id (path) REQUIRED | string | Document id (set_id). |
| level | brief · detail · full= detail | How deep to read. |
| format | json · md · html= json | Response shape. |
Example
{ "domain": "drugs", "id": "f5e548d0-cc79-4c34-a3f5-e20a5b8b6564", "level": "detail", "view": "head", "data": { … } | "text": "…", "token_count": 1834, "meta": { … } } The older
GET /v1/drugs/doc/{id}?view=… still works.Read many
POST
/v1/drugs/readUp to 50 ids, one level. Missing ids come back with
error: "not_found" and are not charged.Parameters
| Parameter | Type | Description |
|---|---|---|
| ids REQUIRED | string[] | Document ids. |
| level | brief · detail · full= detail | Level for every id. |
Example
{ "domain": "drugs", "level": "detail", "docs": [ { "id": "…", "data": { … } }, { "id": "…", "error": "not_found" } ], "meta": { … } } Facets
GET
/v1/drugs/facets?field={field}Legal values for a filter field, so an agent never guesses; precomputed fields carry counts, declared enums come without. Free, no key.
Parameters
| Parameter | Type | Description |
|---|---|---|
| field REQUIRED | route · product_type · pharm_class_epc | Filter field with facets. |
| limit | integer= 50 | Max values. |
Example
{ "domain": "drugs", "field": "…", "values": [ { "value": "…", "count": 3120 } ], "meta": { … } } Askregistered key+ /stream
POST
/v1/drugs/askAgentic Q&A over this domain: the model turns the question into filters plus keywords from the domain's own self-description, reads the hits and answers with [drugs: ] citations; /stream is NDJSON with real token deltas.
effort low / medium / high = 50 / 100 / 200 credits. Append /stream for NDJSON; the first event is always billing. A failure before the first answer_delta is refunded.Parameters
| Parameter | Type | Description |
|---|---|---|
| query REQUIRED | string | 1–2000 characters. Be specific; ask for numbers if you want numbers. |
| effort | low · medium · high= low | Reading rounds, and the price: 50 / 100 / 200 credits. Your plan caps it. |
| verbose | bool= false | Include the tool-call trace (tool_call / tool_result / thinking events when streaming). |
| top_k | integer= 10 | Speculative prefetch size. |
| stream_answer | bool= true | Streaming only: false emits one answer event instead of deltas. |
| max_rounds | integer | 0–8, overrides the effort preset. |
| force_answer_after | number | Seconds; hard cutover into the answer phase. |
| max_answer_tokens | integer= 4096 | Hitting it sets answer_truncated. |
| language | string | Answer language; defaults to the query’s. |
Example
{ "answer": "… [openFDA SPL f5e548d0…] …", "sources": [ … ], "stats": { "rounds": 1, "elapsed_s": 6.2, "answer_truncated": false }, "coverage"?: { … }, "meta": { "credits": { "charged": 50, … } } } Citations are real — every id in
answer exists in this domain (format [openFDA SPL f5e548d0…]). sources is the retrieval set, not the citation list. answer_truncated means incomplete.