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

​
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 = {
  rubric: rubricDefinition,
  title: "Essay on Climate Change",
  textToGrade: "Student essay content here...",
  userId: "student123", // Optional
  model: "gpt-4" // Optional, defaults to optimal model
};

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

console.log(`Grade: ${result.grade}/100`);

​
Get All Assignment Graders

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

graders.forEach(grader => {
  console.log(`Title: ${grader.title}`);
  console.log(`Grade: ${grader.grade}`);
  console.log(`Created: ${grader.createdAt}`);
});

​
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(`Assignment: ${grader.title}`);
console.log(`Grade: ${grader.grade}/100`);

​
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
});

​
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
});