The Assignment Grader API allows you to automatically grade student assignments using AI based on your custom rubrics. Define your grading criteria, submit the assignment content, and receive consistent, objective grades based on your rubric.

​
Key Features

  • Custom Rubrics: Define grading criteria with specific point values
  • Flexible Input: Grade from uploaded materials or direct text
  • Consistent Grading: AI ensures uniform application of rubric criteria
  • Objective Grading: Get numerical grades based on your rubric
  • User Tracking: Optional user ID for tracking grading history
  • Assignment Groups: Group submissions by assignment ID
  • Student Identification: Track submissions by student email or ID
  • Rubric Templates: Save and reuse common rubrics

​
Creating a Rubric Definition

Before grading assignments, you need to define a rubric with specific criteria. Each criterion has:
  • pointsPossible: The maximum points for this criterion (required)
  • title: The name of the criterion (required)
  • description: Detailed explanation of what’s being evaluated (optional but recommended)
// Define a comprehensive rubric
const rubricDefinition = {
  criteria: [
    {
      pointsPossible: 25,
      title: "Thesis Statement",
      description: "Clear, arguable thesis that addresses the prompt"
    },
    {
      pointsPossible: 30,
      title: "Evidence and Analysis",
      description: "Strong evidence with thorough analysis"
    },
    {
      pointsPossible: 25,
      title: "Organization",
      description: "Logical structure with smooth transitions"
    },
    {
      pointsPossible: 20,
      title: "Writing Mechanics",
      description: "Grammar, spelling, and citation format"
    }
  ]
};

// Total points: 100

​
Create Assignment Grader

Grade a new assignment by providing the rubric and content to grade. 
import StudyfetchSDK from '@studyfetch/sdk';

const client = new StudyfetchSDK({
  apiKey: 'your-api-key',
  baseURL: 'https://studyfetchapi.com',
});

// Use the rubric definition from above
const params = {
  title: "Essay on Climate Change",
  textToGrade: "Student essay content here...",
  rubric: rubricDefinition,           // Optional: Custom rubric definition
  rubricTemplateId: "template-123",   // Optional: Use existing rubric template
  assignmentId: "assign-456",         // Optional: Group submissions
  studentIdentifier: "john.doe@example.com", // Optional: Student email or ID
  userId: "student123",               // Optional: For tracking
  model: "gpt-4.1-2025-04-14"         // Optional: AI model to use
};

const result = await client.v1.assignmentGrader.create(params);

console.log(`Success: ${result.success}`);
console.log(`Grade: ${result.gradedAssignment?.grade || 0}/100`);
console.log(`Assignment ID: ${result.gradedAssignment?._id}`);

​
Get All Assignment Graders

Retrieve all assignment graders for your organization. 
const graders = await client.v1.assignmentGrader.getAll();

graders.forEach(grader => {
  console.log(`ID: ${grader._id}`);
  console.log(`Title: ${grader.title}`);
  console.log(`Grade: ${grader.grade}`);
  console.log(`Created: ${grader.createdAt}`);
  console.log(`Assignment ID: ${grader.assignmentId}`);
  console.log(`Student: ${grader.studentIdentifier}`);
});

​
Get Assignment Grader by ID

Retrieve a specific assignment grader by its ID. 
const graderId = "grader_123456";
const grader = await client.v1.assignmentGrader.getByID(graderId);

console.log(`ID: ${grader._id}`);
console.log(`Assignment: ${grader.title}`);
console.log(`Grade: ${grader.grade}/100`);
console.log(`Student: ${grader.studentIdentifier}`);
console.log(`Assignment ID: ${grader.assignmentId}`);

​
Delete Assignment Grader

Delete a specific assignment grader by its ID. 
const graderId = "grader_123456";
await client.v1.assignmentGrader.delete(graderId);
console.log("Assignment grader deleted successfully");

​
Generate Educator Report

Generate a comprehensive report for all submissions of a specific assignment. This provides detailed analytics including grade distribution, statistics, and performance analysis by criteria. 
const assignmentId = "assign-456";
const report = await client.v1.assignmentGrader.generateReport(assignmentId);

console.log("Assignment Report:");
console.log(`Title: ${report.title}`);
console.log(`Total Submissions: ${report.totalSubmissions}`);
console.log(`Average Grade: ${report.statistics.averageGrade}`);
console.log(`Max Grade: ${report.statistics.maxGrade}`);
console.log(`Min Grade: ${report.statistics.minGrade}`);
console.log(`Standard Deviation: ${report.statistics.standardDeviation}`);

// Grade distribution
console.log("Grade Distribution:");
console.log(`  A (90-100): ${report.gradeDistribution.A}`);
console.log(`  B (80-89): ${report.gradeDistribution.B}`);
console.log(`  C (70-79): ${report.gradeDistribution.C}`);
console.log(`  D (60-69): ${report.gradeDistribution.D}`);
console.log(`  F (0-59): ${report.gradeDistribution.F}`);

// Top performing criteria
console.log("Strengths:");
report.strengths.forEach(strength => {
  console.log(`  ${strength.title}: ${strength.avgScore}/${strength.maxPossible} (${strength.performanceRatio})`);
});

// Criteria needing improvement
console.log("Weaknesses:");
report.weaknesses.forEach(weakness => {
  console.log(`  ${weakness.title}: ${weakness.avgScore}/${weakness.maxPossible} (${weakness.performanceRatio})`);
});

​
Rubric Templates

Save and reuse common rubrics by creating rubric templates.

​
Create Rubric Template

const templateParams = {
  name: "Standard Essay Rubric",
  description: "Basic 100-point essay grading rubric",
  criteria: [
    {
      pointsPossible: 25,
      title: "Thesis Statement",
      description: "Clear, arguable thesis that addresses the prompt"
    },
    {
      pointsPossible: 30,
      title: "Evidence and Analysis",
      description: "Strong evidence with thorough analysis"
    },
    {
      pointsPossible: 25,
      title: "Organization",
      description: "Logical structure with smooth transitions"
    },
    {
      pointsPossible: 20,
      title: "Writing Mechanics",
      description: "Grammar, spelling, and citation format"
    }
  ]
};

const template = await client.v1.assignmentGrader.rubricTemplates.create(templateParams);
console.log(`Template created: ${template._id}`);

​
List Rubric Templates

const templates = await client.v1.assignmentGrader.rubricTemplates.list();

templates.forEach(template => {
  console.log(`Name: ${template.name}`);
  console.log(`Description: ${template.description}`);
  console.log(`Created: ${template.createdAt}`);
});

​
Get Rubric Template by ID

const templateId = "template-123";
const template = await client.v1.assignmentGrader.rubricTemplates.getByID(templateId);

console.log(`Template: ${template.name}`);
console.log(`Description: ${template.description}`);
console.log(`Criteria:`, template.criteria);

​
Delete Rubric Template

const templateId = "template-123";
await client.v1.assignmentGrader.rubricTemplates.delete(templateId);
console.log("Rubric template deleted successfully");

​
Grading from Material

Grade an assignment that has already been uploaded as a material.
Important: Materials need time to process after upload. You must wait for the material to have status: 'active' before grading it. Attempting to grade a material that is still processing will fail.Tip: Use the createAndProcess method for text materials to avoid manual waiting - it automatically waits for processing to complete.
// First upload the assignment as a material
const material = await client.v1.materials.create({
  name: "Student Essay - John Doe",
  content: {
    type: "pdf",
    file: studentEssayFile
  }
});

// Wait for material to finish processing
let materialStatus = 'processing';
while (materialStatus !== 'active') {
  const updatedMaterial = await client.v1.materials.retrieve(material._id);
  materialStatus = updatedMaterial.status;
  if (materialStatus === 'error') {
    throw new Error('Material processing failed');
  }
  if (materialStatus === 'processing') {
    await new Promise(resolve => setTimeout(resolve, 2000)); // Wait 2 seconds
  }
}

// Then grade using the material ID
const gradeResult = await client.v1.assignmentGrader.create({
  rubric: rubricDefinition,
  title: "Essay Assignment",
  materialId: material._id,
  assignmentId: "assign-456",
  studentIdentifier: "john.doe@example.com"
});

​
Using Create and Process (Recommended for Text)

For text assignments, use createAndProcess to automatically wait for processing: 
// Create and process text material in one step
const material = await client.v1.materials.createAndProcess({
  content: { 
    type: 'text',
    text: studentEssayText
  },
  name: 'Student Essay - John Doe',
});

// Material is immediately ready for grading
const gradeResult = await client.v1.assignmentGrader.create({
  rubric: rubricDefinition,
  title: "Essay Assignment",
  materialId: material._id,
  assignmentId: "assign-456",
  studentIdentifier: "john.doe@example.com"
});