API_DOCUMENTATION.md

# Deepfake Detection API - Complete API Reference

## Base URL
```
http://localhost:8000
```

---

## **API Endpoints Overview**

### 1. Root Endpoint
- **Endpoint**: `GET /`
- **Description**: Returns API status and available endpoints
- **Authentication**: None
- **Response Format**: JSON

### 2. Health Check (Comprehensive)
- **Endpoint**: `GET /api/health`
- **Description**: Comprehensive health check with system diagnostics
- **Authentication**: None
- **Response Format**: JSON

### 3. Health Check (Simple)
- **Endpoint**: `GET /api/health/simple`
- **Description**: Simple health check for load balancers
- **Authentication**: None
- **Response Format**: JSON

### 4. Readiness Probe
- **Endpoint**: `GET /api/health/ready`
- **Description**: Kubernetes-style readiness probe
- **Authentication**: None
- **Response Format**: JSON

### 5. Liveness Probe
- **Endpoint**: `GET /api/health/live`
- **Description**: Kubernetes-style liveness probe
- **Authentication**: None
- **Response Format**: JSON

### 6. Combined Prediction
- **Endpoint**: `POST /api/predict`
- **Description**: Combined prediction using both XceptionNet and MesoNet models
- **Parameter**: `file` (multipart/form-data)
- **Authentication**: None
- **Response Format**: JSON

### 3. XceptionNet Prediction
- **Endpoint**: `POST /api/xceptionnet/predict`
- **Description**: Deepfake detection using XceptionNet model
- **Parameter**: `image` (multipart/form-data)
- **Authentication**: None
- **Response Format**: JSON

### 4. XceptionNet Model Info
- **Endpoint**: `GET /api/xceptionnet/info`
- **Description**: Get XceptionNet model information
- **Authentication**: None
- **Response Format**: JSON

### 5. MesoNet Prediction
- **Endpoint**: `POST /api/mesonet/predict`
- **Description**: Deepfake detection using MesoNet model
- **Parameter**: `image` (multipart/form-data)
- **Authentication**: None
- **Response Format**: JSON

### 6. MesoNet Model Info
- **Endpoint**: `GET /api/mesonet/info`
- **Description**: Get MesoNet model information
- **Authentication**: None
- **Response Format**: JSON

### 7. GradCAM Analysis
- **Endpoint**: `POST /api/gradcam/analyze`
- **Description**: Generate GradCAM analysis with prediction and visualization (PDF report)
- **Parameter**: `image` (multipart/form-data)
- **Authentication**: None
- **Response Format**: JSON with base64 encoded PDF

### 8. GradCAM Batch Analysis
- **Endpoint**: `POST /api/gradcam/analyze-batch`
- **Description**: Batch GradCAM analysis for multiple images
- **Parameter**: `images` (multipart/form-data, multiple files)
- **Authentication**: None
- **Response Format**: JSON with array of results

### 9. GradCAM Model Info
- **Endpoint**: `GET /api/gradcam/model-info`
- **Description**: Get GradCAM model information
- **Authentication**: None
- **Response Format**: JSON

### 10. GradCAM Test
- **Endpoint**: `GET /api/gradcam/test`
- **Description**: Test GradCAM functionality
- **Authentication**: None
- **Response Format**: JSON

---

## **Detailed API Specifications**

### 1. Root Endpoint

**Request:**
```bash
GET /
```

**Response:**
```json
{
  "status": "ok",
  "message": "Deepfake Detection API Backend is running",
  "available_endpoints": {
    "combined_prediction": "/api/predict",
    "xceptionnet_prediction": "/api/xceptionnet/predict",
    "xceptionnet_info": "/api/xceptionnet/info",
    "mesonet_prediction": "/api/mesonet/predict",
    "mesonet_info": "/api/mesonet/info",
    "gradcam_analysis": "/api/gradcam/analyze",
    "gradcam_batch": "/api/gradcam/analyze-batch",
    "gradcam_info": "/api/gradcam/model-info",
    "gradcam_test": "/api/gradcam/test"
  },
  "usage": {...},
  "new_features": {...}
}
```

---

### 2. Health Check API (Comprehensive)

**Request:**
```bash
GET /api/health
```

**Success Response (200):**
```json
{
  "status": "healthy",
  "timestamp": "2025-10-14T12:30:45.123456",
  "uptime": "running",
  "models": {
    "xceptionnet": "loaded",
    "mesonet": "loaded"
  },
  "system_resources": {
    "memory": {
      "total_gb": 16.0,
      "available_gb": 8.5,
      "used_percent": 46.9
    },
    "disk": {
      "total_gb": 500.0,
      "free_gb": 250.0,
      "used_percent": 50.0
    },
    "cpu_percent": 25.3
  },
  "directories": {
    "uploads": true,
    "models": true
  },
  "api_version": "1.0.0",
  "service": "Deepfake Detection API"
}
```

**Degraded Response (200):**
```json
{
  "status": "degraded",
  "timestamp": "2025-10-14T12:30:45.123456",
  "uptime": "running",
  "models": {
    "xceptionnet": "loaded",
    "mesonet": "not available"
  },
  "system_resources": {...},
  "directories": {...},
  "api_version": "1.0.0",
  "service": "Deepfake Detection API"
}
```

**Unhealthy Response (200):**
```json
{
  "status": "unhealthy",
  "timestamp": "2025-10-14T12:30:45.123456",
  "error": "Error message",
  "service": "Deepfake Detection API"
}
```

---

### 3. Health Check API (Simple)

**Request:**
```bash
GET /api/health/simple
```

**Success Response (200):**
```json
{
  "status": "healthy",
  "timestamp": "2025-10-14T12:30:45.123456"
}
```

**Degraded Response (200):**
```json
{
  "status": "degraded",
  "timestamp": "2025-10-14T12:30:45.123456",
  "reason": "models not loaded"
}
```

---

### 4. Readiness Probe API

**Request:**
```bash
GET /api/health/ready
```

**Success Response (200):**
```json
{
  "ready": true,
  "timestamp": "2025-10-14T12:30:45.123456"
}
```

**Not Ready Response (200):**
```json
{
  "ready": false,
  "timestamp": "2025-10-14T12:30:45.123456",
  "reason": "models not loaded"
}
```

---

### 5. Liveness Probe API

**Request:**
```bash
GET /api/health/live
```

**Success Response (200):**
```json
{
  "alive": true,
  "timestamp": "2025-10-14T12:30:45.123456"
}
```

---

### 6. Combined Prediction API

**Request:**
```bash
POST /api/predict
Content-Type: multipart/form-data
```

**Parameters:**
- `file`: Image file (JPG, PNG, JPEG)

**Success Response (200):**
```json
{
  "prediction": {
    "combined": 0.7234,
    "xceptionnet": 0.7856,
    "mesonet": 0.6234
  },
  "interpretation": {
    "result": "Fake",
    "confidence": 0.8934
  }
}
```

**Error Responses:**
- `400`: No file provided / Invalid image format
- `500`: Model not available / Prediction failed

---

### 3. XceptionNet Prediction API

**Request:**
```bash
POST /api/xceptionnet/predict
Content-Type: multipart/form-data
```

**Parameters:**
- `image`: Image file (JPG, PNG, JPEG)

**Success Response (200):**
```json
{
  "prediction": {
    "probability": 0.7856,
    "label": "fake",
    "confidence": 0.8934
  }
}
```

**Error Responses:**
- `400`: No file provided / Invalid image format
- `500`: XceptionNet model not available / Prediction failed

---

### 4. XceptionNet Model Info API

**Request:**
```bash
GET /api/xceptionnet/info
```

**Success Response (200):**
```json
{
  "model_info": {
    "name": "XceptionNet",
    "input_shape": "(299, 299, 3)",
    "type": "CNN with Face Detection",
    "task": "Deepfake Detection",
    "status": "loaded"
  }
}
```

**Error Response:**
- `500`: Server error

---

### 5. MesoNet Prediction API

**Request:**
```bash
POST /api/mesonet/predict
Content-Type: multipart/form-data
```

**Parameters:**
- `image`: Image file (JPG, PNG, JPEG)

**Success Response (200):**
```json
{
  "prediction": {
    "probability": 0.6234,
    "label": "fake",
    "confidence": 0.7689
  }
}
```

**Error Responses:**
- `400`: No file provided / Invalid image format
- `500`: MesoNet model not available / Prediction failed

---

### 6. MesoNet Model Info API

**Request:**
```bash
GET /api/mesonet/info
```

**Success Response (200):**
```json
{
  "model_info": {
    "name": "MesoNet",
    "input_shape": "(256, 256, 3)",
    "type": "CNN with Face Detection",
    "task": "Deepfake Detection",
    "status": "loaded"
  }
}
```

**Error Response:**
- `500`: Server error

---

### 7. GradCAM Analysis API

**Request:**
```bash
POST /api/gradcam/analyze
Content-Type: multipart/form-data
```

**Parameters:**
- `image`: Image file (JPG, PNG, JPEG)
- `userId`: User ID (string, required) - Identifies the user making the request

**Success Response (200):**
```json
{
  "prediction": {
    "probability": 0.7856,
    "label": "fake",
    "confidence": 0.8934,
    "classification": "deepfake"
  },
  "technical_details": {
    "face_confidence": 0.95,
    "processing_time_ms": 1234,
    "model_layer": "block14_sepconv2_act",
    "image_hash": "a1b2c3d4e5f6g7h8..."
  },
  "report_info": {
    "format": "application/pdf",
    "status": "generated_and_saved",
    "message": "PDF report has been generated and saved to cloud storage",
    "access_via": "Use the URL in saved_files to access the PDF report"
  },
  "saved_files": {
    "pdf_filename": "gradcam_deepfake_image_20250114_123045.pdf",
    "pdf_url": "https://supabase.co/storage/v1/object/public/...",
    "supabase_path": "deepfake-reports/gradcam_deepfake_image_20250114_123045.pdf",
    "primary_storage": "supabase",
    "saved_at": "2025-01-14T12:30:45.123456",
    "file_size_mb": 2.45,
    "storage_locations": ["supabase", "local"]
  },
  "database": {
    "record_id": "uuid-here",
    "stored": true
  }
}
```

**Error Responses:**
- `400`: No file provided / Invalid image format / userId is required
- `500`: GradCAM analysis failed

---

### 8. GradCAM Batch Analysis API

**Request:**
```bash
POST /api/gradcam/analyze-batch
Content-Type: multipart/form-data
```

**Parameters:**
- `images`: Multiple image files (JPG, PNG, JPEG)
- `userId`: User ID (string, required) - Identifies the user making the request

**Success Response (200):**
```json
{
  "batch_summary": {
    "total_images": 5,
    "successful": 4,
    "failed": 1,
    "deepfakes_detected": 2,
    "authentic_detected": 2,
    "batch_processing_time_ms": 5234,
    "average_time_per_image_ms": 1046
  },
  "results": [
    {
      "filename": "image1.jpg",
      "success": true,
      "prediction": {
        "probability": 0.7856,
        "label": "fake",
        "confidence": 0.8934,
        "classification": "deepfake"
      },
      "technical_details": {
        "face_confidence": 0.95,
        "processing_time_ms": 1234,
        "image_hash": "a1b2c3d4e5f6g7h8..."
      },
      "report_format": "application/pdf",
      "saved_files": {
        "pdf_filename": "gradcam_deepfake_batch_001_image1_20250114_123045.pdf",
        "pdf_url": "https://supabase.co/storage/v1/object/public/...",
        "supabase_path": "deepfake-reports/gradcam_deepfake_batch_001_image1_20250114_123045.pdf",
        "primary_storage": "supabase",
        "saved_at": "2025-01-14T12:30:45.123456",
        "file_size_mb": 2.45,
        "storage_locations": ["supabase", "local"]
      },
      "database": {
        "record_id": "uuid-here",
        "stored": true
      }
    },
    {
      "filename": "image2.jpg",
      "success": false,
      "error": "Invalid image format"
    }
  ]
}
```

**Error Responses:**
- `400`: No images provided / userId is required
- `500`: Batch analysis failed

---

### 9. GradCAM Model Info API

**Request:**
```bash
GET /api/gradcam/model-info
```

**Success Response (200):**
```json
{
  "model": {
    "name": "XceptionNet",
    "status": "loaded",
    "target_layer": "block14_sepconv2_act"
  },
  "gradcam": {
    "type": "Optimized GradCAM",
    "memory_optimization": "enabled"
  }
}
```

**Error Response:**
- `500`: Server error

---

### 10. GradCAM Test API

**Request:**
```bash
GET /api/gradcam/test
```

**Success Response (200):**
```json
{
  "status": {
    "model_loaded": true,
    "memory_optimization": "enabled",
    "gradcam_ready": true
  }
}
```

**Error Response:**
- `500`: Server error

---

## **Error Handling**

All endpoints follow a consistent error response format:

```json
{
  "detail": "Error message describing what went wrong"
}
```

### Common HTTP Status Codes:
- `200`: Success
- `400`: Bad Request (invalid input)
- `404`: Not Found
- `500`: Internal Server Error

---

## **Image Requirements**

### Supported Formats:
- JPEG (.jpg, .jpeg)
- PNG (.png)

### Recommendations:
- Image should contain a clear, visible face
- Minimum resolution: 256x256 pixels
- Maximum file size: 10MB (recommended)
- Face should be well-lit and clearly visible

---

## **Testing with cURL**

### Test Root Endpoint:
```bash
curl -X GET http://localhost:8000/
```

### Test Combined Prediction:
```bash
curl -X POST http://localhost:8000/api/predict \
  -F "file=@/path/to/image.jpg"
```

### Test XceptionNet Prediction:
```bash
curl -X POST http://localhost:8000/api/xceptionnet/predict \
  -F "image=@/path/to/image.jpg"
```

### Test XceptionNet Info:
```bash
curl -X GET http://localhost:8000/api/xceptionnet/info
```

### Test MesoNet Prediction:
```bash
curl -X POST http://localhost:8000/api/mesonet/predict \
  -F "image=@/path/to/image.jpg"
```

### Test MesoNet Info:
```bash
curl -X GET http://localhost:8000/api/mesonet/info
```

### Test GradCAM Analysis:
```bash
curl -X POST http://localhost:8000/api/gradcam/analyze \
  -F "image=@/path/to/image.jpg" \
  -F "userId=user123" \
  --output response.json
```

### Test GradCAM Batch:
```bash
curl -X POST http://localhost:8000/api/gradcam/analyze-batch \
  -F "images=@/path/to/image1.jpg" \
  -F "images=@/path/to/image2.jpg" \
  -F "userId=user123" \
  --output batch_response.json
```

### Test GradCAM Model Info:
```bash
curl -X GET http://localhost:8000/api/gradcam/model-info
```

### Test GradCAM Test:
```bash
curl -X GET http://localhost:8000/api/gradcam/test
```

---

## **Notes**

1. **Port Configuration**: Default port is 8000. Can be changed in `app.py`
2. **CORS**: Enabled for all origins (configured for development)
3. **Model Loading**: Models are cached after first load for better performance
4. **Face Detection**: Uses MTCNN for automatic face detection
5. **PDF Reports**: GradCAM endpoints generate professional A4 PDF reports
6. **Memory Optimization**: Server uses optimized memory management for production deployment