MediSearch Evidence APIv1.0.0

Quickstart

curl https://evidence.medisearch.io/v1/evidence/search \
  -H "Authorization: Bearer $MEDISEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "At what age should colorectal cancer screening start?",
    "max_results": 5,
    "filters": {
      "source_types": ["guideline"],
      "guideline": {"countries": ["US"]}
    }
  }'

Authentication

Send your API key with every request to /v1/evidence/search and /mcp, in either header:

Authorization: Bearer <API_KEY>
X-API-Key: <API_KEY>

Missing or invalid keys return 401. Keys are issued by MediSearch; request one at founders@medisearch.io. /, /reference, /openapi.json, /v1/filters* and /healthz are public.

Rate limits

Limits are set per key; the default is 60 requests per minute. Authenticated responses include X-RateLimit-Limit and X-RateLimit-Remaining. Excess requests return 429 with Retry-After. For a higher limit, contact founders@medisearch.io. The service scales to zero; the first request after a period of inactivity takes longer while it starts.

Search

POST /v1/evidence/search · JSON body:

Results are ordered by relevance. Each publication appears at most once.

Optional search hints

Most requests need only question. These fields can improve results for follow-ups, multi-part questions and exact names:

Filters

All optional. Filters combine with AND; values within one filter combine with OR. Unknown values return 422 with suggestions. Nested fields live under filters, e.g. filters.guideline.countries.

Study types

Country matching

guideline.countries: ["DE"] matches guidelines issued in Germany, guidance issued for Europe as a whole, and international bodies (region global, e.g. WHO, Cochrane, KDIGO). With include_reference_bodies: true it also matches:

US CDC, FDA, NIH, USPSTF, NCI, AHRQ, VA/DoD, AHA, ACC, HRS, ASCO, NCCN, ACS-Onc, ASTRO, IDSA, ADA, ES, AACE, ACP, AAFP, AAP, ACOG, AGA, ACG, AASLD, ASGE, ATS, CHEST/ACCP, SCCM, AAN, ACR, APA, ASH, AUA

EU/UK EMA, ECDC, ESC, EACTS, ESVS, ESMO, ESTRO, ERS, EASL, ESGE, ECCO, UEG, EULAR, EAU, ESCMID, EACS, EAN, ESO, ESICM, EHA, ESE, ESHRE, EAACI, NICE, SIGN, BTS, RCOG

Looking up values

The reference page lists every value. As JSON (public):

GET https://evidence.medisearch.io/v1/filters
GET https://evidence.medisearch.io/v1/filters/organizations?q=kardio&country=DE

Response

Top level: request_id, question, rerank_query, result_count, latency_ms, filters_applied, results[]. Each result:

{
  "question": "At what age should colorectal cancer screening start?",
  "result_count": 1,
  "filters_applied": {
    "source_types": [
      "guideline"
    ],
    "guideline": {
      "countries": [
        "US"
      ]
    },
    "...": "..."
  },
  "results": [
    {
      "rank": 1,
      "relevance_score": 0.9442,
      "source_type": "guideline",
      "document_types": [
        "guideline"
      ],
      "title": "Colorectal cancer screening: An update to the American Cancer Society guideline, 2026.",
      "url": "https://pubmed.ncbi.nlm.nih.gov/42200680/",
      "deep_link": "https://pubmed.ncbi.nlm.nih.gov/42200680/#:~:text=…",
      "year": 2026,
      "authors": [
        "Andrew M D Wolf",
        "Richard M Hoffman",
        "…"
      ],
      "journal": "CA: a cancer journal for clinicians",
      "organization": {
        "code": "ACS-Onc",
        "name": "American Cancer Society"
      },
      "passage": "… In 2018, the American Cancer Society (ACS) lowered the recommended age to initiate screening for average-risk adults to age 45 years. …",
      "passage_kind": "passage",
      "section": null,
      "citation": "Andrew M D Wolf et al. (2026). Colorectal cancer screening: An update to the American Cancer Society guideline, 2026. CA: a cancer journal for clinicians. https://pubmed.ncbi.nlm.nih.gov/42200680/"
    }
  ]
}

MCP

Streamable HTTP transport, stateless: POST JSON-RPC 2.0 messages to https://evidence.medisearch.io/mcp and read a JSON response. No session or SSE stream; GET returns 405. Protocol versions 2025-06-18, 2025-03-26, 2024-11-05. Authentication as above.

Both tools are reads with no side effects: they do not create, change or delete data, act on a user's behalf, or require user permissions. Neither is a sensitive action. Calls are stateless and safe to retry. MCP annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true.

Search arguments are the REST fields, flattened:

Claude

In claude.ai, Claude Desktop, Claude mobile or Cowork: Settings → Connectors → Add custom connector, name MediSearch, URL https://evidence.medisearch.io/mcp, no authentication. Both tools then appear in the conversation's tool menu. In Claude Code: claude mcp add --transport http medisearch https://evidence.medisearch.io/mcp --header "Authorization: Bearer <API_KEY>".

Client configuration

{
  "mcpServers": {
    "medisearch": {
      "type": "http",
      "url": "https://evidence.medisearch.io/mcp",
      "headers": {
        "Authorization": "Bearer <API_KEY>"
      }
    }
  }
}

Examples

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_medical_evidence",
    "arguments": {
      "question": "At what age should colorectal cancer screening start?",
      "source_types": [
        "guideline"
      ],
      "guideline_countries": [
        "US"
      ],
      "max_results": 5
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "list_evidence_filter_options",
    "arguments": {
      "organization_search": "cardio",
      "country": "DE"
    }
  }
}

Invalid tool arguments and search failures return a result with isError: true and a readable message naming each invalid argument, so the model can correct the call. Unknown tools and malformed requests return JSON-RPC errors (e.g. -32602).

Errors

REST errors have the body {"error": string, "detail": any}.