API Documentation

Base URL: https://api.medcite.io/api/v1

Authentication

All API requests require an API key via the X-API-Key header.

curl -H "X-API-Key: mc_your_key_here" \
     https://api.medcite.io/api/v1/search \
     -d '{"query": "aspirin"}'

POST /search

Hybrid semantic + keyword search over 39M+ PubMed articles.

Request Body

{
  "query": "SGLT2 inhibitors heart failure outcomes",  // required
  "limit": 20,           // 1-100, default 20
  "year_min": 2018,      // optional
  "year_max": 2026,      // optional
  "language": "eng",     // optional ISO 639 code
  "journal": "Lancet",   // optional, partial match
  "mesh_filter": "Heart Failure"  // optional MeSH term
}

Response

{
  "query": "SGLT2 inhibitors heart failure outcomes",
  "total_results": 20,
  "latency_ms": 42,
  "articles": [
    {
      "pmid": 34878502,
      "title": "SGLT2 Inhibitors and Cardiovascular Risk...",
      "abstract": "Background: ...",
      "journal": "The New England Journal of Medicine",
      "pub_year": 2022,
      "doi": "10.1056/NEJMoa...",
      "authors": "Smith J; Doe A; ...",
      "mesh_terms": "Heart Failure; SGLT2 Inhibitors; ...",
      "score": 0.947,
      "bm25_score": 0.82,
      "vector_score": 0.91
    }
  ]
}

POST /verify

Verify a medical claim against PubMed evidence. Returns a verdict with supporting and contradicting citations.

Request Body

{
  "claim": "Statins reduce cardiovascular mortality by 30%",
  "max_articles": 50  // optional, default 50
}

Response

{
  "status": "completed",
  "claim": "Statins reduce cardiovascular mortality by 30%",
  "report": "## Verdict\nPARTIALLY_SUPPORTED\n\n## Confidence\nMODERATE\n...",
  "article_count": 50,
  "articles_used": [...],
  "cost_usd": 0.52,
  "latency_ms": 8420
}

POST /synthesis

Generate an automated evidence synthesis (rapid review, extended review, or scoping review).

Request Body

{
  "query": "Efficacy of CBT for treatment-resistant depression",
  "tier": "rapid"  // "rapid" ($15) | "extended" ($29) | "scoping" ($59)
}

Tiers

Tier Price Articles Includes
rapid$15Up to 100Narrative synthesis, PICO, citations
extended$29Up to 300+ GRADE assessment, effect sizes, subgroups
scoping$59Up to 800+ PRISMA flowchart, bias screening, CSV data

Article Endpoints

GET /article/{pmid} — Get a single article by PMID

GET /articles/random?count=5&with_abstract=true — Random articles (for demos)

GET /articles/by-year?year=2023&limit=20 — Browse by publication year

GET /journals?q=lancet&limit=50 — List journals with article counts

GET /stats — Database statistics (no auth required)

GET /synthesis/{job_id}/csv — Download synthesis results as CSV

Rate Limits

Plan Price Calls/month
Free$0100
Indie$39/mo10,000
Pro$149/mo100,000
Scale$599/mo1,000,000

Errors

401 — Invalid or missing API key

429 — Monthly limit exceeded

500 — Internal error (try again or contact support)