Install our app for a better experience!
Guide Beginner 5 min read

Teacher Feedback Evaluation API

Last updated Oct 28, 2025

Teacher Feedback Evaluation API Documentation

Overview

The Teacher Feedback Evaluation API allows clients to submit teacher feedback in bulk, trigger AI-powered evaluations using custom rubrics, and generate comprehensive reports without manual intervention through the web interface.

Base URL: https://preparebuddy.com/assessment/api/

Prerequisites

Before using the API, ensure you have:

  1. Valid User Account - A registered account on the platform
  2. Organization Membership - You must be a member of an organization with one of these roles:
  3. Admin - Full organization access and evaluation capabilities
  4. Examiner - Can create evaluations and manage assessments
  5. Super Admin - Platform-wide access to all organizations
  6. Active Membership Status - Your organization membership must be active
  7. Rubric Access - Access to evaluation rubrics in your organization

Note: If you don't meet these requirements, contact your organization administrator to: - Add you to an organization - Grant you the appropriate role (admin or examiner) - Activate your membership

Key Features

  • 🔐 Secure Authentication - Token-based auth with organization scoping
  • 📝 Bulk Feedback Submission - Submit multiple teacher feedbacks at once
  • ⚙️ Custom Rubric Evaluation - Use your organization's evaluation rubrics
  • 🤖 AI-Powered Analysis - Leverage existing AI evaluation capabilities with optional RAG support
  • 🧠 RAG Configuration - Enhanced evaluation quality using reference examples and similarity matching
  • 📧 Auto-Email on Completion - Automatic email delivery when evaluation finishes
  • 📊 Comprehensive Reports - Generate PDF/Word/CSV/JSON reports with complete detailed analytics matching the web interface
  • 🏢 Organization Management - Multi-tenant support with access control
  • 📈 Synchronous Processing - Real-time evaluation completion (1-3 minutes)
  • 🎨 HTML Content Support - Full rich text formatting from CKEditor
  • 🏷️ Flexible Metadata - Add unlimited custom metadata fields

Authentication

Get Authentication Token

Endpoint: POST /auth/token/

Request:

{
    "username": "your_username",
    "password": "your_password"
}

Response:

{
    "success": true,
    "message": "Authentication successful. Use the 'token' field value as your Bearer token for all API requests.",
    "token": "abc123def456session789...",
    "user_id": 42,
    "username": "your_username",
    "email": "you@example.com",
    "organizations": [
        {
            "id": 1,
            "name": "University Teaching Department",
            "role": "admin"
        }
    ]
}

Usage: Use the token value as your Bearer token in subsequent requests:

Authorization: Bearer abc123def456session789...

Important Notes: - The token field contains your authentication token (Django session key) - Tokens expire after 4 hours of inactivity (automatically renewed on each request) - Store tokens securely and never commit them to version control - Re-authenticate when you receive a "Token expired" error - You must have organization membership with admin, examiner, or super_admin role

Error Responses:

If you don't have the required organization membership:

{
    "error": "Access denied. API access requires organization membership with admin, examiner, or super_admin role.",
    "hint": "Contact your organization administrator to be added to an organization with the appropriate role."
}

API Endpoints

1. Organization Management

List Organizations

Endpoint: GET /organizations/

Response:

{
    "organizations": [
        {
            "id": 1,
            "name": "University Teaching Department",
            "role": "admin",
            "created_at": "2024-01-15T10:30:00Z"
        }
    ]
}

List Rubrics

Endpoint: GET /rubrics/

Parameters: - organization_id (optional): Filter by organization

Response:

{
    "rubrics": [
        {
            "id": 1,
            "name": "General Teaching Feedback Rubric",
            "description": "Standard rubric for evaluating teaching feedback quality",
            "total_possible_points": 100,
            "criteria": [
                {
                    "id": 1,
                    "name": "Clarity of Comments",
                    "description": "How clear and understandable are the feedback comments?",
                    "max_points": 25,
                    "criterion_type": "score"
                },
                {
                    "id": 2,
                    "name": "Constructive Suggestions",
                    "description": "Does feedback provide actionable improvement suggestions?",
                    "max_points": 25,
                    "criterion_type": "score"
                }
            ],
            "created_at": "2024-01-10T09:15:00Z"
        }
    ]
}

2. Feedback Management

Submit Bulk Feedback

Endpoint: POST /feedbacks/bulk/

This is the core endpoint for submitting multiple teacher feedbacks for evaluation.

Request:

{
    "organization_id": 1,
    "feedbacks": [
        {
            "title": "Math Assignment 1 Feedback",
            "feedback_content": "<h3>Overall Assessment</h3><p>Student demonstrates <strong>strong understanding</strong> of algebraic concepts. The solution approach is methodical and well-structured.</p><h4>Areas for Improvement</h4><ul><li>Computational errors in steps 3-4</li><li>Need to review basic arithmetic operations</li></ul><p><em>Overall excellent work with room for improvement in accuracy.</em></p>",
            "teacher_name": "Dr. Sarah Johnson",
            "teacher_experience_level": "experienced",
            "assessment_type": "essay",
            "student_level": "Undergraduate Year 2",
            "subject_area": "Mathematics",
            "student_context": "Student received B+ grade, Second attempt after revision",
            "criteria_addressed": ["problem_solving", "communication", "accuracy"],
            "extraction_metadata": {
                "course_info": {
                    "course_id": "MATH101",
                    "assignment_number": 1,
                    "semester": "Spring 2024"
                },
                "grading_context": {
                    "grading_date": "2024-01-20T15:30:00Z",
                    "time_spent_minutes": 15
                },
                "custom_tags": ["needs_followup", "computational_errors"]
            }
        },
        {
            "title": "English Essay Feedback",
            "feedback_content": "<h3>Literary Analysis Assessment</h3><p><strong>Excellent thesis development</strong> and supporting arguments. The essay structure is clear and logical.</p><h4>Strengths:</h4><ul><li>Grammar and vocabulary usage show strong command</li><li>Effective conclusion that summarizes key points</li></ul><h4>Suggestions:</h4><ol><li>Vary sentence structure more</li><li>Include additional scholarly sources</li></ol><p style='color: #2E8B57;'><strong>Grade: A- (92%)</strong></p>",
            "teacher_name": "Prof. Michael Chen",
            "teacher_experience_level": "expert",
            "assessment_type": "essay",
            "student_level": "Graduate",
            "subject_area": "English Literature",
            "criteria_addressed": ["thesis_development", "argument_structure", "writing_quality"],
            "extraction_metadata": {
                "academic_context": {
                    "program": "MA English Literature",
                    "course_code": "ENG501"
                }
            }
        }
    ]
}

Response:

{
    "message": "Successfully created 2 feedbacks",
    "feedbacks": [
        {
            "id": 101,
            "title": "Math Assignment 1 Feedback",
            "teacher_name": "Dr. Sarah Johnson",
            "word_count": 52
        },
        {
            "id": 102,
            "title": "English Essay Feedback", 
            "teacher_name": "Prof. Michael Chen",
            "word_count": 47
        }
    ]
}

List Feedbacks

Endpoint: GET /feedbacks/

Parameters: - organization_id (optional): Filter by organization - limit (default: 50): Number of results per page - offset (default: 0): Pagination offset

Response:

{
    "feedbacks": [
        {
            "id": 101,
            "title": "Math Assignment 1 Feedback",
            "teacher_name": "Dr. Sarah Johnson",
            "assessment_type": "essay",
            "student_level": "Undergraduate Year 2",
            "subject_area": "Mathematics",
            "word_count": 52,
            "created_at": "2024-01-20T14:30:00Z"
        }
    ],
    "pagination": {
        "limit": 50,
        "offset": 0,
        "has_more": false
    }
}

3. Batch Evaluation

Create Batch Evaluation

Endpoint: POST /batches/create/

Create a batch evaluation to assess multiple feedbacks using a specific rubric. Optionally enable RAG (Retrieval-Augmented Generation) for enhanced evaluation quality.

Request (Basic):

{
    "name": "Weekly Feedback Quality Review - Jan 2024",
    "description": "Evaluating teacher feedback quality for math and english assignments",
    "rubric_id": 1,
    "organization_id": 1,
    "feedback_ids": [101, 102, 103, 104],
    "evaluation_focus": "Focus on constructive feedback quality and actionable suggestions",
    "international_standards": ["APA", "Cambridge Assessment Guidelines"]
}

Request (With RAG Support):

{
    "name": "Weekly Feedback Quality Review - Jan 2024",
    "description": "Evaluating teacher feedback quality for math and english assignments",
    "rubric_id": 1,
    "organization_id": 1,
    "feedback_ids": [101, 102, 103, 104],
    "evaluation_focus": "Focus on constructive feedback quality and actionable suggestions",
    "evaluation_instructions": "Pay special attention to specific, actionable recommendations",
    "use_reference_matching": true,
    "reference_matching_mode": "dynamic",
    "reference_detail_level": "detailed",
    "max_references": 5
}

RAG Parameters: - use_reference_matching (boolean, default: false) - Enable RAG to find similar reference examples - reference_matching_mode (string, default: "dynamic") - "static" (use fixed examples) or "dynamic" (similarity-based matching) - reference_detail_level (string, default: "summary") - "summary" or "detailed" analysis depth - max_references (integer, default: 5) - Maximum number of reference examples to use (1-10) - evaluation_instructions (string, optional) - Additional context or instructions for the AI evaluator

Response:

{
    "message": "Batch evaluation created successfully",
    "batch": {
        "id": 25,
        "name": "Weekly Feedback Quality Review - Jan 2024",
        "status": "pending",
        "total_feedbacks": 4,
        "created_at": "2024-01-20T15:00:00Z",
        "rag_configuration": {
            "use_reference_matching": true,
            "reference_matching_mode": "dynamic",
            "reference_detail_level": "detailed",
            "max_references": 5
        }
    }
}

Run Batch Evaluation

Endpoint: POST /batches/{batch_id}/run/

Trigger the evaluation process for a batch.

⚠️ Important: This endpoint processes evaluations synchronously and blocks until completion (typically 1-3 minutes depending on feedback count). If send_email_on_completion is enabled, the email will be sent automatically before the endpoint returns.

Response (Synchronous - After Completion):

{
    "message": "Evaluation completed successfully",
    "batch_id": 25,
    "status": "completed"
}

Note: The response is returned only after all feedbacks have been evaluated. If auto-email is configured, emails are sent before this response is returned.

Check Batch Status

Endpoint: GET /batches/{batch_id}/status/

Monitor the progress of batch evaluation.

Response (Processing):

{
    "batch": {
        "id": 25,
        "name": "Weekly Feedback Quality Review - Jan 2024",
        "status": "processing",
        "total_feedbacks": 4,
        "completed_at": null,
        "created_at": "2024-01-20T15:00:00Z"
    },
    "results": []
}

Response (Completed):

{
    "batch": {
        "id": 25,
        "name": "Weekly Feedback Quality Review - Jan 2024",
        "status": "completed",
        "total_feedbacks": 4,
        "completed_at": "2024-01-20T15:45:00Z",
        "created_at": "2024-01-20T15:00:00Z"
    },
    "results": [
        {
            "id": 201,
            "feedback_title": "Math Assignment 1 Feedback",
            "teacher_name": "Dr. Sarah Johnson",
            "overall_score": 78.5,
            "percentage": 78.5,
            "created_at": "2024-01-20T15:42:00Z"
        },
        {
            "id": 202,
            "feedback_title": "English Essay Feedback",
            "teacher_name": "Prof. Michael Chen", 
            "overall_score": 92.0,
            "percentage": 92.0,
            "created_at": "2024-01-20T15:43:00Z"
        }
    ]
}

List Batches

Endpoint: GET /batches/

Parameters: - organization_id (optional): Filter by organization - status (optional): Filter by status (pending, processing, completed, failed)

4. Report Generation

Generate Batch Report

Endpoint: GET /batches/{batch_id}/report/

Generate comprehensive evaluation reports in multiple formats using your existing reporting system.

Parameters: - format: Report format (default: pdf) - pdf - Comprehensive PDF report with charts and detailed analysis - docx or word - Microsoft Word document with full formatting - csv - Detailed CSV with all evaluation data and statistics - json - Structured JSON for programmatic use

PDF Report (Default)

Request: GET /batches/25/report/ or GET /batches/25/report/?format=pdf

Response: Professional PDF document including: - Executive summary with overall statistics - Score distribution charts and visualizations - Individual teacher performance analysis - Criterion-level performance breakdown - Detailed feedback for each evaluation - Recommendations and improvement areas - Batch metadata and evaluation context

Word Document Report

Request: GET /batches/25/report/?format=docx or GET /batches/25/report/?format=word

Response: Microsoft Word document with: - Same comprehensive content as PDF - Editable format for further customization - Professional formatting and styling - Embedded charts and tables - Table of contents with navigation

CSV Report

Request: GET /batches/25/report/?format=csv

Response: Comprehensive CSV file including: - Batch information and metadata - Summary statistics (average, min, max scores) - Score distribution breakdown - Teacher performance comparison matrix - Individual evaluation details: - Feedback ID, Title, Teacher Name, Experience Level - Assessment Type, Student Level, Subject Area - Overall Score, Percentage, Grade - Individual criterion scores - Strengths and improvement areas - Evaluation timestamp

JSON Report (Complete Detailed Feedback)

Request: GET /batches/25/report/?format=json

Response: Complete detailed evaluation data matching the web interface - includes all the same comprehensive feedback, AI analysis, criterion breakdowns, strengths, recommendations, and performance insights shown on the batch detail page:

{
    "batch": {
        "id": 25,
        "name": "Weekly Feedback Quality Review - Jan 2024",
        "description": "Evaluating teacher feedback quality...",
        "status": "completed",
        "total_feedbacks": 4,
        "completed_at": "2024-01-20T15:45:00Z"
    },
    "rubric": {
        "id": 1,
        "name": "General Teaching Feedback Rubric",
        "total_possible_points": 100
    },
    "results": [
        {
            "feedback": {
                "id": 101,
                "title": "Math Assignment 1 Feedback",
                "teacher_name": "Dr. Sarah Johnson",
                "teacher_experience_level": "experienced",
                "assessment_type": "essay",
                "student_level": "Undergraduate Year 2",
                "subject_area": "Mathematics",
                "word_count": 52,
                "created_at": "2024-01-20T14:30:00Z"
            },
            "evaluation": {
                "overall_score": 78.5,
                "percentage": 78.5,
                "criterion_scores": {
                    "clarity_of_comments": 20,
                    "constructive_suggestions": 18,
                    "specific_examples": 22,
                    "encouragement": 18.5
                },
                "criterion_feedback": {
                    "clarity_of_comments": "Feedback is clear and well-structured...",
                    "constructive_suggestions": "Provides actionable suggestions..."
                },
                "strengths": [
                    "Clear identification of student strengths",
                    "Specific examples provided",
                    "Constructive tone maintained"
                ],
                "areas_for_improvement": [
                    "Could provide more detailed explanations",
                    "Suggestions could be more specific"
                ],
                "specific_recommendations": [
                    "Include more examples of correct approaches",
                    "Provide resources for improvement"
                ],
                "overall_feedback": "Complete AI-generated analysis text with detailed insights...",
                "consistency_notes": "Analysis of consistency with other feedback...",
                "ai_analysis": {
                    "raw_response": "Complete AI analysis matching web interface...",
                    "standards_applied": ["APA", "Educational Standards"],
                    "evaluation_method": "rubric_based"
                },
                "performance_level": "Good",
                "evaluated_at": "2024-01-20T15:42:00Z"
            }
        }
    ],
    "summary": {
        "average_score": 85.25,
        "average_percentage": 85.25,
        "score_distribution": {
            "excellent": 2,
            "good": 1,
            "satisfactory": 1,
            "needs_improvement": 0
        }
    }
}

Batch Summary Report

Endpoint: GET /batches/{batch_id}/summary/

Get a quick statistical summary of batch evaluation results.

Response:

{
    "summary": {
        "batch_id": 25,
        "batch_name": "Weekly Feedback Review",
        "total_feedbacks": 15,
        "rubric_name": "General Teaching Feedback Rubric",
        "total_possible_points": 100,
        "statistics": {
            "average_score": 82.5,
            "average_percentage": 82.5,
            "max_score": 95.0,
            "min_score": 68.0,
            "score_distribution": {
                "excellent": 3,
                "good": 8,
                "satisfactory": 3,
                "needs_improvement": 1
            }
        },
        "criterion_performance": {
            "1": {
                "name": "Clarity of Comments",
                "average_score": 20.5,
                "evaluations": 15
            },
            "2": {
                "name": "Constructive Suggestions",
                "average_score": 21.0,
                "evaluations": 15
            }
        }
    }
}

Download Individual Result

Endpoint: GET /batches/{batch_id}/results/{result_id}/download/

Download a specific teacher's evaluation from a batch.

Parameters: - format: Download format (pdf, docx, word, json)

Examples: - GET /batches/25/results/201/download/?format=pdf - Visual PDF report - GET /batches/25/results/201/download/?format=json - Complete detailed data matching web interface

JSON Format Response (Complete Detail): Returns the same comprehensive evaluation data shown on the web interface, including: - Complete AI analysis and overall feedback - Detailed criterion-by-criterion scores and feedback - Comprehensive strengths, areas for improvement, and specific recommendations - Consistency analysis and performance level assessment - All metadata and evaluation context

PDF/Word Format Response: Visual reports with formatted presentation including: - Teacher information and feedback details - Individual criterion scores with detailed feedback - Strengths and areas for improvement - Specific recommendations - Visual score representation

5. Email Management

Send Individual Evaluation Email

Endpoint: POST /evaluations/{evaluation_id}/email/

Send evaluation results to a teacher via email with PDF/Word/CSV attachments.

Request:

{
    "email_address": "teacher@university.edu",
    "include_pdf": true,
    "include_docx": true,
    "include_csv": false,
    "custom_message": "Please review your evaluation results."
}

Response:

{
    "success": true,
    "message": "Email sent successfully",
    "email_details": {
        "recipient": "teacher@university.edu",
        "attachments": ["pdf", "docx"],
        "sent_at": "2024-01-20T16:30:00Z"
    }
}

Send Batch Evaluation Emails

Endpoint: POST /batches/{batch_id}/email/

Send evaluation results to all teachers in a batch via email.

Request:

{
    "use_batch_preferences": true,
    "override_settings": {
        "include_pdf": true,
        "include_docx": true,
        "include_csv": false
    },
    "custom_message": "Your evaluation results are attached."
}

Response:

{
    "success": true,
    "message": "Batch emails sent successfully",
    "email_summary": {
        "total_sent": 15,
        "successful": 14,
        "failed": 1,
        "failed_emails": ["missing-email@unknown.com"],
        "sent_at": "2024-01-20T16:45:00Z"
    }
}

Configure Batch Auto-Email Settings

Endpoint: POST /batches/{batch_id}/email/configure/

Configure automatic email settings for a batch.

Request:

{
    "auto_email_enabled": true,
    "email_format_preferences": "pdf_docx",
    "manual_email_recipient": "teacher@university.edu"
}

Email Format Options: - pdf_only - PDF Only - docx_only - Word Document Only
- pdf_docx - PDF and Word Document (default) - all_formats - PDF, Word Document, and CSV

Response:

{
    "success": true,
    "message": "Auto-email settings updated",
    "settings": {
        "auto_email_enabled": true,
        "email_format_preferences": "pdf_docx",
        "manual_email_recipient": "teacher@university.edu",
        "updated_at": "2024-01-20T17:00:00Z"
    }
}

Get Batch Email Status

Endpoint: GET /batches/{batch_id}/email/status/

Get email configuration and capability status for a batch.

Response:

{
    "batch": {
        "id": 25,
        "name": "Weekly Feedback Review - Jan 2024",
        "auto_email_enabled": true,
        "email_format_preferences": "pdf_docx",
        "manual_email_recipient": "teacher@university.edu"
    },
    "email_capabilities": {
        "smtp_configured": true,
        "organization_smtp": true,
        "default_smtp": true,
        "can_send_emails": true
    },
    "recent_activity": {
        "last_auto_email": "2024-01-20T16:45:00Z",
        "emails_sent_today": 5,
        "total_emails_sent": 127
    }
}

Usage Examples

Python Example

import requests
import json

class TeacherFeedbackAPI:
    def __init__(self, base_url, username, password):
        self.base_url = base_url
        self.session = requests.Session()
        self.authenticate(username, password)

    def authenticate(self, username, password):
        """Get authentication token"""
        response = self.session.post(f"{self.base_url}/auth/token/", 
            json={"username": username, "password": password})

        if response.status_code == 200:
            data = response.json()
            self.session.headers.update({
                'Authorization': f'Bearer {data["token"]}'
            })
            self.organizations = data["organizations"]
            print(f"Authenticated as {data['username']}")
        else:
            raise Exception(f"Authentication failed: {response.text}")

    def submit_bulk_feedback(self, organization_id, feedbacks):
        """Submit multiple feedbacks for evaluation"""
        data = {
            "organization_id": organization_id,
            "feedbacks": feedbacks
        }

        response = self.session.post(f"{self.base_url}/feedbacks/bulk/", 
                                   json=data)

        if response.status_code == 201:
            return response.json()
        else:
            raise Exception(f"Failed to submit feedbacks: {response.text}")

    def create_batch_evaluation(self, name, rubric_id, organization_id, feedback_ids):
        """Create a batch evaluation"""
        data = {
            "name": name,
            "rubric_id": rubric_id,
            "organization_id": organization_id,
            "feedback_ids": feedback_ids,
            "evaluation_focus": "Standard quality assessment",
            "international_standards": ["APA"]
        }

        response = self.session.post(f"{self.base_url}/batches/create/", 
                                   json=data)

        if response.status_code == 201:
            return response.json()["batch"]
        else:
            raise Exception(f"Failed to create batch: {response.text}")

    def run_batch_evaluation(self, batch_id):
        """Start batch evaluation processing"""
        response = self.session.post(f"{self.base_url}/batches/{batch_id}/run/")

        if response.status_code == 200:
            return response.json()
        else:
            raise Exception(f"Failed to run batch: {response.text}")

    def check_batch_status(self, batch_id):
        """Check batch evaluation status"""
        response = self.session.get(f"{self.base_url}/batches/{batch_id}/status/")

        if response.status_code == 200:
            return response.json()
        else:
            raise Exception(f"Failed to get status: {response.text}")

    def download_report(self, batch_id, format_type="pdf"):
        """Download batch evaluation report"""
        response = self.session.get(
            f"{self.base_url}/batches/{batch_id}/report/",
            params={"format": format_type}
        )

        if response.status_code == 200:
            return response.content
        else:
            raise Exception(f"Failed to download report: {response.text}")

    def get_batch_summary(self, batch_id):
        """Get quick summary statistics"""
        response = self.session.get(f"{self.base_url}/batches/{batch_id}/summary/")

        if response.status_code == 200:
            return response.json()
        else:
            raise Exception(f"Failed to get summary: {response.text}")

    def download_individual_result(self, batch_id, result_id, format_type="pdf"):
        """Download individual teacher evaluation"""
        response = self.session.get(
            f"{self.base_url}/batches/{batch_id}/results/{result_id}/download/",
            params={"format": format_type}
        )

        if response.status_code == 200:
            return response.content
        else:
            raise Exception(f"Failed to download result: {response.text}")

    def send_individual_email(self, evaluation_id, email_address, 
                            include_pdf=True, include_docx=True, include_csv=False, 
                            custom_message=None):
        """Send individual evaluation email"""
        data = {
            "email_address": email_address,
            "include_pdf": include_pdf,
            "include_docx": include_docx,
            "include_csv": include_csv
        }
        if custom_message:
            data["custom_message"] = custom_message

        response = self.session.post(
            f"{self.base_url}/evaluations/{evaluation_id}/email/",
            json=data
        )

        if response.status_code == 200:
            return response.json()
        else:
            raise Exception(f"Failed to send email: {response.text}")

    def send_batch_emails(self, batch_id, use_batch_preferences=True, 
                         override_settings=None, custom_message=None):
        """Send emails for all evaluations in a batch"""
        data = {"use_batch_preferences": use_batch_preferences}

        if override_settings:
            data["override_settings"] = override_settings
        if custom_message:
            data["custom_message"] = custom_message

        response = self.session.post(
            f"{self.base_url}/batches/{batch_id}/email/",
            json=data
        )

        if response.status_code == 200:
            return response.json()
        else:
            raise Exception(f"Failed to send batch emails: {response.text}")

    def configure_batch_auto_email(self, batch_id, auto_email_enabled, 
                                 email_format_preferences="pdf_docx", 
                                 manual_email_recipient=None):
        """Configure automatic email settings for a batch"""
        data = {
            "auto_email_enabled": auto_email_enabled,
            "email_format_preferences": email_format_preferences
        }
        if manual_email_recipient:
            data["manual_email_recipient"] = manual_email_recipient

        response = self.session.post(
            f"{self.base_url}/batches/{batch_id}/email/configure/",
            json=data
        )

        if response.status_code == 200:
            return response.json()
        else:
            raise Exception(f"Failed to configure auto-email: {response.text}")

    def get_batch_email_status(self, batch_id):
        """Get email status and configuration for a batch"""
        response = self.session.get(f"{self.base_url}/batches/{batch_id}/email/status/")

        if response.status_code == 200:
            return response.json()
        else:
            raise Exception(f"Failed to get email status: {response.text}")

# Usage Example
if __name__ == "__main__":
    # Initialize API client
    api = TeacherFeedbackAPI(
        base_url="https://preparebuddy.com/assessment/api",
        username="your_username", 
        password="your_password"
    )

    # Prepare feedback data
    feedbacks = [
        {
            "title": "Assignment 1 Feedback",
            "feedback_content": "Excellent work on the mathematical concepts...",
            "teacher_name": "Dr. Smith",
            "teacher_experience_level": "experienced",
            "assessment_type": "essay",
            "student_level": "Undergraduate",
            "subject_area": "Mathematics"
        }
    ]

    # Submit feedbacks
    org_id = api.organizations[0]["id"]
    submission_result = api.submit_bulk_feedback(org_id, feedbacks)
    print(f"Submitted {len(submission_result['feedbacks'])} feedbacks")

    # Create batch evaluation
    feedback_ids = [f["id"] for f in submission_result["feedbacks"]]
    batch = api.create_batch_evaluation(
        name="API Test Batch",
        rubric_id=1,
        organization_id=org_id,
        feedback_ids=feedback_ids
    )
    print(f"Created batch: {batch['name']}")

    # Run evaluation
    run_result = api.run_batch_evaluation(batch["id"])
    print(f"Started evaluation: {run_result['status']}")

    # Monitor progress
    import time
    while True:
        status = api.check_batch_status(batch["id"])
        print(f"Status: {status['batch']['status']}")

        if status['batch']['status'] == 'completed':
            break
        elif status['batch']['status'] == 'failed':
            print("Evaluation failed!")
            break

        time.sleep(30)  # Check every 30 seconds

    # Get summary first
    summary = api.get_batch_summary(batch["id"])
    print(f"Average score: {summary['summary']['statistics']['average_score']}")

    # Download different report formats
    # PDF Report (comprehensive with charts)
    pdf_report = api.download_report(batch["id"], "pdf")
    with open(f"batch_report_{batch['id']}.pdf", "wb") as f:
        f.write(pdf_report)
    print("PDF report downloaded")

    # Word Document (editable)
    docx_report = api.download_report(batch["id"], "docx")
    with open(f"batch_report_{batch['id']}.docx", "wb") as f:
        f.write(docx_report)
    print("Word document downloaded")

    # CSV Report (for data analysis)
    csv_report = api.download_report(batch["id"], "csv")
    with open(f"batch_report_{batch['id']}.csv", "wb") as f:
        f.write(csv_report)
    print("CSV report downloaded")

    # Download individual teacher reports
    if status['results']:
        first_result = status['results'][0]
        individual_pdf = api.download_individual_result(
            batch["id"], 
            first_result['id'], 
            "pdf"
        )
        with open(f"teacher_evaluation_{first_result['id']}.pdf", "wb") as f:
            f.write(individual_pdf)
        print(f"Individual report downloaded for {first_result['teacher_name']}")

    # Email functionality examples

    # Configure auto-email for the batch
    email_config = api.configure_batch_auto_email(
        batch["id"],
        auto_email_enabled=True,
        email_format_preferences="pdf_docx",
        manual_email_recipient="backup@university.edu"
    )
    print(f"Auto-email configured: {email_config['success']}")

    # Check email status and capabilities
    email_status = api.get_batch_email_status(batch["id"])
    print(f"SMTP configured: {email_status['email_capabilities']['smtp_configured']}")

    # Send individual evaluation email
    if status['results']:
        first_result = status['results'][0]
        email_result = api.send_individual_email(
            first_result['id'],
            "teacher@university.edu",
            include_pdf=True,
            include_docx=True,
            include_csv=False,
            custom_message="Please review your evaluation results."
        )
        print(f"Individual email sent: {email_result['success']}")

    # Send batch emails to all teachers
    batch_email_result = api.send_batch_emails(
        batch["id"],
        use_batch_preferences=True,
        custom_message="Your evaluation results are attached."
    )
    print(f"Batch emails sent: {batch_email_result['email_summary']['successful']} successful")

JavaScript Example

class TeacherFeedbackAPI {
    constructor(baseUrl) {
        this.baseUrl = baseUrl;
        this.token = null;
    }

    async authenticate(username, password) {
        const response = await fetch(`${this.baseUrl}/auth/token/`, {
            method: 'POST',
            headers: {'Content-Type': 'application/json'},
            body: JSON.stringify({username, password})
        });

        if (response.ok) {
            const data = await response.json();
            this.token = data.token;
            this.organizations = data.organizations;
            return data;
        } else {
            throw new Error(`Authentication failed: ${response.statusText}`);
        }
    }

    async submitBulkFeedback(organizationId, feedbacks) {
        const response = await fetch(`${this.baseUrl}/feedbacks/bulk/`, {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
                'Authorization': `Bearer ${this.token}`
            },
            body: JSON.stringify({
                organization_id: organizationId,
                feedbacks: feedbacks
            })
        });

        if (response.ok) {
            return await response.json();
        } else {
            throw new Error(`Failed to submit feedbacks: ${response.statusText}`);
        }
    }

    async createBatchEvaluation(name, rubricId, organizationId, feedbackIds) {
        const response = await fetch(`${this.baseUrl}/batches/create/`, {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
                'Authorization': `Bearer ${this.token}`
            },
            body: JSON.stringify({
                name,
                rubric_id: rubricId,
                organization_id: organizationId,
                feedback_ids: feedbackIds
            })
        });

        if (response.ok) {
            const data = await response.json();
            return data.batch;
        } else {
            throw new Error(`Failed to create batch: ${response.statusText}`);
        }
    }

    async runBatchEvaluation(batchId) {
        const response = await fetch(`${this.baseUrl}/batches/${batchId}/run/`, {
            method: 'POST',
            headers: {'Authorization': `Bearer ${this.token}`}
        });

        if (response.ok) {
            return await response.json();
        } else {
            throw new Error(`Failed to run batch: ${response.statusText}`);
        }
    }

    async checkBatchStatus(batchId) {
        const response = await fetch(`${this.baseUrl}/batches/${batchId}/status/`, {
            headers: {'Authorization': `Bearer ${this.token}`}
        });

        if (response.ok) {
            return await response.json();
        } else {
            throw new Error(`Failed to get status: ${response.statusText}`);
        }
    }

    async downloadReport(batchId, format = 'csv') {
        const response = await fetch(
            `${this.baseUrl}/batches/${batchId}/report/?format=${format}`,
            {headers: {'Authorization': `Bearer ${this.token}`}}
        );

        if (response.ok) {
            return await response.blob();
        } else {
            throw new Error(`Failed to download report: ${response.statusText}`);
        }
    }

    async sendIndividualEmail(evaluationId, emailAddress, options = {}) {
        const data = {
            email_address: emailAddress,
            include_pdf: options.includePdf ?? true,
            include_docx: options.includeDocx ?? true,
            include_csv: options.includeCsv ?? false,
            ...options.customMessage && { custom_message: options.customMessage }
        };

        const response = await fetch(`${this.baseUrl}/evaluations/${evaluationId}/email/`, {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
                'Authorization': `Bearer ${this.token}`
            },
            body: JSON.stringify(data)
        });

        if (response.ok) {
            return await response.json();
        } else {
            throw new Error(`Failed to send email: ${response.statusText}`);
        }
    }

    async sendBatchEmails(batchId, options = {}) {
        const data = {
            use_batch_preferences: options.useBatchPreferences ?? true,
            ...options.overrideSettings && { override_settings: options.overrideSettings },
            ...options.customMessage && { custom_message: options.customMessage }
        };

        const response = await fetch(`${this.baseUrl}/batches/${batchId}/email/`, {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
                'Authorization': `Bearer ${this.token}`
            },
            body: JSON.stringify(data)
        });

        if (response.ok) {
            return await response.json();
        } else {
            throw new Error(`Failed to send batch emails: ${response.statusText}`);
        }
    }

    async configureBatchAutoEmail(batchId, settings) {
        const response = await fetch(`${this.baseUrl}/batches/${batchId}/email/configure/`, {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
                'Authorization': `Bearer ${this.token}`
            },
            body: JSON.stringify(settings)
        });

        if (response.ok) {
            return await response.json();
        } else {
            throw new Error(`Failed to configure auto-email: ${response.statusText}`);
        }
    }

    async getBatchEmailStatus(batchId) {
        const response = await fetch(`${this.baseUrl}/batches/${batchId}/email/status/`, {
            headers: {'Authorization': `Bearer ${this.token}`}
        });

        if (response.ok) {
            return await response.json();
        } else {
            throw new Error(`Failed to get email status: ${response.statusText}`);
        }
    }
}

// Usage Example
async function example() {
    const api = new TeacherFeedbackAPI('https://preparebuddy.com/assessment/api');

    // Authenticate
    await api.authenticate('your_username', 'your_password');
    console.log('Authenticated successfully');

    // Submit feedbacks
    const feedbacks = [
        {
            title: "Math Assignment Feedback",
            feedback_content: "Student shows excellent understanding...",
            teacher_name: "Prof. Johnson",
            teacher_experience_level: "experienced",
            assessment_type: "essay",
            student_level: "Undergraduate",
            subject_area: "Mathematics"
        }
    ];

    const orgId = api.organizations[0].id;
    const submissionResult = await api.submitBulkFeedback(orgId, feedbacks);
    console.log(`Submitted ${submissionResult.feedbacks.length} feedbacks`);

    // Create and run batch evaluation
    const feedbackIds = submissionResult.feedbacks.map(f => f.id);
    const batch = await api.createBatchEvaluation(
        "API Test Batch", 1, orgId, feedbackIds
    );

    await api.runBatchEvaluation(batch.id);
    console.log('Batch evaluation started');

    // Monitor progress
    let status;
    do {
        await new Promise(resolve => setTimeout(resolve, 30000)); // Wait 30s
        status = await api.checkBatchStatus(batch.id);
        console.log(`Status: ${status.batch.status}`);
    } while (status.batch.status === 'processing');

    if (status.batch.status === 'completed') {
        // Download report
        const reportBlob = await api.downloadReport(batch.id, 'csv');
        // Handle blob download in browser
        const url = window.URL.createObjectURL(reportBlob);
        const a = document.createElement('a');
        a.href = url;
        a.download = `batch_report_${batch.id}.csv`;
        a.click();
        window.URL.revokeObjectURL(url);

        // Email functionality examples

        // Configure auto-email settings
        await api.configureBatchAutoEmail(batch.id, {
            auto_email_enabled: true,
            email_format_preferences: 'pdf_docx',
            manual_email_recipient: 'backup@university.edu'
        });
        console.log('Auto-email configured');

        // Check email capabilities
        const emailStatus = await api.getBatchEmailStatus(batch.id);
        console.log('SMTP configured:', emailStatus.email_capabilities.smtp_configured);

        // Send individual evaluation email
        if (status.results.length > 0) {
            const emailResult = await api.sendIndividualEmail(
                status.results[0].id,
                'teacher@university.edu',
                {
                    includePdf: true,
                    includeDocx: true,
                    includeCsv: false,
                    customMessage: 'Please review your evaluation results.'
                }
            );
            console.log('Individual email sent:', emailResult.success);
        }

        // Send batch emails to all teachers
        const batchEmailResult = await api.sendBatchEmails(batch.id, {
            useBatchPreferences: true,
            customMessage: 'Your evaluation results are attached.'
        });
        console.log('Batch emails sent:', batchEmailResult.email_summary.successful, 'successful');
    }
}

Error Handling

Common Error Responses

401 Unauthorized:

{"error": "Authentication required"}

403 Forbidden:

{"error": "Access denied to this organization"}

400 Bad Request:

{"error": "organization_id is required"}

404 Not Found:

{"error": "Batch not found"}

500 Internal Server Error:

{"error": "Internal server error: Database connection failed"}

Rate Limiting

  • Authentication endpoints: 10 requests per minute
  • Bulk operations: 5 requests per minute
  • Other endpoints: 100 requests per minute

Best Practices

  1. Authentication: Store tokens securely and refresh when needed
  2. Bulk Operations: Submit feedbacks in batches of 50-100 for optimal performance
  3. Polling: Check batch status every 30-60 seconds to avoid overwhelming the server
  4. Error Handling: Implement retry logic with exponential backoff
  5. Data Validation: Validate feedback content and metadata before submission
  6. Organization Scope: Always specify organization_id for proper access control

HTML Content Support

The API fully supports HTML-formatted feedback content, just like CKEditor produces:

Supported HTML Elements

  • Headings: <h1>, <h2>, <h3>, etc.
  • Text Formatting: <strong>, <em>, <u>, <span style="...">
  • Lists: <ul>, <ol>, <li>
  • Tables: Full table support with styling
  • Paragraphs: <p>, <div>, <blockquote>
  • Links and Images: <a>, <img> with preserved URLs

Example HTML Feedback

{
    "feedback_content": "<h3>Assignment Review</h3><p>The student shows <strong>excellent understanding</strong> of the concepts.</p><table border='1'><tr><th>Criteria</th><th>Score</th></tr><tr><td>Analysis</td><td>90%</td></tr></table>"
}

Metadata Support

Add unlimited custom metadata through two flexible fields:

1. Structured Criteria

{
    "criteria_addressed": [
        "problem_solving",
        "communication",
        "critical_thinking",
        "technical_accuracy"
    ]
}

2. Flexible JSON Metadata

The extraction_metadata field accepts any JSON structure:

{
    "extraction_metadata": {
        "course_info": {
            "course_id": "MATH101",
            "semester": "Spring 2024",
            "assignment_id": "hw_03"
        },
        "student_context": {
            "student_id": "S123456",
            "year_level": 2,
            "major": "Engineering"
        },
        "grading_session": {
            "graded_by": "prof_smith",
            "grading_date": "2024-01-20T15:30:00Z",
            "time_spent_minutes": 25
        },
        "quality_metrics": {
            "feedback_quality_score": 8.5,
            "constructiveness": "high",
            "actionable_suggestions": 4
        },
        "custom_tags": ["urgent", "exemplary", "needs_followup"]
    }
}

Common Metadata Use Cases

  • LMS Integration: Course IDs, assignment IDs, submission timestamps
  • Academic Context: Semester, student level, prerequisites
  • Quality Tracking: Feedback scores, tone assessment, suggestion counts
  • Workflow Management: Priority levels, follow-up flags, review status
  • Research Data: Anonymization flags, study participation, cohort IDs

Reference Feedback System & RAG

Status: Now Available via API! 🎉

The system includes RAG (Retrieval-Augmented Generation) for enhanced evaluation quality:

  • ✅ Web Interface: Create and manage reference feedbacks at /assessment/teacher-evaluation/references/
  • ✅ Database Storage: Reference examples stored with vector embeddings for similarity search
  • ✅ AI Integration: Now fully integrated - Use RAG via API for enhanced evaluations
  • ✅ API Support: Configure RAG parameters when creating batch evaluations

How to Use RAG via API

Enable RAG when creating a batch evaluation:

{
    "name": "My Batch",
    "rubric_id": 1,
    "organization_id": 1,
    "feedback_ids": [101, 102, 103],
    "use_reference_matching": true,
    "reference_matching_mode": "dynamic",
    "reference_detail_level": "detailed",
    "max_references": 5
}

Reference Feedback Categories

Reference feedbacks can be categorized as: - Excellent: Gold standard examples showing best practices - Good: Quality examples with minor areas for improvement - Average: Acceptable examples with clear improvement opportunities - Poor: Examples demonstrating common issues to avoid

RAG Benefits

  • ✓ Consistency: More consistent scoring across similar feedbacks
  • ✓ Context-Aware: Evaluations learn from your specific quality standards
  • ✓ Accuracy: +18-28% improvement in evaluation accuracy
  • ✓ Actionable: More specific and actionable recommendations

See Also: RAG_IMPLEMENTATION_GUIDE.md for detailed information about RAG configuration and best practices.

Support

For technical support or questions about the API: - Review existing teacher evaluation documentation in your system - Check the web interface for additional context about rubrics and evaluations - Contact your system administrator for organization-specific configurations - See additional guides: - API_USAGE_GUIDE.md - NEW! Complete API workflow guide with RAG and auto-email examples - RAG_IMPLEMENTATION_GUIDE.md - Comprehensive RAG configuration and best practices - HTML_FEEDBACK_GUIDE.md - Detailed HTML formatting examples - METADATA_GUIDE.md - Comprehensive metadata documentation - API_TESTING_GUIDE.md - Step-by-step testing instructions

Testing

Comprehensive API testing suite available: - /testing/test_api_core_workflow.py - Complete end-to-end workflow test including RAG and auto-email

Note: This API leverages your existing teacher evaluation infrastructure, including AI models, rubrics, and organizational settings configured through the web interface.

Last Updated: January 2025 - Added RAG support, synchronous evaluation processing, and auto-email functionality

Tags
api integration development authentication endpoints
On this page
Quick actions
Back to API Reference Edit this page Get help