API_DOCUMENTATION.md

PPD Recommendation API - Documentation

Base URL

http://localhost:8000

Authentication

Currently no authentication required. For production, implement API key or JWT authentication.

---

Endpoints

1. Health Check

GET /

Response:

{
  "status": "online",
  "engine_ready": true,
  "version": "1.5"
}

---

2. Detailed Health Check

GET /api/health

Description: Container health monitoring endpoint

Response:

{
  "status": "healthy",
  "timestamp": "2026-01-29T18:10:00",
  "checks": {
    "database": "ok",
    "model": "ok",
    "articles_loaded": 139
  }
}

---

3. System Statistics

GET /api/stats

Description: Get system metrics and article counts

Response:

{
  "total_articles": 139,
  "articles_by_type": {
    "pubmed": 136,
    "text": 2,
    "html": 1
  },
  "articles_by_risk": {
    "All": 136,
    "Moderate": 2,
    "High": 1
  },
  "model_vocabulary_size": 20652,
  "last_updated": "2026-01-29T18:10:00"
}

---

4. Get Recommendations (Main Endpoint)

POST /api/recommend

Description: Get personalized article recommendations based on symptoms and crisis level

Request Body:

{
  "risk_level": "Moderate",
  "symptoms_text": "I feel sad and have trouble sleeping",
  "top_n": 5
}

Parameters:

• risk_level (string, required): One of "Low", "Moderate", "High"
• symptoms_text (string, required): User's symptom description
• top_n (integer, optional): Number of recommendations (default: 5)

Response:

{
  "status": "success",
  "risk_assessment": "Moderate",
  "recommendations": [
    {
      "article_id": 134,
      "title": "Sleep disturbances in postpartum depression",
      "category": "General",
      "risk_level": "All",
      "format_type": "pubmed",
      "external_url": "https://pubmed.ncbi.nlm.nih.gov/12345678/",
      "access_type": "External Link",
      "final_score": 0.856
    }
  ]
}

---

5. Get Article Content

GET /api/article/{article_id}

Description: Retrieve full content for a specific article

Parameters:

• article_id (integer, path): Article ID from recommendation

Response:

{
  "article_id": 134,
  "title": "Sleep disturbances in postpartum depression",
  "category": "General",
  "format_type": "pubmed",
  "external_url": "https://pubmed.ncbi.nlm.nih.gov/12345678/",
  "content": "Full article abstract or content..."
}

Error Response (404):

{
  "detail": "Article not found"
}

---

3. Real-Time PubMed Search

GET /api/pubmed/search

Description: Proxy endpoint to fetch articles directly from PubMed in real-time.

Parameters:

• query (string, optional): Search term (default: "postpartum depression")
• limit (int, optional): Number of results (default: 10)

Response:

{
  "status": "success",
  "count": 2,
  "results": [
    {
      "title": "Article Title",
      "content": "Abstract content...",
      "url": "https://pubmed.ncbi.nlm.nih.gov/12345/"
    }
  ]
}

---

6. Rebuild TF-IDF Model (Admin)

POST /api/admin/rebuild-model

Description: Manually trigger model rebuild from existing database

Response:

{
  "status": "success",
  "message": "Weighted TF-IDF model rebuilt and reloaded."
}

---

7. Trigger PubMed Ingestion (Admin)

POST /api/admin/trigger-ingestion

Description: Manually fetch new articles from PubMed and rebuild model

Response:

{
  "status": "success",
  "message": "Ingested 15 new articles and rebuilt model."
}

---

Error Responses

All endpoints return standard HTTP status codes:

• 200: Success
• 404: Resource not found
• 500: Internal server error

Error format:

{
  "detail": "Error message description"
}

---

Integration Examples

JavaScript (Fetch API)

// Get recommendations
const response = await fetch('http://localhost:8000/api/recommend', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    risk_level: 'Moderate',
    symptoms_text: 'anxiety and sleep problems',
    top_n: 3
  })
});
const data = await response.json();
console.log(data.recommendations);

Python (Requests)

import requests

response = requests.post('http://localhost:8000/api/recommend', json={
    'risk_level': 'High',
    'symptoms_text': 'severe depression and suicidal thoughts',
    'top_n': 5
})
recommendations = response.json()['recommendations']

cURL

curl -X POST http://localhost:8000/api/recommend \
  -H "Content-Type: application/json" \
  -d '{"risk_level":"Low","symptoms_text":"mild anxiety","top_n":3}'

---

Rate Limiting

Currently no rate limiting. Recommended for production:

• 100 requests per minute per IP
• 1000 requests per hour per IP

---

CORS

CORS is enabled for all origins in development. For production, restrict to specific domains.