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:**
```json
{
  "status": "online",
  "engine_ready": true,
  "version": "1.5"
}
```

---

### 2. Detailed Health Check
**GET** `/api/health`

**Description:** Container health monitoring endpoint

**Response:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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):**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:
```json
{
  "detail": "Error message description"
}
```

---

## Integration Examples

### JavaScript (Fetch API)
```javascript
// 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)
```python
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
```bash
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.