recycling-project-solutions/API_DOCS.md

# Memory Module Detection API Documentation

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

## Endpoints

### 1. Health Check
**GET** `/health`

Check if the API is running and model is loaded.

**Response:**
```json
{
  "status": "healthy",
  "model_loaded": true,
  "timestamp": "2025-07-12T07:41:46.123456"
}
```

### 2. API Information
**GET** `/api`

Get basic API information and available endpoints.

**Response:**
```json
{
  "name": "Memory Module Detection API",
  "version": "1.0",
  "description": "AI-powered memory module detection using YOLOv8",
  "model_loaded": true,
  "endpoints": ["/health", "/api", "/detect", "/detect/hardcoded", "/detect/base64"]
}
```

### 3. Upload Image Detection
**POST** `/detect`

Upload an image file for memory module detection.

**Request:**
- Content-Type: `multipart/form-data`
- Body: Form data with `file` field containing image
- Optional: `confidence` parameter (default: 0.8)

**Response:**
```json
{
  "success": true,
  "detections": [
    {
      "x1": 100.5,
      "y1": 150.2,
      "x2": 200.8,
      "y2": 250.6,
      "confidence": 0.95,
      "class": "memory_module"
    }
  ],
  "num_detections": 1,
  "annotated_image": "base64_encoded_image_string",
  "confidence_threshold": 0.8
}
```

### 4. Hardcoded Test Image
**GET** `/detect/hardcoded`

Process the hardcoded test image for detection.

**Query Parameters:**
- `confidence` (optional): Confidence threshold (default: 0.8)

**Example:**
```
GET /detect/hardcoded?confidence=0.9
```

**Response:**
```json
{
  "success": true,
  "detections": [...],
  "num_detections": 2,
  "annotated_image": "base64_encoded_image_string",
  "confidence_threshold": 0.9,
  "test_image_path": "training/memory/out1.png"
}
```

### 5. Base64 Image Detection
**POST** `/detect/base64`

Process a base64 encoded image for detection.

**Request:**
```json
{
  "image_data": "base64_encoded_image_string",
  "confidence": 0.8
}
```

**Response:**
```json
{
  "success": true,
  "detections": [...],
  "num_detections": 1,
  "annotated_image": "base64_encoded_image_string",
  "confidence_threshold": 0.8
}
```

## Error Responses

All endpoints return error responses in this format:
```json
{
  "error": "Error message description",
  "success": false
}
```

Common HTTP status codes:
- `200` - Success
- `400` - Bad Request (invalid file, missing parameters)
- `404` - Not Found (endpoint or file not found)
- `413` - File Too Large (max 16MB)
- `500` - Internal Server Error (model not loaded, processing error)

## Supported Image Formats
- PNG
- JPG/JPEG
- GIF
- BMP

## File Size Limits
- Maximum upload size: 16MB

## Detection Response Format

Each detection object contains:
- `x1, y1`: Top-left corner coordinates
- `x2, y2`: Bottom-right corner coordinates  
- `confidence`: Detection confidence score (0.0-1.0)
- `class`: Detected object class ("memory_module")

## Usage Examples

### cURL Examples

**Health Check:**
```bash
curl http://localhost:5002/health
```

**Upload Image:**
```bash
curl -X POST -F "file=@image.jpg" -F "confidence=0.8" http://localhost:5002/detect
```

**Hardcoded Test:**
```bash
curl "http://localhost:5002/detect/hardcoded?confidence=0.9"
```

### Python Examples

**Health Check:**
```python
import requests

response = requests.get('http://localhost:5002/health')
print(response.json())
```

**Upload Image:**
```python
import requests

with open('image.jpg', 'rb') as f:
    files = {'file': f}
    data = {'confidence': 0.8}
    response = requests.post('http://localhost:5002/detect', files=files, data=data)
    print(response.json())
```

**Base64 Detection:**
```python
import requests
import base64

with open('image.jpg', 'rb') as f:
    image_data = base64.b64encode(f.read()).decode()

payload = {
    'image_data': image_data,
    'confidence': 0.8
}
response = requests.post('http://localhost:5002/detect/base64', json=payload)
print(response.json())
```

## Model Information
- **Architecture:** YOLOv8 Nano
- **Classes:** memory_module
- **Input Size:** 640x640
- **Accuracy:** 99.5% mAP50
- **Inference Time:** ~37ms on CPU