Skip to main content
This endpoint grades a student’s homework submission by setting a numeric rating and an optional written comment, marking the submission as reviewed. Use it to provide feedback after evaluating a student’s uploaded work.

​
Endpoint

POST /api/v3/admin/homeworks/grade/{id}
Required role: Admin

​
Required Headers

HeaderValue
AuthorizationBearer <token>
Acceptapplication/json
Content-Typeapplication/json

​
Path Parameters

​
id
integer
required
The unique submission ID. Must be a numeric value.

​
Request Body

​
rating
integer
required
The numeric grade to assign to the submission. Must be an integer between 1 and 10 (inclusive).
​
comment
string
Optional written feedback for the student. Maximum 1000 characters.

​
Example Request

curl -X POST https://app.example.com/api/v3/admin/homeworks/grade/101 \
  -H "Authorization: Bearer your-token" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"rating": 8, "comment": "Great effort. Review question 4."}'

​
Response

​
200 OK

Returns a confirmation message and the updated SubmissionObject reflecting the saved grade. 
{
  "message": "Grade Saved Successfully",
  "data": {
    "id": 101,
    "student_id": 77,
    "student_name": "Ahmed Ali",
    "student_email": "ahmed@example.com",
    "rating": 8,
    "instructor_comment": "Great effort. Review question 4.",
    "is_reviewed": true,
    "submitted_at": "2026-06-05 14:30:00",
    "files": [{"id": 55, "name": "my_homework.pdf", "url": "https://cdn.example.com/media/55/my_homework.pdf"}],
    "download_url": "https://app.example.com/api/v3/assignments/download/101"
  }
}

​
Validation Error Responses (422)

The API returns a 422 status with field-level error details when request body validation fails. The examples below show the possible validation errors: Missing rating: 
{"message": "ValidationError", "errors": {"rating": ["The rating field is required."]}}
Rating out of range: 
{"message": "ValidationError", "errors": {"rating": ["The rating must be between 1 and 10."]}}
Comment too long: 
{"message": "ValidationError", "errors": {"comment": ["The comment may not be greater than 1000 characters."]}}

​
Error Responses

StatusMessageCause
401UnauthorizedRequestMissing or invalid token, or the authenticated user does not have the Admin role.
404PDF Homework not foundNo submission exists with the given ID.
422ValidationErrorrating is missing, not an integer, or outside the 1–10 range; or comment exceeds 1000 characters.
Grading is idempotent — calling this endpoint again on the same submission overwrites the previous rating and comment. There is no lock once a submission is marked as reviewed, so you can update a grade at any time.