OpenEvidence Local Dev Loop Skill

OpenEvidence Local Dev Loop

Overview

Local development workflow for OpenEvidence clinical decision support API integration. Provides a fast feedback loop with mock evidence queries, citation responses, and clinical summary data so you can build health-tech tools without consuming live API quota. Toggle between mock mode for rapid iteration and sandbox mode for validating against the real OpenEvidence platform. Always use de-identified data in development.

Environment Setup

cp .env.example .env
# Set your credentials:
# OPENEVIDENCE_API_KEY=oe_xxxxxxxxxxxx
# OPENEVIDENCE_BASE_URL=https://api.openevidence.com/v1
# MOCK_MODE=true
npm install express axios dotenv tsx typescript @types/node
npm install -D vitest supertest @types/express

Dev Server

// src/dev/server.ts
import express from "express";
import { createProxyMiddleware } from "http-proxy-middleware";
const app = express();
app.use(express.json());
const MOCK = process.env.MOCK_MODE === "true";
if (!MOCK) {
  app.use("/v1", createProxyMiddleware({
    target: process.env.OPENEVIDENCE_BASE_URL,
    changeOrigin: true,
    headers: { Authorization: `Bearer ${process.env.OPENEVIDENCE_API_KEY}` },
  }));
} else {
  const { mountMockRoutes } = require("./mocks");
  mountMockRoutes(app);
}
app.listen(3008, () => console.log(`OpenEvidence dev server on :3008 [mock=${MOCK}]`));

Mock Mode

// src/dev/mocks.ts — realistic clinical decision support responses (de-identified)
export function mountMockRoutes(app: any) {
  app.post("/v1/query", (req: any, res: any) => res.json({
    query: req.body.question,
    answer: "Based on current evidence, first-line treatment for type 2 diabetes includes metformin combined with lifestyle modifications. HbA1c targets should be individualized.",
    citations: [
      { title: "ADA Standards of Care 2025", source: "Diabetes Care", doi: "10.2337/dc25-S009", year: 2025 },
      { title: "Metformin Meta-Analysis", source: "NEJM", doi: "10.1056/NEJMoa2412345", year: 2024 },
    ],
    confidenceScore: 0.92,
  }));
  app.get("/v1/topics", (_req: any, res: any) => res.json([
    { id: "top_1", name: "Diabetes Management", questionCount: 245 },
    { id: "top_2", name: "Hypertension", questionCount: 189 },
    { id: "top_3", name: "Oncology Screening", questionCount: 134 },
  ]));
  app.get("/v1/citations/:doi", (req: any, res: any) => res.json({
    doi: req.params.doi, title: "ADA Standards of Care 2025", abstract: "Annual update to diabetes management guidelines...",
    journal: "Diabetes Care", year: 2025, evidenceLevel: "Level I",
  }));
}

Testing Workflow

npm run dev:mock &                    # Start mock server in background
npm run test                          # Unit tests with vitest
npm run test -- --watch               # Watch mode for rapid iteration
MOCK_MODE=false npm run test:integration  # Integration test against real API

Debug Tips

Never use real patient data in development — all mock data must be de-identified
confidenceScore ranges from 0 to 1 — display as percentage in UI
Citation DOIs may be null for preprints or conference abstracts
Query responses can be slow (2-5s) on the live API — set appropriate timeouts
Use topics endpoint to validate query categorization before submitting full queries

Error Handling

| Issue | Cause | Fix | |-------|-------|-----| | 401 Unauthorized | Invalid API key | Regenerate at OpenEvidence developer portal | | 400 Bad Request | Empty or malformed query | Validate question field is non-empty string | | 422 Unprocessable | Query outside supported medical domains | Check supported topics first | | 429 Rate Limited | Too many queries per minute | Add backoff, switch to mock mode | | ECONNREFUSED :3008 | Dev server not running | Run npm run dev:mock first |

Resources

OpenEvidence Platform

Next Steps

See openevidence-debug-bundle.

Agent Skills: OpenEvidence Local Dev Loop

Install this agent skill to your local

Skill Files