Skip to main content
The Assignment Grader API allows you to submit student work (text or uploaded materials), define grading criteria via a rubric, and receive AI-generated scores and feedback for every criterion. It supports inline rubrics, reusable rubric templates, assignment content for source-based grading, and aggregate educator reports.

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
  • Assignment Content: Provide source material (reading passages, case studies, prompts) that the AI uses as the authoritative reference when grading
  • 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

Base URL

All endpoints are relative to your API prefix (defaults to api/v1):
For local development:

Authentication

Every endpoint is protected by FlexibleAuthGuard, which accepts either: If neither is present the request returns 401 Unauthorized.
Every record (graded assignment, rubric template) is scoped to the authenticated organizationId. You can only read/delete records that belong to your org.

Common Headers

Endpoint Summary

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)

Create Assignment Grader

Grade a new assignment by providing the rubric and content to grade. Returns the saved graded assignment with AI-generated scores and feedback.

Request Body

* You must provide exactly one of materialId or textToGrade. Providing both or neither returns 400 Bad Request. ** You must provide at least one of rubric or rubricTemplateId. An inline rubric must contain at least one criterion.

Example Request (curl)

Response — 201 Created

SDK Examples

Get All Assignment Graders

Returns every graded assignment for the authenticated organization.

Example Request (curl)

Response — 200 OK

An array of AssignmentGrader objects.

SDK Examples

Get Assignment Grader by ID

Retrieve a specific graded assignment by its ID.

Example Request (curl)

Response — 200 OK

A single AssignmentGrader object. Returns 404 Not Found if no assignment matches the ID.

SDK Examples

Delete Assignment Grader

Delete a specific graded assignment by its ID.

Example Request (curl)

Response — 200 OK

Returns 404 Not Found if the assignment doesn’t exist or belongs to a different org.

SDK Examples

Generate Educator Report

Aggregates statistics across every graded submission in your organization that shares the given assignmentId. Use this after grading multiple students for the same logical assignment.

Example Request (curl)

Response — 200 OK

Field Semantics

Returns 404 Not Found if no submissions match the assignmentId in your organization.

SDK Examples

Rubric Templates

Rubric templates are reusable rubrics scoped to your organization. They optionally store an assignmentContent so the same source material is automatically supplied every time the template is used.

Create Rubric Template

Request Body

Example Request (curl)

Response — 201 Created

A RubricTemplate document.

SDK Examples

List Rubric Templates

Returns every rubric template for the authenticated organization, sorted newest first.

Example Request (curl)

SDK Examples

Get Rubric Template by ID

Returns a single RubricTemplate. Returns 404 Not Found if not found in your organization.

SDK Examples

Delete Rubric Template

Response — 200 OK

Returns 404 Not Found if the template doesn’t exist or belongs to a different org.

SDK Examples

Assignment Content

The assignmentContent field provides the AI grader with the original material students were working from — such as a reading passage, case study, or prompt. This is critical for accurate grading because the AI can verify student answers against the actual source instead of relying on its own knowledge.

Where You Can Set It

Priority Order

When assignmentContent is specified in multiple places, the following priority applies:
  1. Top-level assignmentContent on the grading request (highest priority)
  2. assignmentContent inside the rubric object on the grading request
  3. assignmentContent saved on the rubric template (if rubricTemplateId is used — lowest priority)
This means you can save a default passage on a rubric template and override it per-request when needed — for example, if you update a passage slightly for one section of students.

Usage Patterns

Every grading request has up to four pieces working together: The AI grader reads all four, then scores the student’s answer against the rubric using the source material as the ground truth. Below are the most common patterns for combining them.

Pattern 1 — Reading Comprehension (Passage + Questions)

A teacher assigns a reading passage and asks students to answer questions about it. Each question becomes a rubric criterion, and the passage goes in assignmentContent.
The AI will flag Q3 as incorrect because the student said conditions were “great” — the passage says they were dangerous.

Pattern 2 — Essay / Open-Ended Writing (No Source Material)

When students write an original essay (no assigned reading), you don’t need assignmentContent at all. The rubric criteria describe what a good essay looks like.

Pattern 3 — Case Study Analysis (Scenario + Specific Questions)

Give the AI a case study as assignmentContent, then define criteria that test whether the student applied the right frameworks or identified the right issues.
The AI will notice the student oversimplified — they didn’t acknowledge the trade-offs or apply an ethical framework.

Pattern 4 — Reusable Template for Repeated Assignments

When many students answer the same questions about the same material, save everything in a rubric template so you only define the rubric and passage once. Create the template once:
Grade each student — just send the answer:
The passage and rubric are pulled from the template automatically — no need to re-send them.

Choosing the Right Pattern

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.
For text assignments, use createAndProcess to automatically wait for processing:

Full Example: Passage Reading + Question Answering

This end-to-end walkthrough shows the full lifecycle: create a reusable template with a passage baked in, grade multiple students against it, then pull a class-wide educator report.

Step 1 — Create a Rubric Template with the Passage

Capture _id from the response — that’s your TEMPLATE_ID.

Step 2 — Grade Each Student’s Submission

Repeat this for every student, keeping the same assignmentId.
What the AI grader does:
  1. Reads the rubric criteria (questions + what to look for)
  2. Reads the assignment content (the water cycle passage) as the source of truth
  3. Reads the student’s submission (their answers)
  4. Grades each answer against the passage, not against its own knowledge
  5. Returns per-criterion scores and feedback

Step 3 — Pull the Educator Report

After grading multiple students with the same assignmentId, generate an aggregate report:
You’ll receive aggregate statistics, grade distribution, per-criterion analysis, strengths, weaknesses, and a list of every submission.

Inline Rubric with Assignment Content (No Template)

If you don’t need a reusable template, you can pass everything in a single request:

Object Reference

RubricCriterion Object

Rubric Object (Request Input)

GradedRubricCriterion Object (Response)

AssignmentGrader Object

RubricTemplate Object

Error Responses

All errors follow the standard exception envelope. Example error body:

Tips & Best Practices

  • Provide assignmentContent whenever possible. It dramatically improves grading accuracy because the AI grades against the actual source instead of guessing.
  • Keep assignmentContent focused. Paste the actual passage or prompt students received. Don’t include instructions meant for the grader — put those in the criterion description fields instead.
  • Use criterion descriptions as grading instructions. For example: “Award full points only if the student names ≥2 specific dates from the passage.”
  • Save templates for repeated assignments. If 30 students are all answering the same reading comprehension, create a template once and reuse it with rubricTemplateId.
  • Always set assignmentId and studentIdentifier when you plan to run an educator report. Without assignmentId, the report can’t aggregate submissions.
  • Top-level wins for assignmentContent. If you need a one-off override of the template’s saved content, just include assignmentContent at the top level of the grading request.
  • Cap on inputs. Materials larger than ~30k chars per item are truncated for grading; very large materials (>100k chars) are also truncated when extracted.
  • Strict grading. The grader awards 0 points for factually incorrect answers. Post-processing also detects keywords like “incorrect”, “wrong”, “opposite” in the AI’s per-criterion feedback and forces pointsAwarded to 0 (unless the feedback also indicates partial correctness with words like “partially”, “mostly”).