Teacher Evaluation API - Complete Workflow Guide

Overview

This comprehensive guide walks you through the complete teacher feedback evaluation API workflow from initial authentication to automatic email delivery. Follow this guide to integrate teacher evaluation capabilities into your application using the Assessment API.

Prerequisites

Before you begin, ensure you have:

Valid account on the platform
Organization membership with one of these roles:
Admin - Full organization access and evaluation capabilities
Examiner - Can create evaluations and manage assessments
Super Admin - Platform-wide access to all organizations
Active membership status - Your organization membership must be active
Organization ID for your organization
Rubric ID for the evaluation rubric you want to use
API endpoint URL (e.g., https://preparebuddy.com/assessment/api

Note: If you don't meet these requirements, contact your organization administrator to add you to an organization and grant you the appropriate role.

Complete Workflow Steps

Step 1: Authentication

First, authenticate to get your API token.

Endpoint: POST /api/auth/token/

curl -X POST https://preparebuddy.com/api/auth/token/ \
  -H "Content-Type: application/json" \
  -d '{
    "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": "abc123sessionkey456...",
  "user_id": 42,
  "username": "your_username",
  "email": "user@example.com",
  "organizations": [
    {
      "id": 1,
      "name": "My School",
      "role": "admin"
    }
  ]
}

Important: Use the token value as your Bearer token for all subsequent requests.

Error Response (No 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."
}

Step 2: Upload Teacher Feedbacks

Submit one or more teacher feedbacks for evaluation.

Endpoint: POST /api/feedbacks/bulk/

curl -X POST https://preparebuddy.com/api/feedbacks/bulk/ \
  -H "Authorization: Bearer xyz789..." \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": 1,
    "feedbacks": [
      {
        "title": "Math Assignment Feedback - Student A",
        "feedback_content": "The student demonstrates excellent understanding of algebraic concepts. The solution approach is logical and well-structured. However, there are minor calculation errors in the final steps.",
        "teacher_name": "John Smith",
        "teacher_experience_level": "experienced",
        "assessment_type": "assignment",
        "student_level": "Grade 10",
        "subject_area": "Mathematics",
        "student_context": "Student scored 85%, First attempt"
      },
      {
        "title": "Science Lab Report Feedback - Student B",
        "feedback_content": "Good effort on the lab report. The hypothesis and methodology are clearly stated. The data collection is thorough. The conclusion could benefit from more analysis.",
        "teacher_name": "Jane Doe",
        "teacher_experience_level": "novice",
        "assessment_type": "lab_report",
        "student_level": "Grade 9",
        "subject_area": "Science"
      }
    ]
  }'

Response:

{
  "message": "Successfully created 2 feedbacks",
  "feedbacks": [
    {
      "id": 101,
      "title": "Math Assignment Feedback - Student A",
      "teacher_name": "John Smith",
      "word_count": 45
    },
    {
      "id": 102,
      "title": "Science Lab Report Feedback - Student B",
      "teacher_name": "Jane Doe",
      "word_count": 38
    }
  ]
}

Step 3: Create Batch Evaluation with RAG

Create a batch evaluation and optionally enable RAG for enhanced quality.

Endpoint: POST /api/batches/create/

Option A: Basic Batch (Without RAG)

curl -X POST https://preparebuddy.com/api/batches/create/ \
  -H "Authorization: Bearer xyz789..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q1 2025 Teacher Evaluations",
    "description": "First quarter teacher performance review",
    "rubric_id": 5,
    "organization_id": 1,
    "feedback_ids": [101, 102],
    "evaluation_focus": "Focus on clarity and actionability of feedback"
  }'

Option B: With RAG Enhancement (Recommended)

curl -X POST https://preparebuddy.com/api/batches/create/ \
  -H "Authorization: Bearer xyz789..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q1 2025 Teacher Evaluations",
    "description": "First quarter teacher performance review with RAG",
    "rubric_id": 5,
    "organization_id": 1,
    "feedback_ids": [101, 102],
    "evaluation_focus": "Focus on clarity and actionability of feedback",
    "evaluation_instructions": "Pay special attention to specific, measurable recommendations for student improvement",
    "use_reference_matching": true,
    "reference_matching_mode": "dynamic",
    "reference_detail_level": "detailed",
    "max_references": 5
  }'

RAG Parameters Explained: - use_reference_matching - Enable RAG to find similar high-quality examples - reference_matching_mode - "dynamic" (similarity-based) or "static" (fixed examples) - reference_detail_level - "detailed" (comprehensive) or "summary" (concise) - max_references - Number of reference examples to use (1-10, default: 5)

Response:

{
  "message": "Batch evaluation created successfully",
  "batch": {
    "id": 50,
    "name": "Q1 2025 Teacher Evaluations",
    "status": "pending",
    "total_feedbacks": 2,
    "created_at": "2025-01-15T10:30:00Z",
    "rag_configuration": {
      "use_reference_matching": true,
      "reference_matching_mode": "dynamic",
      "reference_detail_level": "detailed",
      "max_references": 5
    }
  }
}

Step 4: Configure Auto-Email (Optional but Recommended)

Set up automatic email delivery when evaluation completes.

Endpoint: POST /api/batches/50/email/configure/

curl -X POST https://preparebuddy.com/api/batches/50/email/configure/ \
  -H "Authorization: Bearer xyz789..." \
  -H "Content-Type: application/json" \
  -d '{
    "send_email_on_completion": true,
    "manual_email_recipient": "teacher@school.edu",
    "email_format_preferences": "pdf_docx",
    "email_message": "Your teaching evaluation is complete. Please review the attached reports for detailed feedback and recommendations."
  }'

Email Format Options: - "pdf_only" - PDF report only - "docx_only" - Word document only - "pdf_docx" - Both PDF and Word (recommended) - "all_formats" - PDF, Word, and CSV

Response:

{
  "success": true,
  "message": "Email configuration updated successfully",
  "configuration": {
    "batch_id": 50,
    "batch_name": "Q1 2025 Teacher Evaluations",
    "send_email_on_completion": true,
    "manual_email_recipient": "teacher@school.edu",
    "email_format_preferences": "pdf_docx",
    "format_description": "PDF and Word Document",
    "email_message": "Your teaching evaluation is complete...",
    "updated_at": "2025-01-15T10:32:00Z"
  }
}

Step 5: Run Evaluation

Trigger the AI evaluation process. This endpoint blocks until completion.

Endpoint: POST /api/batches/50/run/

⚠️ Important: This endpoint processes evaluations synchronously and will block for 1-3 minutes depending on the number of feedbacks. If auto-email is enabled, the email will be sent before this endpoint returns.

curl -X POST https://preparebuddy.com/api/batches/50/run/ \
  -H "Authorization: Bearer xyz789..."

What Happens During Execution: 1. Batch status changes to "processing" 2. Each feedback is evaluated using AI with the specified rubric 3. If RAG is enabled, similar reference examples are retrieved and used 4. Criterion scores, feedback, and recommendations are generated 5. Overall teacher assessment is synthesized 6. If auto-email is enabled, emails are sent to recipients 7. Batch status changes to "completed" 8. Response is returned

Response (After 1-3 minutes):

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

✅ If auto-email was enabled, the email has already been sent to teacher@school.edu with PDF and Word attachments!

Step 6: Check Status and Results

Verify the evaluation completed and view results.

Endpoint: GET /api/batches/50/status/

curl https://preparebuddy.com/api/batches/50/status/ \
  -H "Authorization: Bearer xyz789..."

Response:

{
  "batch": {
    "id": 50,
    "name": "Q1 2025 Teacher Evaluations",
    "status": "completed",
    "total_feedbacks": 2,
    "completed_at": "2025-01-15T10:35:00Z",
    "created_at": "2025-01-15T10:30:00Z"
  },
  "results": [
    {
      "id": 201,
      "feedback_title": "Math Assignment Feedback - Student A",
      "teacher_name": "John Smith",
      "overall_score": 45.5,
      "percentage": 91.0,
      "created_at": "2025-01-15T10:34:00Z"
    },
    {
      "id": 202,
      "feedback_title": "Science Lab Report Feedback - Student B",
      "teacher_name": "Jane Doe",
      "overall_score": 38.0,
      "percentage": 76.0,
      "created_at": "2025-01-15T10:34:30Z"
    }
  ]
}

Step 7: Download Reports (Optional)

Download evaluation reports in various formats.

Download PDF Report

curl https://preparebuddy.com/api/batches/50/report/?format=pdf \
  -H "Authorization: Bearer xyz789..." \
  --output batch_report.pdf

Download Word Document

curl https://preparebuddy.com/api/batches/50/report/?format=docx \
  -H "Authorization: Bearer xyz789..." \
  --output batch_report.docx

Download CSV Data

curl https://preparebuddy.com/api/batches/50/report/?format=csv \
  -H "Authorization: Bearer xyz789..." \
  --output batch_report.csv

Get JSON Data

curl https://preparebuddy.com/api/batches/50/report/?format=json \
  -H "Authorization: Bearer xyz789..."

JSON Response includes: - Complete evaluation details for each feedback - Criterion-by-criterion scores and feedback - Strengths, areas for improvement, and recommendations - Overall teacher assessment - RAG reference comparisons (if enabled) - Summary statistics

Step 8: Get Summary Report (Optional)

Get quick statistics and insights.

Endpoint: GET /api/batches/50/summary/

curl https://preparebuddy.com/api/batches/50/summary/ \
  -H "Authorization: Bearer xyz789..."

Response:

{
  "summary": {
    "batch_id": 50,
    "batch_name": "Q1 2025 Teacher Evaluations",
    "total_feedbacks": 2,
    "rubric_name": "Standard Teaching Rubric",
    "total_possible_points": 50,
    "statistics": {
      "average_score": 41.75,
      "average_percentage": 83.5,
      "max_score": 45.5,
      "min_score": 38.0,
      "score_distribution": {
        "excellent": 1,
        "good": 1,
        "satisfactory": 0,
        "needs_improvement": 0
      }
    },
    "criterion_performance": {
      "1": {
        "name": "Clarity of Feedback",
        "average_score": 8.5,
        "evaluations": 2
      },
      "2": {
        "name": "Constructive Suggestions",
        "average_score": 8.0,
        "evaluations": 2
      }
    },
    "completed_at": "2025-01-15T10:35:00Z"
  }
}

Complete Python Example

Here's a complete working example in Python:

import requests
import time

# Configuration
API_BASE = "https://preparebuddy.com/api"
USERNAME = "your_username"
PASSWORD = "your_password"
ORG_ID = 1
RUBRIC_ID = 5

def main():
    # Step 1: Authenticate
    print("Step 1: Authenticating...")
    auth_response = requests.post(
        f"{API_BASE}/auth/token/",
        json={"username": USERNAME, "password": PASSWORD}
    )
    token = auth_response.json()['session_key']
    headers = {"Authorization": f"Bearer {token}"}
    print(f"✓ Authenticated as {auth_response.json()['username']}")

    # Step 2: Upload feedbacks
    print("\nStep 2: Uploading feedbacks...")
    feedbacks_response = requests.post(
        f"{API_BASE}/feedbacks/bulk/",
        headers=headers,
        json={
            "organization_id": ORG_ID,
            "feedbacks": [
                {
                    "title": "Math Feedback",
                    "feedback_content": "Great work on algebra concepts...",
                    "assessment_type": "assignment",
                    "teacher_name": "John Smith",
                    "student_level": "Grade 10"
                }
            ]
        }
    )
    feedback_ids = [f['id'] for f in feedbacks_response.json()['feedbacks']]
    print(f"✓ Uploaded {len(feedback_ids)} feedbacks")

    # Step 3: Create batch with RAG
    print("\nStep 3: Creating batch with RAG...")
    batch_response = requests.post(
        f"{API_BASE}/batches/create/",
        headers=headers,
        json={
            "name": "API Test Batch",
            "rubric_id": RUBRIC_ID,
            "organization_id": ORG_ID,
            "feedback_ids": feedback_ids,
            "use_reference_matching": True,
            "reference_matching_mode": "dynamic"
        }
    )
    batch_id = batch_response.json()['batch']['id']
    print(f"✓ Created batch {batch_id}")

    # Step 4: Configure auto-email
    print("\nStep 4: Configuring auto-email...")
    requests.post(
        f"{API_BASE}/batches/{batch_id}/email/configure/",
        headers=headers,
        json={
            "send_email_on_completion": True,
            "manual_email_recipient": "teacher@school.edu",
            "email_format_preferences": "pdf_docx"
        }
    )
    print("✓ Auto-email configured")

    # Step 5: Run evaluation (blocks until complete!)
    print("\nStep 5: Running evaluation (this takes 1-3 minutes)...")
    eval_response = requests.post(
        f"{API_BASE}/batches/{batch_id}/run/",
        headers=headers
    )
    print(f"✓ Evaluation completed: {eval_response.json()['status']}")
    print("✓ Auto-email sent to teacher@school.edu!")

    # Step 6: Get results
    print("\nStep 6: Fetching results...")
    status_response = requests.get(
        f"{API_BASE}/batches/{batch_id}/status/",
        headers=headers
    )
    results = status_response.json()['results']
    for result in results:
        print(f"  - {result['feedback_title']}: {result['overall_score']} ({result['percentage']:.1f}%)")

    # Step 7: Download PDF report
    print("\nStep 7: Downloading PDF report...")
    pdf_response = requests.get(
        f"{API_BASE}/batches/{batch_id}/report/?format=pdf",
        headers=headers
    )
    with open(f"batch_report_{batch_id}.pdf", "wb") as f:
        f.write(pdf_response.content)
    print(f"✓ Report saved as batch_report_{batch_id}.pdf")

    print("\n✅ Complete workflow finished successfully!")

if __name__ == "__main__":
    main()

Workflow Summary

1. Authenticate              →  Get session_key token
2. Upload Feedbacks          →  Get feedback IDs
3. Create Batch with RAG     →  Get batch ID
4. Configure Auto-Email      →  Set email preferences
5. Run Evaluation            →  [Blocks 1-3 mins] → Email sent automatically
6. Check Status              →  Verify completion and view scores
7. Download Reports          →  Get PDF/DOCX/CSV/JSON
8. Get Summary               →  View statistics and insights

Troubleshooting

Issue: Token expired

Symptom: 401 Unauthorized error Solution: Re-authenticate to get a new token (tokens expire after 2 weeks)

Issue: Evaluation taking too long

Symptom: Run endpoint blocks for >5 minutes Solution: Check number of feedbacks; typical time is 30-90 seconds per feedback

Issue: Email not received

Symptom: Evaluation completes but email not in inbox Solution: - Check spam/junk folder - Verify email address in configuration - Check organization SMTP settings

Issue: No reference examples found (RAG)

Symptom: RAG enabled but no reference comparisons in results Solution: Create reference feedbacks in web interface at /assessment/teacher-evaluation/references/

Best Practices

Authentication
Store tokens securely
Refresh tokens before they expire
Don't hardcode credentials
Batch Size
Keep batches under 50 feedbacks for reasonable processing time
Use multiple batches for large datasets
RAG Usage
Start with reference_matching_mode: "dynamic" for best results
Use reference_detail_level: "detailed" for comprehensive feedback
Maintain 10-20 high-quality reference examples per rubric
Email Configuration
Always configure auto-email for production workflows
Use "pdf_docx" format for best recipient experience
Include clear, actionable email messages
Error Handling
Implement retry logic for transient failures
Log all API responses for debugging
Monitor evaluation completion times

Next Steps

RAG Configuration: See api_rag_configuration.md for detailed RAG setup
Email System: See email_api.md for advanced email features
Testing: Run /testing/test_api_core_workflow.py for complete workflow validation
RAG Guide: Read RAG_IMPLEMENTATION_GUIDE.md for RAG best practices

Last Updated: January 2025

API Core Workflow Guide

Teacher Evaluation API - Complete Workflow Guide

Overview

Prerequisites

Complete Workflow Steps

Step 1: Authentication

Step 2: Upload Teacher Feedbacks

Step 3: Create Batch Evaluation with RAG

Option A: Basic Batch (Without RAG)

Option B: With RAG Enhancement (Recommended)

Step 4: Configure Auto-Email (Optional but Recommended)

Step 5: Run Evaluation

Step 6: Check Status and Results

Step 7: Download Reports (Optional)

Download PDF Report

Download Word Document

Download CSV Data

Get JSON Data

Step 8: Get Summary Report (Optional)

Complete Python Example

Workflow Summary

Troubleshooting

Issue: Token expired

Issue: Evaluation taking too long

Issue: Email not received

Issue: No reference examples found (RAG)

Best Practices

Next Steps

Tags

Was this page helpful?

On this page

Quick actions