OpenEvidence — Evidence Review & Citations

Overview

Search medical evidence, manage citations, and generate formatted evidence reports through OpenEvidence. Use this workflow to find clinical studies for a specific question, build citation collections for literature reviews, or produce structured evidence summaries with graded recommendations. This is the secondary workflow — for DeepConsult research synthesis, see openevidence-core-workflow-a.

Instructions

Step 1: Search the Evidence Database

const results = await client.evidence.search({
  query: 'SGLT2 inhibitors cardiovascular outcomes type 2 diabetes',
  filters: {
    study_type: ['rct', 'meta_analysis', 'systematic_review'],
    year_range: { min: 2020, max: 2026 },
    evidence_level: ['1a', '1b', '2a'],
  },
  limit: 25,
  sort: 'relevance',
});
console.log(`Found ${results.total} studies`);
results.items.forEach(s =>
  console.log(`  [${s.evidence_level}] ${s.title} (${s.journal}, ${s.year}) — ${s.citations} citations`)
);

Step 2: Build a Citation Collection

const collection = await client.citations.create({
  name: 'SGLT2i CV Outcomes Review — April 2026',
  study_ids: results.items.slice(0, 15).map(s => s.id),
  tags: ['cardiology', 'diabetes', 'sglt2i'],
});
console.log(`Collection ${collection.id}: ${collection.study_count} studies`);
await client.citations.addByDoi(collection.id, { doi: '10.1056/NEJMoa2034577' });

Step 3: Grade Evidence and Extract Key Findings

const graded = await client.evidence.grade(collection.id, {
  framework: 'GRADE',  // GRADE | Oxford | USPSTF
  outcome: 'major_adverse_cardiovascular_events',
});
graded.findings.forEach(f =>
  console.log(`${f.outcome}: ${f.grade} (${f.certainty}) — ${f.summary}`)
);
console.log(`Overall recommendation: ${graded.recommendation}`);

Step 4: Generate a Formatted Evidence Report

const report = await client.reports.generate({
  collection_id: collection.id,
  format: 'structured',
  sections: ['clinical_question', 'search_strategy', 'evidence_table', 'grade_summary', 'references'],
  citation_style: 'AMA',
});
console.log(`Report generated: ${report.page_count} pages`);
console.log(`Download: ${report.download_url}`);

HIPAA Notice

HIPAA-compliant and SOC 2 Type II certified — never include patient identifiers
Use de-identified clinical scenarios only; ensure BAA is in place before handling PHI

Error Handling

Issue	Cause	Fix
`401 Unauthorized`	Invalid API key or expired session	Regenerate key in OpenEvidence dashboard
`404 Study not found`	DOI not indexed or incorrect ID	Search by title or check DOI format
`422 Invalid filter`	Unsupported evidence_level or study_type	Use allowed values from `client.schema.filters()`
`429 Rate limited`	Exceeded 60 queries/minute	Add backoff; batch searches where possible
`503 Grading unavailable`	GRADE engine under maintenance	Retry after 5 minutes or use Oxford framework

Output

A successful workflow returns ranked evidence results with evidence levels, a curated citation collection, GRADE assessments with certainty ratings, and a downloadable structured report in AMA citation format.

Resources

OpenEvidence Platform

Next Steps

See openevidence-sdk-patterns for authentication and HIPAA-compliant configuration.