API Documentation

Programmatic access to the MedicOath discovery engine. All data is CC0 public domain.

Get API Key

Authentication

Include your API key as a Bearer token:

Authorization: Bearer mo_your_key_here

Rate limits: Free (100/hour) | Research (1,000/hour) | Institutional (10,000/hour)

Endpoints

GET/api/v1/diseases

List all diseases with hypothesis counts

Response: { items: Disease[], total: number }

GET/api/v1/diseases/{slug}

Get disease details by slug

Response: { id, name, slug, category, description, neglect_score, ... }

GET/api/v1/diseases/{slug}/summary

AI-generated disease summary (cached 7 days)

Response: { disease, summary: { what_is_known, what_is_unknown, ... } }

GET/api/v1/hypotheses/{id}

Get full hypothesis details

Response: { id, title, mechanism, confidence_score, ipfs_cid, ... }

GET/api/v1/hypotheses/{id}/versions

Version history for a hypothesis

Response: { items: Version[], total: number }

GET/api/v1/hypotheses/{id}/evidence

Evidence submissions for a hypothesis

Response: { items: Evidence[], total: number }

POST/api/v1/hypotheses/{id}/evidence

Submit evidence (no auth required)

Response: { success: true, submission: Evidence }

GET/api/v1/hypotheses/{id}/challenges

Formal challenges to a hypothesis

Response: { items: Challenge[], total: number }

POST/api/v1/hypotheses/{id}/challenges

Challenge a hypothesis (no auth required)

Response: { success: true, challenge: Challenge }

POST/api/v1/hypotheses/{id}/fork

Fork a hypothesis in a new direction

Response: { success: true, fork: Hypothesis }

GET/api/v1/search/semantic?q={query}

Semantic search across diseases, hypotheses, papers

Response: { query, results: Result[], total: number }

GET/api/v1/discoveries/feed

RSS 2.0 feed of latest discoveries

Response: application/rss+xml

POST/api/v1/watches

Watch a disease or hypothesis for updates

Response: { success: true, watch: Watch }

POST/api/v1/api-keys

Generate an API key

Response: { api_key: string, tier, rate_limit }

GET/api/v1/hypotheses/{id}/cite?format=bibtex

Citation export (bibtex, apa, mla, chicago, ris, json-ld)

Response: text/plain or application/x-bibtex

GET/api/v1/hypotheses/{id}/pdf

Hypothesis as printable HTML document

Response: text/html

GET/api/v1/hypotheses/{id}/trials

Matching ClinicalTrials.gov studies

Response: { trials: Trial[], cached: boolean }

GET/api/v1/export/hypotheses?format=json

Bulk export all hypotheses (json or csv)

Response: application/json or text/csv

GET/api/v1/export/diseases?format=json

Bulk export all diseases (json or csv)

Response: application/json or text/csv

GET/api/v1/trending

Trending diseases by activity score

Response: { items: TrendingDisease[] }

GET/api/v1/badges/{slug}

SVG badge for embedding (shields.io style)

Response: image/svg+xml

GET/api/fhir/metadata

FHIR R4 CapabilityStatement

Response: application/fhir+json

GET/api/fhir/ResearchStudy/{id}

Hypothesis as FHIR R4 ResearchStudy

Response: application/fhir+json

GET/api/fhir/ResearchStudy?condition={name}

Search hypotheses by disease (FHIR Bundle)

Response: application/fhir+json

Code Examples

import requests

API_KEY = "mo_your_key_here"
BASE = "https://medicoath.com/api/v1"
headers = {"Authorization": f"Bearer {API_KEY}"}

# Search for Alzheimer's hypotheses
resp = requests.get(
    f"{BASE}/search/semantic",
    params={"q": "tau protein clearance", "type": "hypotheses"},
    headers=headers,
)
for h in resp.json()["results"]:
    print(f"{h['title']} ({h['score']*100:.0f}%)")

Response Headers

X-CC0: true — All data is CC0 public domain

X-ProofChain: {cid} — IPFS CID for ProofChain-timestamped responses

import requests API_KEY = "mo_your_key_here" BASE = "https://medicoath.com/api/v1" headers = {"Authorization": f"Bearer {API_KEY}"} # Search for Alzheimer's hypotheses resp = requests.get( f"{BASE}/search/semantic", params={"q": "tau protein clearance", "type": "hypotheses"}, headers=headers, ) for h in resp.json()["results"]: print(f"{h['title']} ({h['score']*100:.0f}%)")