Openevidence upgrade migration

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

Migration Issue	Symptom	Fix
Evidence grade scale changed	Grade returns "level-1" instead of "A"	Map new grade scale to internal representation using lookup table
Citation format restructured	Missing pmid field, now nested under identifiers.pmid	Update citation parser for new nested identifier structure
Disclaimer field required	Integration missing safety warnings in user-facing output	Always render disclaimers[] array from query response
Specialty taxonomy expanded	400 with unknown specialty on filtered queries	Fetch current specialties from /specialties endpoint
Streaming format changed	SSE parser breaks on new event structure	Update event stream parser for new data: payload format

Resources

• OpenEvidence
• OpenEvidence API Documentation

Next Steps

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