quiz-grading
5 endpoints.
/api/grading-queue Bearer tokenList attempts awaiting grading
Every attempt in pending_grading across the quizzes the caller's quizzes:grade scope reaches, oldest submission first, one page at a time; `quiz` narrows it to one quiz. Each row says how many manually graded questions the paper holds and how many still want points — zero means the attempt is ready to finalize. A caller holding no quizzes:grade anywhere gets an empty list, not an error.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| quiz | query | string (uuid) | no | Only attempts of this quiz (UUID id). |
| limit | query | integer | no | Page size, 1-200. Defaults to 50. |
| cursor | query | string | no | Opaque cursor from a previous page's next_cursor. |
Responses
| Status | Description | Body |
|---|---|---|
| 200 | One page of the queue, and the cursor for the next. | GradingQueueList |
| 400 | The cursor is malformed. | ErrorResponse |
| 401 | The access token is missing or invalid. | ErrorResponse |
| 500 | The database could not be read. | ErrorResponse |
/api/quiz-attempts/{attempt_id}/grading Bearer tokenRead an attempt for grading
The attempt's paper as a marker sees it: every question with the taker's response, the correct answer where the kind has one, the rubric, and on manually graded questions the machine's suggestion, the points awarded so far and the feedback written. For holders of quizzes:grade or quizzes:read over the quiz; the taker reads their own paper through the review endpoint instead.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| attempt_id | path | string (uuid) | yes | UUID id of the attempt. |
Responses
| Status | Description | Body |
|---|---|---|
| 200 | The paper, marker fields included. | QuizAttemptReview |
| 401 | The access token is missing or invalid. | ErrorResponse |
| 404 | No visible attempt has that id. | ErrorResponse |
| 500 | The database could not be read. | ErrorResponse |
/api/quiz-attempts/{attempt_id}/grades/{question_id} Bearer tokenAward points on one question
Records the marker's points — and, when sent, feedback for the taker — on one manually graded question of a submitted attempt. Full marks records the question as correct. While the attempt awaits finalization the grade is a draft the taker cannot see; on an already finalized attempt the change rescores it at once, and if its results were released the learning record gains a further score row labelled as a regrade. Requires quizzes:grade over the quiz.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| attempt_id | path | string (uuid) | yes | UUID id of the attempt. |
| question_id | path | string (uuid) | yes | UUID id of a question on the attempt's paper. |
| Field | Type | Required | Description |
|---|---|---|---|
| points_awarded | integer | yes | Whole points, 0 up to the question's points_possible on this paper. Full marks records the question as correct; anything less as incorrect. minimum 0 |
| feedback_markdown | string | null | no | A note to the taker, as markdown, shown beside the question in their answer review once the attempt's results are released. Omit to keep the current note; send null or empty to clear it. at most 20000 characters |
Responses
| Status | Description | Body |
|---|---|---|
| 200 | The paper with the grade recorded. | QuizAttemptReview |
| 400 | The request body failed validation. | ErrorResponse |
| 401 | The access token is missing or invalid. | ErrorResponse |
| 403 | The caller can read this quiz but does not hold quizzes:grade. | ErrorResponse |
| 404 | No visible attempt has that id. | ErrorResponse |
| 409 | The attempt is still in progress, the question is not on its paper or not manually graded, or the points exceed what the question is worth. | ErrorResponse |
| 500 | The database could not be reached, or the write failed. | ErrorResponse |
/api/quiz-attempts/{attempt_id}/finalize-grading Bearer tokenFinalize an attempt's grading
Scores a pending_grading attempt from its points once every manually graded question has some, and moves it to submitted. Nothing is released by this: the taker sees the result only once an administrator releases the attempt. Requires quizzes:grade over the quiz.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| attempt_id | path | string (uuid) | yes | UUID id of the attempt. |
Responses
| Status | Description | Body |
|---|---|---|
| 200 | The scored paper. | QuizAttemptReview |
| 401 | The access token is missing or invalid. | ErrorResponse |
| 403 | The caller can read this quiz but does not hold quizzes:grade. | ErrorResponse |
| 404 | No visible attempt has that id. | ErrorResponse |
| 409 | The attempt is not awaiting grading, or a question still wants points. | ErrorResponse |
| 500 | The database could not be reached, or the write failed. | ErrorResponse |
/api/quizzes/{quiz_id}/release-attempts Bearer tokenRelease chosen attempts' results
Stamps results_released_at on the named attempts of the quiz, making each taker's score and pass/fail visible to them and — for attempts that needed a marker — reporting the score into their learning record. Only scored (submitted), unreleased attempts of this quiz are stamped; the rest of the list is skipped and the response says which ids went. Expired in-progress attempts are finalized first. Requires quizzes:write over the quiz's owner.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| quiz_id | path | string | yes | UUID id, or a slug resolved within the organization given by the org query parameter. |
| org | query | string | no | Organization UUID id or slug to filter by (and to resolve slug refs in). |
| Field | Type | Required | Description |
|---|---|---|---|
| attempt_ids | array of string (uuid) | yes | Attempts of this quiz to release. Ones already released, still in progress or still awaiting grading are skipped, not refused; ids of other quizzes are ignored. 1–500 items |
Responses
| Status | Description | Body |
|---|---|---|
| 200 | Which attempts were released. | ReleaseAttemptsResponse |
| 400 | The request body failed validation. | ErrorResponse |
| 401 | The access token is missing or invalid. | ErrorResponse |
| 403 | The caller can read this quiz but does not hold quizzes:write. | ErrorResponse |
| 404 | No visible quiz has that id or slug. | ErrorResponse |
| 500 | The database could not be reached, or the write failed. | ErrorResponse |