MIRACLE API

🌟 Introduction

MIRACLE is an open-source API that provides evidence-based reference values for cardiovascular magnetic resonance (CMR) measurements. It standardizes the interpretation of CMR studies by offering instant access to peer-reviewed normal ranges, z-scores, and percentiles across multiple clinical domains.

🚀 Live Demos

• Pediatric CMR Reference Calculator: miracle-app.surge.sh

• Interactive Chatbot: miracle-chat.netlify.app

✨ Key Features

• 📊 Evidence-based reference values
• 🔓 Open-access API
• 🏥 Multiple clinical domains
• 🧮 Real-time z-score calculations
• 📈 Percentile computations
• 🤖 AI/LLM integration ready
• 📱 REST API with flexible endpoints

🛠️ Getting Started

Basic API Call

curl --request GET \
     --url 'https://ref.miracle-api.workers.dev/exec?domain=Pediatric_Ventricle&parameter=LVEDV&gender=Male' \
     --header 'accept: application/json'

Code Examples

import requests

url = "https://ref.miracle-api.workers.dev/exec?domain=Pediatric_Ventricle&parameter=LVEDV&gender=Male"

headers = {"accept": "application/json"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {accept: 'application/json'}};

fetch('https://ref.miracle-api.workers.dev/exec?domain=Pediatric_Ventricle&parameter=LVEDV&gender=Male', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

📚 API Endpoints

Adult Cardiac

Adult Vascular

Pediatric Cardiac

Full documentation available at miracleapi.readme.io

🏥 For the SCMR Community

Ready-to-Use Applications

1. Pediatric CMR Z-score Calculator Web App

   • React-based frontend with Material-UI components
   • Real-time validation and calculation
   • RESTful API integration with error handling
   • Mobile-responsive design
   • Print support
   • Live Demo | Source Code

2. Virtual CMR Report Generator

   • Batch processing of multiple parameters
   • Customizable report templates using Handlebars
   • Export options: PDF, DOCX, JSON
   • Integration examples with clinical systems

   // Example report generation
   const report = await miracleAPI.generateReport({
     patient: { gender: "Male", height: 110, weight: 22 },
     measurements: {
       LVEDV: 62,
       LVEF: 60,
       LVM: 45
     },
     template: "pediatric_standard"
   });
   

3. LLM-Powered Chatbot

   • OpenAI/Groq function calling architecture
   • Natural language parsing with structured output
   • Context-aware conversation handling
   • Error boundary implementation
   • Live Demo | Source Code

   // Example function calling schema
   {
     "name": "getPediatricVentricleZScore",
     "parameters": {
       "type": "object",
       "properties": {
         "gender": { "type": "string", "enum": ["Male", "Female"] },
         "parameter": { "type": "string", "enum": ["LVEDV", "LVEF", "LVM"] },
         "measured": { "type": "number" },
         "ht_cm": { "type": "number" },
         "wt_kg": { "type": "number" }
       }
     }
   }
   

AI/LLM Integration

LLM-Ready Documentation

• Structured markdown format at /llms.txt
• Automated updates via GitHub Actions
• Endpoint schemas in OpenAPI 3.0

curl https://miracleapi.readme.io/llms.txt
# Returns markdown-formatted documentation

Model Context Protocol (MCP)

• OpenAPI specification at /mcp
• JSON Schema validation
• Rate limiting information
• Authentication requirements
• Read Documentation

curl https://miracleapi.readme.io/mcp
# Returns OpenAPI specification

Function Calling Support

• OpenAI-compatible function definitions
• Anthropic Claude-ready schemas
• Groq API integration examples
• Error handling patterns

# Example function registration with OpenAI
tools = [{
    "type": "function",
    "function": {
        "name": "getPediatricReferenceValues",
        "description": "Get z-scores for pediatric CMR measurements",
        "parameters": { ... }
    }
}]

Research Tools

Current Capabilities

# Example: Basic batch processing with current API
import pandas as pd
import requests

def process_cmr_data(data_df):
    base_url = "https://ref.miracle-api.workers.dev/exec"
    results = []
    
    for _, row in data_df.iterrows():
        params = {
            "domain": "Pediatric_Ventricle",
            "parameter": row["parameter"],
            "gender": row["gender"],
            "measured": row["value"],
            "ht_cm": row["height"],
            "wt_kg": row["weight"]
        }
        response = requests.get(base_url, params=params)
        results.append(response.json())
    
    return pd.DataFrame(results)

# Usage
df = pd.read_csv("measurements.csv")
results_df = process_cmr_data(df)
results_df.to_csv("results_with_zscores.csv")

🛣️ Future Roadmap (Planned Features)

• DICOM SR templates
• REDCap integration
• Data validation suite

🐍 Python SDK

The official Python SDK is now available for batch processing and research workflows.

Installation:

pip install miracle-sdk

Usage:

from miracle import Miracle, MiracleBatch

# Single request
client = Miracle()
result = client.pediatric_ventricle_reference_values(
    parameter="LVEDV",
    gender="Male",
    measured=62.5,
    ht_cm=110,
    wt_kg=22
)
print(result)

# Batch processing (parallel, high-performance)
processor = MiracleBatch(max_workers=10)
df_results = processor.process_csv(
    file_path="patients.csv",
    domain="Pediatric_Ventricle",
    mapping={"gender": "gender", "ht_cm": "height_cm", ...}
)
df_results.to_csv("results_with_zscores.csv")

📦 PyPI: pypi.org/project/miracle-sdk | GitHub: github.com/drankush/MIRACLE-sdk

📖 Citation

@article{ankush2026miracle,
  title   = {MIRACLE: An Open-Access API for Evidence-Based Reference Values in Cardiovascular MRI},
  author  = {Ankush, Ankush and Ponnatapura, Janardhana and Sakthivel, Muthu and Sellamuthu, Eswara},
  journal = {Journal of Cardiovascular Magnetic Resonance},
  volume  = {28},
  pages   = {102338},
  year    = {2026},
  doi     = {10.1016/j.jocmr.2025.102338}
}

Ankush A, et al. MIRACLE: An Open-Access API for Evidence-Based Reference Values in Cardiovascular MRI. Journal of Cardiovascular Magnetic Resonance. 2026;28:102338. https://doi.org/10.1016/j.jocmr.2025.102338

📄 License

Apache License 2.0 - See LICENSE for details