Search Medical Papers | Captain Docs

import requests
import uuid
import json
BASE_URL = "https://api.runcaptain.com"
API_KEY = "your_api_key"
ORG_ID = "your_organization_id"
headers = {
    "Authorization": f"Bearer {API_KEY}",
    "X-Organization-ID": ORG_ID,
    "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}")

{
  "domain": "medical",
  "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].",
  "sources": [
    {
      "type": "pubmed",
      "pmid": "28578601",
      "journal": "The New England journal of medicine",
      "year": 2017,
      "doi": "10.1056/NEJMoa1706450",
      "title": "Olaparib for Metastatic Breast Cancer in Patients with a Germline BRCA Mutation."
    },
    {
      "type": "pubmed",
      "pmid": "30110579",
      "journal": "The New England journal of medicine",
      "year": 2018,
      "doi": "10.1056/NEJMoa1802905",
      "title": "Talazoparib in Patients with Advanced Breast Cancer and a Germline BRCA Mutation."
    },
    {
      "type": "clinical_trial",
      "nct_id": "NCT02000622",
      "phase": "PHASE3",
      "status": "ACTIVE_NOT_RECRUITING",
      "title": "Olaparib as Adjuvant Treatment in Patients With Germline BRCA Mutated High Risk HER2 Negative Primary Breast Cancer (OlympiA)"
    },
    {
      "type": "pubmed",
      "pmid": "34081848",
      "journal": "The New England journal of medicine",
      "year": 2021,
      "doi": "10.1056/NEJMoa2105215",
      "title": "Adjuvant Olaparib for Patients with BRCA1- or BRCA2-Mutated Breast Cancer."
    }
  ],
  "gaps": [
    "Long-term (>10 year) survival data for patients on adjuvant olaparib",
    "Head-to-head comparative efficacy between BRCA1 and BRCA2 subgroups"
  ],
  "tool_calls": 5,
  "latency_ms": 7420
}

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.

stream=true returns text/event-stream with tool_use, tool_result_summary, text_delta, and done event types.

Authentication

AuthorizationBearer

Bearer token authentication using API key

Request

This endpoint expects an object.

questionstringRequired3-2000 characters

Natural-language question.

max_sourcesintegerOptional1-25Defaults to 10

Target number of cited sources in the final answer.

include_trialsbooleanOptionalDefaults to true

Whether the agent may call ClinicalTrials.gov.

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_use, tool_result_summary, text_delta, and done events.

domainstring

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

answerstring

Synthesized answer with inline citations.

sourceslist of objects

gapslist of strings

Things the agent could not find or verify.

tool_callsintegerDefaults to 0

Number of tool calls the agent made.

latency_msintegerDefaults to 0

End-to-end wall-clock latency.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

422

Unprocessable Entity Error

Authentication

Headers

Request

Response

Errors