OpenEvidence Upgrade & Migration

Overview

OpenEvidence is a clinical AI platform that provides evidence-based medical answers and clinical decision support. The API exposes endpoints for clinical queries, evidence retrieval, and citation management. Tracking API changes is critical because OpenEvidence evolves its evidence grading schema, citation format, and clinical query response structure — and breaking changes in a healthcare context can surface outdated medical evidence, alter confidence scores, or remove critical safety disclaimers that downstream clinical applications depend on.

Version Detection

const OPENEVIDENCE_BASE = "https://api.openevidence.com/v1";

async function detectOpenEvidenceVersion(apiKey: string): Promise<void> {
  const res = await fetch(`${OPENEVIDENCE_BASE}/status`, {
    headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
  });
  const version = res.headers.get("x-openevidence-api-version") ?? "v1";
  console.log(`OpenEvidence API version: ${version}`);

  // Test clinical query response schema
  const queryRes = await fetch(`${OPENEVIDENCE_BASE}/query`, {
    method: "POST",
    headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
    body: JSON.stringify({ question: "What is the recommended treatment for hypertension?", max_citations: 1 }),
  });
  const data = await queryRes.json();
  const hasStructuredCitations = data.citations?.[0]?.evidence_grade !== undefined;
  console.log(`Structured citations: ${hasStructuredCitations}`);
  const hasDisclaimers = data.disclaimers !== undefined;
  console.log(`Disclaimers field present: ${hasDisclaimers}`);
}

Migration Checklist

• Review OpenEvidence release notes for API schema changes
• Verify clinical query response structure (answer, citations, confidence)
• Check evidence grading scale — letter grades vs. numeric scores may change
• Validate citation format (PMID references, DOI links, journal metadata)
• Test disclaimer and safety warning fields in query responses
• Update clinical specialty filters if taxonomy was expanded
• Check rate limits for clinical query endpoints (may differ by plan tier)
• Verify streaming response format if using real-time query mode
• Update evidence date range filters if temporal query syntax changed
• Run clinical validation suite against known question-answer pairs

Schema Migration

// OpenEvidence query response: flat answer → structured evidence with grading
interface OldQueryResponse {
  answer: string;
  citations: Array<{ title: string; url: string; source: string }>;
  confidence: number;
}

interface NewQueryResponse {
  answer: { text: string; sections: Array<{ heading: string; content: string }> };
  citations: Array<{
    title: string;
    url: string;
    source: string;
    pmid?: string;
    doi?: string;
    evidence_grade: "A" | "B" | "C" | "D" | "expert_opinion";
    publication_year: number;
  }>;
  confidence: { score: number; level: "high" | "moderate" | "low"; basis: string };
  disclaimers: string[];
  query_metadata: { specialty: string; guidelines_version: string };
}

function migrateQueryResponse(old: OldQueryResponse): NewQueryResponse {
  return {
    answer: { text: old.answer, sections: [{ heading: "Summary", content: old.answer }] },
    citations: old.citations.map((c) => ({
      ...c,
      evidence_grade: "C" as const,
      publication_year: 0,
    })),
    confidence: { score: old.confidence, level: old.confidence > 0.7 ? "high" : "moderate", basis: "legacy" },
    disclaimers: ["This information is for educational purposes. Consult a healthcare provider."],
    query_metadata: { specialty: "general", guidelines_version: "unknown" },
  };
}

Rollback Strategy

class OpenEvidenceClient {
  private apiVersion: "v1" | "v2";

  constructor(private apiKey: string, version: "v1" | "v2" = "v2") {
    this.apiVersion = version;
  }

  async query(question: string, options?: { specialty?: string }): Promise<any> {
    try {
      const res = await fetch(`https://api.openevidence.com/${this.apiVersion}/query`, {
        method: "POST",
        headers: { Authorization: `Bearer ${this.apiKey}`, "Content-Type": "application/json" },
        body: JSON.stringify({ question, ...options }),
      });
      if (!res.ok) throw new Error(`OpenEvidence ${res.status}`);
      return await res.json();
    } catch (err) {
      if (this.apiVersion === "v2") {
        console.warn("Falling back to OpenEvidence API v1");
        this.apiVersion = "v1";
        return this.query(question, options);
      }
      throw err;
    }
  }
}

Error Handling

Resources

• OpenEvidence
• OpenEvidence API Documentation

Next Steps

For CI pipeline integration, see openevidence-ci-integration.