openapi: 3.1.0 info: title: FastAPI Recommendation System description: FastAPI Recommendation System API version: 1.0.0 paths: /api/v1/recommendations/coaches/{user_id}: get: tags: - recommendations summary: Get recommendations description: ✨ Retrieve personalized recommendations for a user based on the type parameter (defaults to user if not provided) operationId: get_coach_recommendations_api_v1_recommendations_coaches__user_id__get parameters: - name: user_id in: path required: true schema: type: string description: The user ID to get recommendations for title: User Id description: The user ID to get recommendations for - name: top_k in: query required: false schema: type: integer maximum: 10 minimum: 1 description: 'Number of recommendations to return (1-10, default: 10)' default: 10 title: Top K description: 'Number of recommendations to return (1-10, default: 10)' - name: type in: query required: false schema: $ref: '#/components/schemas/RecommendationType' description: 'Type of recommendations: user (default), coach, or athlete' default: user description: 'Type of recommendations: user (default), coach, or athlete' responses: '200': description: Successfully retrieved recommendations content: application/json: schema: $ref: '#/components/schemas/CoachRecommendationsResponse' examples: single_item: summary: Single recommendation (top_k=1) value: user_id: 5563086a-6465-4608-8afa-3b700f8c9107 recommendations: - score: 0.691477463949316 sports: - Volleyball coach_id: 14a33d13-334e-4424-b3b1-5afbf8017391 service_id: 96fc9bf7-385d-4188-bf88-d5baf3846f6f '400': description: Bad request - Invalid user_id '404': description: User not found '422': description: Validation error '500': description: Internal server error /api/v1/recommendations/feed/{user_id}: get: tags: - recommendations summary: Get Feed Recommendations description: |- ✨ Get top_k feed recommendations for a specific user and remove them from database. Args: user_id: The user ID to get recommendations for top_k: Number of recommendations to return and remove (1-100, default: 5) db: AsyncSession dependency Returns: Dictionary containing the top_k feed recommendations (removed from database) Raises: ValidationError: If user_id is invalid NotFoundError: If no recommendations found HTTPException: 500 for other errors operationId: get_feed_recommendations_api_v1_recommendations_feed__user_id__get parameters: - name: user_id in: path required: true schema: type: string description: The user ID to get feed recommendations for title: User Id description: The user ID to get feed recommendations for - name: top_k in: query required: false schema: type: integer maximum: 100 minimum: 1 description: 'Number of recommendations to return and remove (1-100, default: 5)' default: 5 title: Top K description: 'Number of recommendations to return and remove (1-100, default: 5)' responses: '200': description: Successfully retrieved top_k feed recommendations (removed from recommendations) content: application/json: schema: $ref: '#/components/schemas/FeedRecommendationsResponse' examples: top_5_recommendations: summary: Top 5 recommendations (removed from DB) value: user_id: 4cedfba7-XXXX-YYYY-b48e-33b912b84b7d recommendations: - score: 0.6274336283185841 sports: - Lacrosse post_id: f3b199f3-XXXX-YYYY-82c8-143260a8fa75 coach_id: 8a6c78dd-XXXX-YYYY-ae2c-c7003978a2b3 fallback: original - score: 0.5891234567890123 sports: - Basketball post_id: a1b2c3d4-XXXX-YYYY-82c8-143260a8fa76 coach_id: 9b7c89ef-XXXX-YYYY-ae2c-c7003978a2b4 fallback: original '400': description: Bad request - Invalid user_id '404': description: User not found '422': description: Validation error '500': description: Internal server error /api/v1/recommendations/groups/{user_id}: get: tags: - recommendations summary: Get Groups Recommendations description: |- ✨ Get groups recommendations for a specific user. Args: user_id: The user ID to get recommendations for top_k: Number of recommendations to return (1-10, default: 10) db: AsyncSession dependency Returns: Dictionary containing the groups recommendations data (filtered to top_k items) Raises: ValidationError: If user_id is invalid NotFoundError: If no recommendations found HTTPException: 500 for other errors operationId: get_groups_recommendations_api_v1_recommendations_groups__user_id__get parameters: - name: user_id in: path required: true schema: type: string description: The user ID to get groups recommendations for title: User Id description: The user ID to get groups recommendations for - name: top_k in: query required: false schema: type: integer maximum: 10 minimum: 1 description: 'Number of recommendations to return (1-10, default: 10)' default: 10 title: Top K description: 'Number of recommendations to return (1-10, default: 10)' responses: '200': description: Successfully retrieved groups recommendations content: application/json: schema: $ref: '#/components/schemas/FeedRecommendationsResponse' examples: single_item: summary: Single recommendation (top_k=1) value: user_id: 4cedfba7-XXXX-YYYY-b48e-33b912b84b7d recommendations: - fallback: no geolocation group_id: 0d4bef05-4b33-44f7-b888-4fab428dd20e total_score: 0.4100000000000001 '400': description: Bad request - Invalid user_id '404': description: User not found '422': description: Validation error '500': description: Internal server error /api/v1/health: get: tags: - health summary: Health Check description: ✨ Check the health status of the application operationId: health_check_api_v1_health_get responses: '200': description: Application is healthy content: application/json: schema: {} example: status: healthy timestamp: '2025-08-11T14:47:51.786172+00:00' version: 1.0.0 uptime: running system: cpu_percent: 7.3 memory_percent: 44.9 memory_available: 4528975872 memory_total: 8226844672 services: api: healthy database: not_connected performance: response_time: measured_by_middleware concurrent_requests: monitored_by_uvicorn '503': description: Application is unhealthy components: schemas: CoachRecommendationsResponse: additionalProperties: true type: object title: CoachRecommendationsResponse description: Response model for coach recommendations endpoint. example: recommendations: - coach_id: 14a33d13-334e-4424-b3b1-5afbf8017391 score: 0.691477463949316 service_id: 96fc9bf7-385d-4188-bf88-d5baf3846f6f sports: - Volleyball user_id: 5563086a-6465-4608-8afa-3b700f8c9107 FeedRecommendationsResponse: anyOf: - additionalProperties: true type: object - items: {} type: array title: FeedRecommendationsResponse description: |- Response model for feed recommendations endpoint. Returns top_k recommendations (removed from DB). Returns: - Empty array [] when no recommendations - Dict with recommendations key when recommendations exist example: recommendations: - coach_id: 8a6c78dd-XXXX-YYYY-ae2c-c7003978a2b3 fallback: original post_id: f3b199f3-XXXX-YYYY-82c8-143260a8fa75 score: 0.6274336283185841 sports: - Lacrosse - coach_id: 9b7c89ef-XXXX-YYYY-ae2c-c7003978a2b4 fallback: original post_id: a1b2c3d4-XXXX-YYYY-82c8-143260a8fa76 score: 0.5891234567890123 sports: - Basketball - coach_id: a8b9c0d1-XXXX-YYYY-ae2c-c7003978a2b5 fallback: original post_id: b2c3d4e5-XXXX-YYYY-82c8-143260a8fa77 score: 0.543210987654321 sports: - Soccer - coach_id: b9c0d1e2-XXXX-YYYY-ae2c-c7003978a2b6 fallback: original post_id: c3d4e5f6-XXXX-YYYY-82c8-143260a8fa78 score: 0.4987654321098765 sports: - Tennis - coach_id: c0d1e2f3-XXXX-YYYY-ae2c-c7003978a2b7 fallback: original post_id: d4e5f6g7-XXXX-YYYY-82c8-143260a8fa79 score: 0.4567890123456789 sports: - Swimming user_id: 4cedfba7-XXXX-YYYY-b48e-33b912b84b7d RecommendationType: type: string enum: - coach - athlete - user title: RecommendationType