docs: Comprehensive update to API endpoints documentation

📚 ENHANCED API DOCUMENTATION:
- Detailed descriptions for all 13 API endpoints
- Added parameters, request/response formats for each endpoint
- Organized by functional categories (Core, News, Recommendations, Search, AI)
- Added use cases and practical examples for each endpoint
- Comprehensive parameter documentation with defaults

✅ COMPLETE ENDPOINT COVERAGE:
- Core System (3): /, /health, /stats
- News Management (2): /fetch-news, /articles
- Recommendations (4): /recommend-news, /recommend-by-query, /recommend-by-interests, /trending
- Search & Discovery (1): /search
- AI Analysis (3): /analyze-article, /generate-insights, /ai-status

🚀 Ready for developer onboarding and API integration!

docs/README.md

@@ -84,28 +84,89 @@ DS_Task_AI_News/
 
 ## API Endpoints (13 Total)
 
-### **Core System (3)**
-- `GET /` - Root health check
-- `GET /health` - Detailed system health & statistics
-- `GET /stats` - System metrics and performance data
+### **Core System Endpoints (3)**
 
-### **News Management (2)**
-- `POST /fetch-news` - Fetch fresh articles from RSS feeds
-- `GET /articles` - Get articles with pagination & advanced filtering
+#### `GET /`
+- **Purpose**: Root health check and API information
+- **Response**: Basic API status, version, and health confirmation
+- **Use Case**: Quick API availability check
 
-### **Recommendations (4)**
-- `GET /recommend-news` - Recommendations by article ID
-- `POST /recommend-by-query` - Recommendations by text query
-- `POST /recommend-by-interests` - Recommendations by user interests
-- `GET /trending` - Get trending articles
+#### `GET /health`
+- **Purpose**: Detailed system health and statistics
+- **Response**: Vector store stats, total articles, index status, settings
+- **Use Case**: System monitoring and diagnostics
 
-### **Search & Discovery (1)**
-- `POST /search` - Advanced semantic search with filters
+#### `GET /stats`
+- **Purpose**: Comprehensive system metrics and performance data
+- **Response**: Detailed statistics including embedding stats, RSS feeds, model info
+- **Use Case**: Performance monitoring and system analysis
 
-### **AI Analysis (3)**
-- `POST /analyze-article` - AI analysis of specific article
-- `POST /generate-insights` - Generate AI insights from articles
-- `GET /ai-status` - AI system status & capabilities
+### **News Management Endpoints (2)**
+
+#### `POST /fetch-news`
+- **Purpose**: Fetch fresh articles from all configured RSS feeds
+- **Response**: Success status, articles fetched count, total articles
+- **Use Case**: Manual news updates and system refresh
+
+#### `GET /articles`
+- **Purpose**: Retrieve articles with advanced filtering and pagination
+- **Parameters**: `limit`, `offset`, `source`, `category`, `date_from`, `date_to`
+- **Response**: Paginated articles with metadata and filtering info
+- **Use Case**: Browse articles, implement pagination, filter by criteria
+
+### **Recommendation Endpoints (4)**
+
+#### `GET /recommend-news`
+- **Purpose**: Get recommendations based on a specific article ID
+- **Parameters**: `article_id` (required), `top_k` (default: 5)
+- **Response**: Similar articles with similarity scores
+- **Use Case**: "More like this" functionality
+
+#### `POST /recommend-by-query`
+- **Purpose**: Get recommendations based on text query
+- **Body**: `{"query": "text", "top_k": 5}`
+- **Response**: Relevant articles matching query semantics
+- **Use Case**: Content discovery, topic-based recommendations
+
+#### `POST /recommend-by-interests`
+- **Purpose**: Get recommendations based on user interests
+- **Body**: `{"interests": ["AI", "technology"], "top_k": 10}`
+- **Response**: Articles matching user interest profile
+- **Use Case**: Personalized content feeds
+
+#### `GET /trending`
+- **Purpose**: Get currently trending articles
+- **Parameters**: `top_k` (default: 10)
+- **Response**: Most popular/relevant recent articles
+- **Use Case**: Homepage trending section, popular content
+
+### **Search & Discovery Endpoints (1)**
+
+#### `POST /search`
+- **Purpose**: Advanced semantic search with multiple filters
+- **Body**: `{"query": "text", "top_k": 5, "date_from": "2024-01-01", "source": "TechCrunch"}`
+- **Response**: Semantically similar articles with relevance scores
+- **Features**: Semantic similarity, date filtering, source filtering, content inclusion
+- **Use Case**: Intelligent search, content discovery
+
+### **AI Analysis Endpoints (3)**
+
+#### `POST /analyze-article`
+- **Purpose**: AI-powered analysis of a specific article
+- **Body**: `{"article_id": "article_id"}`
+- **Response**: AI-generated summary, sentiment analysis, key insights
+- **Use Case**: Content analysis, automated insights
+
+#### `POST /generate-insights`
+- **Purpose**: Generate AI insights from multiple recent articles
+- **Body**: `{"article_count": 10}`
+- **Response**: Trend analysis, topic summaries, market insights
+- **Use Case**: Market research, trend analysis, content curation
+
+#### `GET /ai-status`
+- **Purpose**: Check AI system status and capabilities
+- **Response**: AI availability, model status, feature capabilities
+- **Use Case**: System health check, feature availability verification
 
 ## Setup & Installation
 
@@ -223,7 +284,7 @@ Our implementation includes:
 {
   "status": "healthy",
   "vector_store": {
-    "total_articles": 714,
+    "total_articles": 238,
     "index_dimension": 384,
     "index_exists": true
   }