Search Medical Papers | Captain Docs

import requests
import uuid
import json
BASE_URL = "https://api.runcaptain.com"
API_KEY = "your_api_key"
headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
    "Idempotency-Key": str(uuid.uuid4())
}
response = requests.post(
    f"{BASE_URL}/v2/datasets/scientific/medical/ask",
    headers=headers,
    json={
        "question": "What is the evidence that BRCA1-mutated breast cancer patients benefit from PARP inhibitors?",
        "max_sources": 10,
        "include_trials": True,
        "recency_years": 10
    },
    # First invocation of the day can hit a cold Lambda (~60s) + agent loop
    # (~30-60s). 180s leaves headroom for the full cold path.
    timeout=180.0,
)
# Surface non-JSON responses (504 gateway timeout, 502 bad gateway, empty
# body, HTML error pages) instead of blowing up with an opaque JSONDecodeError.
if response.headers.get("content-type", "").startswith("application/json"):
    print(json.dumps(response.json(), indent=2))
else:
    print(f"HTTP {response.status_code}  content-type={response.headers.get('content-type')!r}")
    print(f"body: {response.text[:500]!r}")

{
  "answer": "Strong evidence supports PARP inhibitor use in BRCA1-mutated breast cancer across the metastatic and adjuvant settings. The OlympiAD phase 3 trial showed olaparib monotherapy extended progression-free survival versus standard chemotherapy in metastatic HER2-negative disease (7.0 vs. 4.2 months; HR 0.58) [PMID:28578601]. EMBRACA demonstrated similar benefit with talazoparib (8.6 vs. 5.6 months; HR 0.54) [PMID:30110579]. In the adjuvant setting, OlympiA [NCT:NCT02000622] showed improvements in overall survival (HR 0.68) and invasive disease-free survival [PMID:34081848].",
  "domain": "medical",
  "gaps": [
    "Long-term (>10 year) survival data for patients on adjuvant olaparib",
    "Head-to-head comparative efficacy between BRCA1 and BRCA2 subgroups"
  ],
  "latency_ms": 7420,
  "sources": [
    {
      "url": "https://pubmed.ncbi.nlm.nih.gov/28578601/",
      "title": "Olaparib for Metastatic Breast Cancer in Patients with a Germline BRCA Mutation.",
      "dataset": "pubmed",
      "published_at": "2017",
      "metadata": {
        "type": "pubmed",
        "pmid": "28578601",
        "journal": "The New England journal of medicine",
        "year": 2017,
        "doi": "10.1056/NEJMoa1706450"
      }
    },
    {
      "url": "https://pubmed.ncbi.nlm.nih.gov/30110579/",
      "title": "Talazoparib in Patients with Advanced Breast Cancer and a Germline BRCA Mutation.",
      "dataset": "pubmed",
      "published_at": "2018",
      "metadata": {
        "type": "pubmed",
        "pmid": "30110579",
        "journal": "The New England journal of medicine",
        "year": 2018,
        "doi": "10.1056/NEJMoa1802905"
      }
    },
    {
      "url": "https://clinicaltrials.gov/study/NCT02000622",
      "title": "Olaparib as Adjuvant Treatment in Patients With Germline BRCA Mutated High Risk HER2 Negative Primary Breast Cancer (OlympiA)",
      "dataset": "clinical_trials",
      "metadata": {
        "type": "clinical_trial",
        "nct_id": "NCT02000622",
        "phase": "PHASE3",
        "status": "ACTIVE_NOT_RECRUITING"
      }
    },
    {
      "url": "https://pubmed.ncbi.nlm.nih.gov/34081848/",
      "title": "Adjuvant Olaparib for Patients with BRCA1- or BRCA2-Mutated Breast Cancer.",
      "dataset": "pubmed",
      "published_at": "2021",
      "metadata": {
        "type": "pubmed",
        "pmid": "34081848",
        "journal": "The New England journal of medicine",
        "year": 2021,
        "doi": "10.1056/NEJMoa2105215"
      }
    }
  ],
  "tool_calls": 5
}

Search medical and biomedical papers with a natural-language question. Federates PubMed, PMC full-text, ClinicalTrials.gov, and Semantic Scholar, then synthesizes a cited answer.

Implementation: invokes the medical-agent Lambda (TypeScript, Mastra, Claude Sonnet). Streaming responses flow through the captain-stream S2 basin — identical pattern to /v2/collections/{name}/query.

Search medical and biomedical papers with a natural-language question. Federates PubMed, PMC full-text, ClinicalTrials.gov, and Semantic Scholar, then synthesizes a cited answer. Implementation: invokes the `medical-agent` Lambda (TypeScript, Mastra, Claude Sonnet). Streaming responses flow through the `captain-stream` S2 basin — identical pattern to `/v2/collections/{name}/query`.

Request

This endpoint expects an object.

questionstringRequired3-2000 characters

Natural-language question.

include_trialsbooleanOptionalDefaults to true

Whether the agent may call ClinicalTrials.gov.

max_sourcesintegerOptional1-25Defaults to 10

Target number of cited sources in the final answer.

recency_yearsinteger or nullOptional1-50Defaults to 10

Prefer evidence within the last N years where the question allows.

streambooleanOptionalDefaults to false

If true, response is text/event-stream; otherwise JSON.

Response

Synthesized answer with cited sources. Returns JSON by default; when stream=true the response is text/event-stream with tool.start, tool.end, text.delta, and run.end events.

answerstring

Synthesized answer with inline citations.

domainstring

The scientific domain, e.g. 'medical'.

gapslist of strings

Things the agent could not find or verify.

latency_msintegerDefaults to 0

End-to-end wall-clock latency.

sourceslist of objects

tool_callsintegerDefaults to 0

Number of tool calls the agent made.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error