API docs by Redocly

FastAPI Recommendation System (1.0.0)

Download OpenAPI specification:

FastAPI Recommendation System API

recommendations

Get recommendations

✨ Retrieve personalized recommendations for a user based on the type parameter (defaults to user if not provided)

path Parameters
user_id
required
string (User Id)

The user ID to get recommendations for

query Parameters
top_k
integer (Top K) [ 1 .. 10 ]
Default: 10

Number of recommendations to return (1-10, default: 10)

type
string (RecommendationType)
Default: "user"
Enum: "coach" "athlete" "user"

Type of recommendations: user (default), coach, or athlete

Responses

Response Schema: application/json
property name*
additional property
any

Response samples

Content type
application/json
{
  • "user_id": "5563086a-6465-4608-8afa-3b700f8c9107",
  • "recommendations": [
    • {
      • "score": 0.691477463949316,
      • "sports": [
        ],
      • "coach_id": "14a33d13-334e-4424-b3b1-5afbf8017391",
      • "service_id": "96fc9bf7-385d-4188-bf88-d5baf3846f6f"
      }
    ]
}

Get Feed Recommendations

✨ 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

path Parameters
user_id
required
string (User Id)

The user ID to get feed recommendations for

query Parameters
top_k
integer (Top K) [ 1 .. 100 ]
Default: 5

Number of recommendations to return and remove (1-100, default: 5)

Responses

Response Schema: application/json
Any of
property name*
additional property
any

Response samples

Content type
application/json
{
  • "user_id": "4cedfba7-XXXX-YYYY-b48e-33b912b84b7d",
  • "recommendations": [
    • {
      • "score": 0.6274336283185841,
      • "sports": [
        ],
      • "post_id": "f3b199f3-XXXX-YYYY-82c8-143260a8fa75",
      • "coach_id": "8a6c78dd-XXXX-YYYY-ae2c-c7003978a2b3",
      • "fallback": "original"
      },
    • {
      • "score": 0.5891234567890123,
      • "sports": [
        ],
      • "post_id": "a1b2c3d4-XXXX-YYYY-82c8-143260a8fa76",
      • "coach_id": "9b7c89ef-XXXX-YYYY-ae2c-c7003978a2b4",
      • "fallback": "original"
      }
    ]
}

Get Groups Recommendations

✨ 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

path Parameters
user_id
required
string (User Id)

The user ID to get groups recommendations for

query Parameters
top_k
integer (Top K) [ 1 .. 10 ]
Default: 10

Number of recommendations to return (1-10, default: 10)

Responses

Response Schema: application/json
Any of
property name*
additional property
any

Response samples

Content type
application/json
{
  • "user_id": "4cedfba7-XXXX-YYYY-b48e-33b912b84b7d",
  • "recommendations": [
    • {
      • "fallback": "no geolocation",
      • "group_id": "0d4bef05-4b33-44f7-b888-4fab428dd20e",
      • "total_score": 0.4100000000000001
      }
    ]
}

health

Health Check

✨ Check the health status of the application

Responses

Response Schema: application/json
any

Response samples

Content type
application/json
{
  • "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"
    }
}