> ## Documentation Index
> Fetch the complete documentation index at: https://developer.vclasses.net/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /api/v3/admin/homeworks/grade/{id} — Grade Submission

> Grade a student homework submission with a rating from 1 to 10 and an optional comment. Marks the submission as reviewed. Grades can be overwritten at any time.

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

| Header          | Value              |
| --------------- | ------------------ |
| `Authorization` | `Bearer <token>`   |
| `Accept`        | `application/json` |
| `Content-Type`  | `application/json` |

## Path Parameters

<ParamField path="id" type="integer" required>
  The unique submission ID. Must be a numeric value.
</ParamField>

## Request Body

<ParamField body="rating" type="integer" required>
  The numeric grade to assign to the submission. Must be an integer between `1` and `10` (inclusive).
</ParamField>

<ParamField body="comment" type="string">
  Optional written feedback for the student. Maximum 1000 characters.
</ParamField>

## Example Request

```bash theme={null}
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.

```json theme={null}
{
  "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:**

```json theme={null}
{"message": "ValidationError", "errors": {"rating": ["The rating field is required."]}}
```

**Rating out of range:**

```json theme={null}
{"message": "ValidationError", "errors": {"rating": ["The rating must be between 1 and 10."]}}
```

**Comment too long:**

```json theme={null}
{"message": "ValidationError", "errors": {"comment": ["The comment may not be greater than 1000 characters."]}}
```

## Error Responses

| Status | Message                  | Cause                                                                                                 |
| ------ | ------------------------ | ----------------------------------------------------------------------------------------------------- |
| `401`  | `UnauthorizedRequest`    | Missing or invalid token, or the authenticated user does not have the Admin role.                     |
| `404`  | `PDF Homework not found` | No submission exists with the given ID.                                                               |
| `422`  | `ValidationError`        | `rating` is missing, not an integer, or outside the 1–10 range; or `comment` exceeds 1000 characters. |

<Tip>
  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.
</Tip>