API Schema Reference
Every public endpoint, its response fields, exposure level, and per-endpoint safety context.
ASH publishes a read-only research API for researchers, developers, and dashboard integrations. Every endpoint is public, CORS-enabled, and CDN-cached — no authentication and no PII. This page documents the true response shape of each endpoint and tags every field by exposure level, so consumers know which data is patient-safe versus gated behind an audience parameter.
Exposure levels
- Patient-safeReturned to anonymous consumers and the default
audience=patientpayload. Plain-language, governance, and safety-scaffolding fields. - Clinician-gatedGated behind
?audience=clinician. Protocol-like depth (leech counts, durations, contraindications, trial intervention detail). Returning it requires an explicit acknowledgement that it is educational, not institutional protocol. - Researcher-gatedGated behind
?audience=researcher. Citation depth (key-trial lists, full citation arrays) for literature-graph and academic integrations. - AlwaysPresent for every audience — identifiers, citation identifiers, governance status, and hypermedia
_links. - Citation-integrityCitation-integrity status. Every citation-bearing object carries
citationIntegrityStatus— one ofverified_pubmed,unverified_pending,verified_doi, oridentifier_absent— per the Cycle 11 PMID-quarantine model. Treatunverified_pendingentries as suspect until the PMID audit completes.
Endpoints
/api/research-articlesResearch-article library
PubMed-verified bibliographic metadata for the imported research-article library (1,000+ entries). Bibliographic only — no clinical protocol detail.
Query parameters: limit (1–100, default 25), offset (≥0), organ_system (substring), year_min, year_max, tier (very-low | low | moderate | high).
Response fields
| Field | Exposure | Meaning |
|---|---|---|
| slug | Always | Stable identifier for the article entry. |
| pmid | Always | PubMed identifier, or null when absent. |
| title | Always | Article title. |
| authors | Always | Author string. |
| year | Always | Publication year. |
| journal | Always | Source journal. |
| citationIntegrityStatus | Citation-integrity | verified_pubmed | unverified_pending | verified_doi | identifier_absent. Carried by every citation-bearing object. |
| pmidVerified | Citation-integrity | ISO date the PMID was resolved against PubMed E-utilities (present only when verified). |
| organSystem | Patient-safe | Organ-system tag, emitted only when present on the entry. |
| evidenceTier | Patient-safe | GRADE tier mirrored from hirudopedia evidenceGrade when present. |
| studyType | Patient-safe | Study design tag, when present. |
| safetyDomain | Patient-safe | Safety-domain tag, when present. |
| dateAdded | Patient-safe | ISO date the entry was added. |
Safety / exposure note
All fields are bibliographic metadata — no protocol detail, leech counts, or dosing. Each article carries citationIntegrityStatus per the Cycle 11 PMID-quarantine model; treat unverified_pending entries as suspect until the PMID Integrity Sprint completes (see /pmid-audit-status). FDA cleared leeches for one indication only (K040187, 2004); all other indexed uses are off-label or investigational.
/api/conditionsCondition registry
Audience-routed condition registry. Defaults to patient-safe; clinical protocol depth and citation depth are gated behind the audience parameter.
Default audience: patient (default)
Query parameters: limit (1–100, default 25), offset (≥0), tier (A-FDA-cleared | B-clinical-evidence | C-investigational), category (12 organ-system enum values), audience (patient | clinician | researcher).
Response fields
| Field | Exposure | Meaning |
|---|---|---|
| slug, name, tagline, tier, category | Patient-safe | Core identity and classification, present for all audiences. |
| patientName, laymanDescription | Patient-safe | Plain-language naming and description. |
| icd10Codes | Patient-safe | ICD-10 code array, when present. |
| regulatoryStatus, evidenceLevel, safetyTier, safetyDomains, scopeStatement | Patient-safe | Governance and safety metadata — always safe to expose. |
| patientSummary, whatThisDoesNotMean, askClinicianQuestions, redFlagsUrgentCare, limitations | Patient-safe | Patient-facing safety scaffolding. |
| evidenceSummary | Clinician-gated | Full evidence summary. Returned for audience=clinician (and researcher). |
| protocolSummary | Clinician-gated | Protocol summary — gated; only under audience=clinician. |
| typicalLeechCount | Clinician-gated | Typical leech count — gated clinical detail. |
| typicalDuration | Clinician-gated | Typical treatment duration — gated clinical detail. |
| contraindications | Clinician-gated | Contraindication list — gated clinical decision content. |
| keyTrials[] | Researcher-gated | Key-trial citation depth; only under audience=researcher. |
| keyTrials[].citationIntegrityStatus | Citation-integrity | Per-trial integrity status (verified_pubmed | unverified_pending | verified_doi | identifier_absent). |
| _links | Always | condition_page path and related_rcts count. |
Safety / exposure note
Defaults to audience=patient and OMITS protocolSummary, typicalLeechCount, typicalDuration, contraindications, and keyTrials. These were reclassified as a P0 safety surface in Cycle 11 — protocol-like content (leech counts, frequencies, thresholds) is gated behind ?audience=clinician with an explicit acknowledgement that it is educational, not a substitute for institutional governance. _safetyContext documents exactly which fields were withheld for the active audience.
/api/compoundsCompound registry
Leech-derived bioactive-compound metadata (hirudin, hyaluronidase, eglins, etc.). Pharmacology / biochemistry reference — not clinical protocol detail.
Query parameters: limit (1–100, default 25), offset (≥0), category (anticoagulant | antiplatelet | fibrinolytic | proteinase-inhibitor | anti-inflammatory | antimicrobial | vasodilator | ecm-enzyme | analgesic | other).
Response fields
| Field | Exposure | Meaning |
|---|---|---|
| slug, name, tagline | Patient-safe | Identity and one-line description. |
| category | Patient-safe | Compound class enum. |
| evidenceTier | Patient-safe | Evidence tier for the compound. |
| molecularWeightDa | Patient-safe | Molecular weight in daltons, when numeric. |
| targets | Patient-safe | Molecular-target array, when present. |
| _links | Always | compound_page path. |
Safety / exposure note
Bioactive-compound metadata for educational reference — no clinical protocol detail. Drug-vs-leech distinction matters: FDA-approved hirudin-class drugs (lepirudin, desirudin, bivalirudin) are recombinant or synthetic analogs, NOT whole-leech therapy, and most leech salivary compounds remain preclinical.
/api/rctsRCT registry
Randomized-controlled-trial registry. Research-oriented, so it defaults to audience=researcher; the patient audience strips intervention/protocol depth.
Default audience: researcher (default)
Query parameters: limit (1–100, default 25), offset (≥0), grade (high | moderate | low | very-low), status (completed | ongoing | preliminary), condition (registry slug), audience (researcher | clinician | patient).
Response fields
| Field | Exposure | Meaning |
|---|---|---|
| slug, title, authors, year, journal, condition, grade, status | Always | Trial identity, GRADE certainty, and status — present for all audiences. |
| pmid, doi | Always | Citation identifiers (research-citation, not clinical-actionable). |
| pmidVerified | Citation-integrity | ISO verification date, when present. |
| citationIntegrityStatus | Citation-integrity | verified_pubmed | unverified_pending | verified_doi | identifier_absent, computed per entry. |
| design, n, intervention, comparator, primaryEndpoint, primaryResult, cohen_d, followUpDuration, phase, keyFindings, limitations, clinicalImplications, fundingSource | Clinician-gated | Trial-design and intervention depth. Withheld from audience=patient; present for clinician and researcher. |
| citations[] | Researcher-gated | Full citation list, each carrying its own citationIntegrityStatus. Only under audience=researcher. |
| _links | Always | rct_page, condition_page, and pubmed URL (or null). |
Safety / exposure note
Default audience=researcher exposes trial-design depth; audience=patient strips intervention, comparator, primaryResult and similar protocol-adjacent fields, keeping only title/grade/year/status. Every entry and every nested citation carries citationIntegrityStatus, and _safetyContext lists which fields were filtered for the active audience.
/api/biographiesBiography registry
Historically- and contemporary-significant figures in hirudotherapy science (Haycraft 1884 → present). Public-domain biographical facts only.
Query parameters: limit (1–100, default 25), offset (≥0), era (ancient | medieval | 19th-century | early-20th | mid-20th | late-20th | contemporary).
Response fields
| Field | Exposure | Meaning |
|---|---|---|
| slug, name | Patient-safe | Identifier and full name. |
| lifeSpan | Patient-safe | Life-years string (registry lifeYears, e.g. "1857-1922"). |
| era | Patient-safe | Era enum value. |
| contribution | Patient-safe | One-sentence contribution (mapped from registry tagline). |
| publicationCount | Patient-safe | Count of keyPublications (0 when none). |
| institutionalAffiliations | Patient-safe | Affiliation array, when present. |
| _links | Always | biography_page path. |
Safety / exposure note
Public biographical metadata only — no clinical content. Inclusion in this registry does not imply ASH endorses any clinical claim made by the individual or any product associated with them.
/api/jurisdictionsJurisdiction registry
Global regulatory survey — authorities governing medicinal leech therapy worldwide (FDA, EMA, PMDA, Health Canada, WHO, etc.).
Query parameters: limit (1–100, default 25), offset (≥0), region (north-america | europe | asia-pacific | latin-america | middle-east | africa | oceania).
Response fields
| Field | Exposure | Meaning |
|---|---|---|
| slug | Patient-safe | Stable identifier. |
| name | Patient-safe | Country name (registry country field). |
| regulatoryAuthority | Patient-safe | Full agency name (registry name field). |
| leechRegulatoryStatus | Patient-safe | Honest status marker; uses 'unregulated' where no leech-specific pathway is verified. |
| region, type | Patient-safe | Region enum and jurisdiction type. |
| shortName | Patient-safe | Short agency name, when present. |
| lastReviewedByASH | Patient-safe | ISO date of ASH editorial review (closest analogue to a 'regulated since' date). |
| _links | Always | jurisdiction_page path. |
Safety / exposure note
Regulatory reference, not medical or legal advice. Most jurisdictions have NO leech-specific authorization pathway; an 'unregulated' status means ASH has not verified a pathway — not that the country allows or prohibits the practice. Verify current status with the named authority before any clinical use.
/api/site-statsSite statistics (hypermedia root)
Aggregate registry counts and cross-API discovery links. Public hypermedia root for programmatic consumers, dashboards, and structured data.
Query parameters: None. Static, CDN-cached.
Response fields
| Field | Exposure | Meaning |
|---|---|---|
| asOf | Always | ISO timestamp of the response. |
| registries | Always | Counts: conditions, compounds, rcts, biographies, jurisdictions. |
| researchArticles | Always | Research-article library size. |
| totalArtifacts | Always | Sum of all registry counts plus research articles. |
| longTermGoal, progressPct | Always | 10,000-article goal and percent progress. |
| conditionTiers | Always | Condition counts by tier { A, B, C }. |
| links, apis | Always | Site links and the sibling-endpoint discovery object. |
Safety / exposure note
Aggregate statistics only — no clinical protocol detail and no per-entry data. conditionTiers.A counts only conditions within the FDA-cleared pathway (K040187, 2004); Tier B/C are off-label or investigational. progressPct measures library size against a 10,000-article goal and does NOT imply clinical recommendation. Each sibling endpoint reached via the apis object enforces its own audience model and citation integrity.
/api/changelogEditorial changelog
Public editorial change history, hand-maintained from the merged-PR record. Companion to /api/site-stats for aggregators tracking editorial activity.
Query parameters: limit (1–50, default 20), category (architecture | content | translation | registry | correction | infrastructure, case-insensitive).
Response fields
| Field | Exposure | Meaning |
|---|---|---|
| date | Always | Entry date (YYYY-MM-DD). |
| prRange | Always | Associated PR reference (e.g. "PR #70"). |
| title, summary | Always | Change title and summary. |
| category | Always | One of architecture | content | translation | registry | correction | infrastructure. |
| details | Always | Array of detail strings. |
| categories | Always | Top-level count of entries per category across the full log. |
Safety / exposure note
Editorial change log for educational / audit reference — no clinical protocol detail. Inclusion reflects ASH editorial activity, not endorsement of any clinical claim referenced in an entry. The 'correction' category surfaces errata (e.g. fabricated-PMID removals) transparently rather than silently revising them.
Related pages
How Evidence Is Graded
The Tier A/B/C framework and GRADE-aligned ratings behind the API fields.
Framework →