---
name: 1stauthor-drugs
description: The 1stAuthor drugs domain.
---

# 1stAuthor Drugs

256,282 US drug labels (openFDA SPL, latest version per set_id). Indications, contraindications, interacting drugs, boxed-warning gist and one-line summaries are model-extracted; route / product type / pharmacologic class come from the openfda mapping block.

Base URL `https://api.1stauthor.com`. Every call takes `Authorization: Bearer $FA_API_KEY`; the free samples named below work without a key. Free sample id: `f5e548d0-cc79-4c34-a3f5-e20a5b8b6564`, free sample query: `semaglutide weight loss`.

## Three verbs, every domain

```
POST /v1/{domain}/search  {query, filters?, top_k?}      → hits[].id + a card each
GET  /v1/{domain}/read/{id}?level=brief|detail|full      → read as deep as you need
POST /v1/{domain}/ask     {query, effort: low|medium|high} → an answer with real citations
```

`read` also takes `extra=<side>` for another side of the same document and `format=json|md|html`.
At `level=full`, `section=<name>` reads one section and `characters=N` the first N characters.

## Start here

- **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_epc`

## Search filters

| field | type | meaning |
|---|---|---|
| `route` | keyword · eq any | Route of administration |
| `product_type` | keyword · eq any | 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 |

Rarely needed, but valid: `generic_name`, `substance_names`, `pharm_class_moa`, `manufacturer`, `rxcui`, `unii`, `product_ndc`, `application_number`.

Filters combine with AND; `_or` / `_not` are available. Ranges are `{"gte": n}` / `{"lte": n}`, full text is `{"text": "…"}`.

## Read

| 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) |

## Ask

`POST /v1/drugs/ask {query, effort}` — Agentic 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:<set_id> <title>] citations; /stream is NDJSON with real token deltas. Costs 50 / 100 / 200 credits by effort. Append `/stream` for NDJSON; the first event is always `billing`.

`sources` is the retrieval set, not the citation list — filter it by the ids that appear in `answer`. `answer_truncated` means the answer is incomplete; say so.

## Also here

- GET /v1/entities?q=<机构名> → 实体；GET /v1/entities/<id>/docs?domain=drugs → 该机构在本域的文档

## Facets

`GET /v1/drugs/facets?field=<field>` lists the legal values for `route`, `product_type`, `pharm_class_epc` — free, no key. Use it instead of guessing a spelling.

## Working rules

- **Search first, read second.** A search hit is a card; decide from the card which ids deserve a read.
- **Read in layers.** `detail` answers most questions; go to `full` only when the answer is not in it.
- **Filters are declared.** An undeclared filter field is a 400, never a silent no-op. `GET /v1/{domain}` lists what exists.
- **Cite what you read.** Use the citation format below, and say plainly when the corpus has nothing.
- **Failures are not charged.** A 404 costs nothing; an upstream error is refunded. Quote `meta.request_id` when reporting one.

Citation format: `[openFDA SPL f5e548d0…]`.

## What this corpus will and will not tell you

- 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).

---

Generated from https://api.1stauthor.com/v1/drugs on 2026-10-14. Full reference: https://1stauthor.com/docs/drugs/