Recommendations API

Get Personalized Recommendations

Generate personalized product recommendations based on customer data and behavior.

Endpoint

POST /api/recommend/recommend

Authentication

Required: JWT Bearer token

Request Body

{
  "sequence_data": {
    "customer_preferences": {
      "categories": ["electronics", "books"],
      "price_range": {
        "min": 50,
        "max": 500
      }
    },
    "browsing_history": ["product_123", "product_456"],
    "purchase_history": ["product_789"]
  },
  "task": "product_recommendation",
  "template": "personalized"
}

Request Parameters

Parameter	Type	Required	Description
sequence_data	object	Yes	Customer data including preferences, history, and context
task	string	Yes	The recommendation task type (e.g., "product_recommendation")
template	string	Yes	Recommendation template to use (e.g., "personalized", "trending")

Response

{
  "status_code": 200,
  "results": [
    {
      "recommendation_id": 124,
      "score": 0.9,
      "rank": 1
    },
    {
      "recommendation_id": 125,
      "score": 0.89,
      "rank": 2
    }
  ]
}

Response Fields

Field	Type	Description
status_code	integer	HTTP status code
results	array	List of recommendation objects
recommendation_id	integer	Unique identifier for the recommendation
score	float	Confidence score (0.0 - 1.0)
rank	integer	Recommendation ranking

Error Responses

400 Bad Request

{
  "detail": "Invalid request parameters"
}

401 Unauthorized

{
  "detail": "Invalid authentication credentials"
}

500 Internal Server Error

{
  "detail": "Failed to get recommendations"
}

Example Usage

curl -X POST "http://localhost:5051/api/recommend/recommend" \
  -H "Authorization: Bearer <jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "sequence_data": {
      "customer_preferences": {
        "categories": ["electronics"]
      }
    },
    "task": "product_recommendation",
    "template": "personalized"
  }'

Process Flow

1. Authentication: JWT token is validated
2. Sequence Logging: Customer interaction is logged for analytics
3. Recommendation Generation: External recommendation service is called
4. Decision Logging: Recommendation results are stored
5. Response: Personalized recommendations are returned

The API automatically logs all recommendation requests and responses for analytics and improvement purposes.