api/QUICK_REFERENCE.md

RagBot API - Quick Reference

🚀 Quick Start Commands

Start API (Local)

# From api/ directory
cd C:\Users\admin\OneDrive\Documents\GitHub\RagBot\api
..\.\.venv\Scripts\python.exe -m uvicorn app.main:app --reload --port 8000

Start API (Docker)

# From api/ directory
docker-compose up --build

Test API

# Run test suite
.\test_api.ps1

# Or manual test
curl http://localhost:8000/api/v1/health

---

📡 Endpoints Cheat Sheet

Method	Endpoint	Purpose
GET	/api/v1/health	Check API status
GET	/api/v1/biomarkers	List all 24 biomarkers
POST	/api/v1/analyze/natural	Natural language analysis
POST	/api/v1/analyze/structured	Structured JSON analysis
GET	/api/v1/example	Pre-run diabetes example
GET	/docs	Swagger UI documentation

---

💻 Integration Snippets

JavaScript/Fetch

const response = await fetch('http://localhost:8000/api/v1/analyze/natural', {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    message: "My glucose is 185 and HbA1c is 8.2",
    patient_context: {age: 52, gender: "male"}
  })
});
const result = await response.json();
console.log(result.prediction.disease); // "Diabetes"

PowerShell

$body = @{
    biomarkers = @{Glucose = 185; HbA1c = 8.2}
    patient_context = @{age = 52; gender = "male"}
} | ConvertTo-Json

$result = Invoke-RestMethod -Uri "http://localhost:8000/api/v1/analyze/structured" `
    -Method Post -Body $body -ContentType "application/json"

Write-Host $result.prediction.disease

Python

import requests

response = requests.post('http://localhost:8000/api/v1/analyze/structured', json={
    'biomarkers': {'Glucose': 185.0, 'HbA1c': 8.2},
    'patient_context': {'age': 52, 'gender': 'male'}
})
result = response.json()
print(result['prediction']['disease'])  # Diabetes

---

🔧 Troubleshooting Quick Fixes

API won't start

# Check if port 8000 is in use
netstat -ano | findstr :8000

# Kill process if needed
taskkill /PID <PID> /F

LLM provider errors

# Check your .env has the right keys
# Default provider is Groq (GROQ_API_KEY required)
# Alternative: Google Gemini (GOOGLE_API_KEY)
# Optional: Ollama (local, no key needed)

Vector store not loading

# From RagBot root
.\.venv\Scripts\python.exe scripts/setup_embeddings.py

---

📊 Response Fields Overview

Key Fields You'll Use:

• prediction.disease - Predicted disease name
• prediction.confidence - Confidence score (0-1)
• analysis.safety_alerts - Critical warnings
• analysis.biomarker_flags - All biomarker statuses
• analysis.recommendations.immediate_actions - What to do
• conversational_summary - Human-friendly text for display

Full Data Access:

• agent_outputs - Raw agent execution data
• analysis.disease_explanation.citations - Medical literature sources
• workflow_metadata - Execution details

---

🎯 Common Use Cases

1. Chatbot Integration

// User types: "my glucose is 140"
const response = await analyzeNatural(userMessage);
displayResult(response.conversational_summary);

2. Form-Based Input

// User fills form with biomarker values
const response = await analyzeStructured({
  biomarkers: formData,
  patient_context: patientInfo
});
showAnalysis(response.analysis);

3. Dashboard Display

// Fetch and display example
const example = await fetch('/api/v1/example').then(r => r.json());
renderDashboard(example);

---

🔐 Production Checklist

Before deploying to production:

• Update CORS in .env (restrict to your domain)
• Add API key authentication
• Enable HTTPS
• Set up rate limiting
• Configure logging (rotate logs)
• Add monitoring/alerts
• Test error handling
• Document API for your team

---

📞 Support

• API Docs: http://localhost:8000/docs
• Main README: api/README.md
• RagBot Docs: ../docs/

---

🎓 Example Requests

Simple Test

curl http://localhost:8000/api/v1/health

Full Analysis

curl -X POST http://localhost:8000/api/v1/analyze/natural \
  -H "Content-Type: application/json" \
  -d '{"message": "glucose 185, HbA1c 8.2", "patient_context": {"age": 52, "gender": "male"}}'

Get Example

curl http://localhost:8000/api/v1/example

---

Last Updated: February 2026
API Version: 1.0.0