Add API reference documentation and response format examples

Author: Dev9269

README.md

@@ -72,6 +72,40 @@ curl -X POST https://malware-detector-production.up.railway.app/api/scan \
   -F "file=@sample.exe"
 ```
 
+### Response Format
+
+Successful scan returns:
+```json
+{
+  "filename": "sample.exe",
+  "malicious": true,
+  "confidence": 0.97,
+  "threat_score": 87,
+  "explanation": {
+    "top_features": [
+      {"name": "suspicious_section_count", "value": 8, "contribution": 0.32},
+      {"name": "high_entropy_sections", "value": 5, "contribution": 0.28}
+    ]
+  },
+  "sha256": "a1b2c3d4...",
+  "timestamp": "2026-07-29T12:00:00Z"
+}
+```
+
+### API Reference
+
+| Endpoint | Method | Description | Query Params |
+|---|---|---|---|
+| `/api/health` | GET | Service health check | — |
+| `/api/scan` | POST | Upload and scan a PE file | `file` (multipart) |
+| `/api/history` | GET | Paginated scan history | `page`, `limit` |
+| `/api/report/{id}` | GET | Detailed scan report by ID | — |
+| `/api/dashboard` | GET | Aggregate statistics | — |
+
+**Authentication:** The API is publicly accessible. Rate limiting is applied per IP (100 req/min).
+
+**Errors:** All endpoints return `{"detail": "error message"}` with appropriate HTTP status codes (400, 404, 422, 500).
+
 ## Running Tests
 
 ```bash