Moderated Grading API

BETA: This API resource is not finalized, and there could be breaking changes before its final release.

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 ModerationSetController#index

BETA: This API endpoint is not finalized, and there could be breaking changes before its final release.

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 Users

Select students for moderation ModerationSetController#create

BETA: This API endpoint is not finalized, and there could be breaking changes before its final release.

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:

Parameter		Type	Description
student_ids[]		number	user ids for students to select for moderation

Returns a list of Users

Show provisional grade status for a student ProvisionalGradesController#status

BETA: This API endpoint is not finalized, and there could be breaking changes before its final release.

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:

Parameter		Type	Description
student_id		integer	The id of the student to show the status for

Example Request:

curl 'https://<canvas>/api/v1/courses/1/assignments/2/provisional_grades/status?student_id=1'

Example Response:

{ "needs_provisional_grade": false }

Select provisional grade ProvisionalGradesController#select

BETA: This API endpoint is not finalized, and there could be breaking changes before its final release.

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 have :moderate_grades rights.

Example Response:

{
  "assignment_id": 867,
  "student_id": 5309,
  "selected_provisional_grade_id": 53669
}

Copy provisional grade ProvisionalGradesController#copy_to_final_mark

BETA: This API endpoint is not finalized, and there could be breaking changes before its final release.

POST /api/v1/courses/:course_id/assignments/:assignment_id/provisional_grades/:provisional_grade_id/copy_to_final_mark

Scope:

url:POST|/api/v1/courses/:course_id/assignments/:assignment_id/provisional_grades/:provisional_grade_id/copy_to_final_mark

Given a provisional grade, copy the grade (and associated submission comments and rubric assessments) to a “final” mark which can be edited or commented upon by a moderator prior to publication of grades.

Notes:

The student must be in the moderation set for the assignment.
The newly created grade will be selected.
The caller must have “Moderate Grades” rights in the course.

Returns a ProvisionalGrade

Publish provisional grades for an assignment ProvisionalGradesController#publish

BETA: This API endpoint is not finalized, and there could be breaking changes before its final release.

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:

curl 'https://<canvas>/api/v1/courses/1/assignments/2/provisional_grades/publish' \
     -X POST

Show provisional grade status for a student AnonymousProvisionalGradesController#status

BETA: This API endpoint is not finalized, and there could be breaking changes before its final release.

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:

Parameter		Type	Description
anonymous_id		string	The id of the student to show the status for

Example Request:

curl 'https://<canvas>/api/v1/courses/1/assignments/2/anonymous_provisional_grades/status?anonymous_id=1'

Example Response:

{ "needs_provisional_grade": false }