Moderated Grading
API for viewing and adding students to the list of people in moderation for an assignment
API for manipulating provisional grades
Provisional grades are created by using the Submissions API endpoint "Grade or comment on a submission" with provisional=true. They can be viewed by using "List assignment submissions", "Get a single submission", or "List gradeable students" with include[]=provisional_grades. This API performs other operations on provisional grades for use with the Moderated Grading feature.
A ProvisionalGrade object looks like:
{
// The identifier for the provisional grade
"provisional_grade_id": 23,
// The numeric score
"score": 90,
// The grade
"grade": "A-",
// Whether the grade was applied to the most current submission (false if the
// student resubmitted after grading)
"grade_matches_current_submission": true,
// When the grade was given
"graded_at": "2015-11-01T00:03:21-06:00",
// Whether this is the 'final' provisional grade created by the moderator
"final": false,
// A link to view this provisional grade in SpeedGrader
"speedgrader_url": "http://www.example.com/courses/123/gradebook/speed_grader?..."
}List students selected for moderation
GET /api/v1/courses/:course_id/assignments/:assignment_id/moderated_students
Scope: url:GET|/api/v1/courses/:course_id/assignments/:assignment_id/moderated_students
Returns a paginated list of students selected for moderation
Returns a list of User objects.
Select students for moderation
ModerationSetController#create
POST /api/v1/courses/:course_id/assignments/:assignment_id/moderated_students
Scope: url:POST|/api/v1/courses/:course_id/assignments/:assignment_id/moderated_students
Returns an array of users that were selected for moderation
Request Parameters:
student_ids[]
number
user ids for students to select for moderation
Returns a list of User objects.
Bulk select provisional grades
ProvisionalGradesController#bulk_select
PUT /api/v1/courses/:course_id/assignments/:assignment_id/provisional_grades/bulk_select
Scope: url:PUT|/api/v1/courses/:course_id/assignments/:assignment_id/provisional_grades/bulk_select
Choose which provisional grades will be received by associated students for an assignment. The caller must be the final grader for the assignment or an admin with :select_final_grade rights.
Example Response:
Show provisional grade status for a student
ProvisionalGradesController#status
GET /api/v1/courses/:course_id/assignments/:assignment_id/provisional_grades/status
Scope: url:GET|/api/v1/courses/:course_id/assignments/:assignment_id/provisional_grades/status
Tell whether the student's submission needs one or more provisional grades.
Request Parameters:
student_id
integer
The id of the student to show the status for
Example Request:
Example Response:
Select provisional grade
ProvisionalGradesController#select
PUT /api/v1/courses/:course_id/assignments/:assignment_id/provisional_grades/:provisional_grade_id/select
Scope: url:PUT|/api/v1/courses/:course_id/assignments/:assignment_id/provisional_grades/:provisional_grade_id/select
Choose which provisional grade the student should receive for a submission. The caller must be the final grader for the assignment or an admin with :select_final_grade rights.
Example Response:
Publish provisional grades for an assignment
ProvisionalGradesController#publish
[DEPRECATED] This method is deprecated, effective 2026-10-15 (notice given 2026-07-15):
Publishing grades synchronously can time out for assignments with many submissions. Use the asynchronous Publish provisional grades (asynchronous) endpoint instead, which performs the publish in a background job and returns a Progress object that can be polled for completion.
POST /api/v1/courses/:course_id/assignments/:assignment_id/provisional_grades/publish
Scope: url:POST|/api/v1/courses/:course_id/assignments/:assignment_id/provisional_grades/publish
Publish the selected provisional grade for all submissions to an assignment. Use the "Select provisional grade" endpoint to choose which provisional grade to publish for a particular submission.
Students not in the moderation set will have their one and only provisional grade published.
WARNING: This is irreversible. This will overwrite existing grades in the gradebook.
Example Request:
Publish provisional grades for an assignment (asynchronous)
ProvisionalGradesController#publish_async
POST /api/v1/courses/:course_id/assignments/:assignment_id/provisional_grades/publish_async
Scope: url:POST|/api/v1/courses/:course_id/assignments/:assignment_id/provisional_grades/publish_async
Publish the selected provisional grade for all submissions to an assignment in a background job. Unlike the synchronous "Publish provisional grades" endpoint, this returns immediately with a Progress object that can be polled for completion.
Use the "Select provisional grade" endpoint to choose which provisional grade to publish for a particular submission.
Students not in the moderation set will have their one and only provisional grade published.
WARNING: This is irreversible. This will overwrite existing grades in the gradebook.
Example Request:
Returns a Progress object.
Show provisional grade status for a student
AnonymousProvisionalGradesController#status
GET /api/v1/courses/:course_id/assignments/:assignment_id/anonymous_provisional_grades/status
Scope: url:GET|/api/v1/courses/:course_id/assignments/:assignment_id/anonymous_provisional_grades/status
Determine whether or not the student's submission needs one or more provisional grades.
Request Parameters:
anonymous_id
string
The id of the student to show the status for
Example Request:
Example Response:
This documentation is generated directly from the Canvas LMS source code, available on Github.
Last updated
Was this helpful?