# Generate AI-driven course recommendations

Generate personalized course recommendations using AI that considers the user's
        learning history, organizational goals, and available courses.

        Authentication Required:
        - User must be authenticated
        - Platform key must be provided
        - User must have access to the specified platform

        How It Works:
        1. Fetches tenant's custom recommendation prompt (if configured)
        2. Analyzes user's course completion history and performance
        3. Reviews available course catalog
        4. Uses AI to match courses to user's needs and organizational goals
        5. Returns 3-5 courses with clear explanations

        Tenant Prompts:
        Each organization can configure custom prompts that guide recommendations.
        For example: "Prioritize leadership for sales roles" or "Focus on technical skills."

        Use Cases:
        - Manual recommendation requests by users
        - Post-assessment recommendations
        - Milestone-triggered suggestions
        - Learning path planning

Endpoint: GET /api/ai-search/recommendations/
Version: 4.84.1-ai-plus
Security: PlatformApiKeyAuthentication

## Query parameters:

  - `assessment_id` (string)
    Assessment ID if triggered by assessment completion

  - `context_type` (string)
    Context type for recommendation (e.g., 'assessment_completed', 'milestone_reached')

  - `difficulty_levels` (string)
    Filter recommendations to specific difficulty levels (CSV)

  - `domains` (string)
    Filter recommendations to specific domains (CSV)

  - `include_main_catalog` (boolean)
    Include items from 'main' tenant catalog IN ADDITION TO platform-specific catalog. By default, only platform-specific data is returned (tenant isolation). Set to True to also include shared 'main' tenant resources.

  - `include_user_history` (boolean)
    Include user's learning history (completed courses, topics) in the RAG search query. Helps find content that builds on their background.

  - `include_user_skills` (boolean)
    Include user's skills and badges in the RAG search query. Helps personalize results based on what the user already knows.

  - `k` (integer)
    Number of similar items to retrieve via RAG per tenant (before filtering). Higher values give more options but may be slower.

  - `limit` (integer)
    Number of course recommendations to return (max 20)

  - `page` (integer)
    Page number for pagination (starts at 1)

  - `page_size` (integer)
    Number of recommendations per page (max 100)

  - `platform_key` (string)
    Platform key for tenant-scoped recommendations

  - `platform_org` (string,null)
    Platform org identifier (optional - avoids database lookup if provided)

  - `ranking_prompt` (string)
    Custom prompt for LLM ranking (only if ranking_strategy='custom'). Define how the LLM should evaluate and order the recommendations.

  - `ranking_strategy` (string)
    Strategy for LLM ranking. Only used if use_llm_ranking=True.

* relevance - Rank by relevance and value (default)
* difficulty - Rank by difficulty progression
* personalized - Personalize to user context and goals
* custom - Use custom ranking prompt
    Enum: "relevance", "difficulty", "personalized", "custom"

  - `recommendation_type` (string)
    Type of resource to recommend. Catalog types (courses/programs/resources/pathways) will use the platform's 'catalog' prompt category if configured.

* mentors - Mentor Recommendations
* courses - Course Recommendations
* programs - Program Recommendations
* resources - Resource Recommendations
* pathways - Pathway Recommendations
    Enum: "mentors", "courses", "programs", "resources", "pathways"

  - `search_terms` (string)
    Search terms to find similar content (e.g., 'leadership', 'data science'). Used to build the RAG query.

  - `spa_url` (string)
    Frontend/SPA identifier (e.g., 'catalog.example.com', 'mentor-ai.ibl.com'). Used to retrieve the correct prompt for that specific frontend. Auto-detected from HTTP_REFERER if not provided.

  - `trigger_source` (string)
    What triggered this recommendation request

  - `use_llm_ranking` (boolean)
    Use LLM to rank and personalize RAG results. Adds AI-generated reasoning but increases cost and latency. Only applies if use_rag_search=True.

  - `use_rag_search` (boolean)
    Use RAG similarity search instead of full LLM catalog review. Faster and more cost-effective. Set to False for legacy LLM-only behavior.

## Response 200 fields (application/json):

  - `recommendations` (array, required)
    List of course recommendations with reasoning

  - `recommendations.course_id` (string, required)
    The ID of the recommended course

  - `recommendations.course_title` (string, required)
    The title of the recommended course

  - `recommendations.reason` (string, required)
    AI-generated explanation for why this course is recommended

  - `recommendations.domain` (string,null)
    Course domain/subject area

  - `recommendations.difficulty_level` (string,null)
    Course difficulty level

  - `recommendations.estimated_hours` (number,null)
    Estimated hours to complete

  - `recommendations.confidence_score` (number,null)
    AI confidence in this recommendation (0-1)

  - `recommendations.platform_key` (string,null)
    Platform/tenant key this course belongs to (extracted from course_id or metadata)

  - `recommendations.description` (string,null)
    Course description (priority: description > short_description > overview with HTML stripped)

  - `recommendations.short_description` (string,null)
    Course short description from edx_data

  - `user_context` (object)
    Summary of user context used for recommendations

  - `recommendation_id` (string)
    Unique ID for this recommendation set (for tracking)

  - `generated_at` (string, required)
    When these recommendations were generated

  - `platform_key` (string, required)
    Platform key for these recommendations

  - `method_used` (string)
    Method used to generate recommendations: 'rag_only', 'llm_only', or 'rag_plus_llm'

  - `search_query_used` (string)
    The actual search query used for RAG similarity search (if applicable)

  - `candidates_retrieved` (integer)
    Number of candidates retrieved via RAG before filtering (if applicable)

  - `includes_main_catalog` (boolean)
    Whether the results include items from the 'main' tenant catalog

  - `processing_time_seconds` (number)
    Time taken to generate recommendations (in seconds)

  - `success` (boolean)
    Whether the request was successful

  - `count` (integer)
    Total number of recommendations available

  - `next` (string,null)
    URL for the next page of results (if pagination is enabled)

  - `previous` (string,null)
    URL for the previous page of results (if pagination is enabled)


## Response 400 fields

## Response 401 fields

## Response 500 fields