> ## 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.

# GET /api/v3/admin/homeworks — List PDF Homework Classes

> Retrieve a paginated list of classes with PDF homework assignments, including all student submissions. Supports filtering by course ID and pagination controls.

This endpoint returns a paginated list of every class that has a PDF homework assignment attached, along with all student submissions for each class. Use the query parameters to filter by course or control pagination.

## Endpoint

```
GET /api/v3/admin/homeworks
```

**Required role:** Admin

## Required Headers

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

## Query Parameters

<ParamField query="course_id" type="integer">
  Filter results to a specific course by its ID. Omit to return classes across all courses.
</ParamField>

<ParamField query="per_page" type="integer" default="15">
  Number of homework classes to return per page.
</ParamField>

<ParamField query="page" type="integer" default="1">
  Page number to retrieve.
</ParamField>

## Example Request

```bash theme={null}
curl -X GET "https://app.example.com/api/v3/admin/homeworks?page=1&per_page=15" \
  -H "Authorization: Bearer your-token" \
  -H "Accept: application/json"
```

## Response

### 200 OK

```json theme={null}
{
  "current_page": 1,
  "data": [
    {
      "id": 42,
      "title": "Lesson 3 — Algebra",
      "course_id": 5,
      "course_title": "Math Grade 10",
      "has_assignment": true,
      "assignment_deadline": "30/06/2026 11:59 PM",
      "assignment_description": "Solve problems 1-10 from chapter 3.",
      "assignment_file_url": "https://cdn.example.com/media/10/homework.pdf",
      "created_at": "2026-06-01 10:00:00",
      "submissions": [
        {
          "id": 101,
          "student_id": 77,
          "student_name": "Ahmed Ali",
          "student_email": "ahmed@example.com",
          "rating": null,
          "instructor_comment": null,
          "is_reviewed": false,
          "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"
        }
      ]
    }
  ],
  "first_page_url": "https://app.example.com/api/v3/admin/homeworks?page=1",
  "from": 1,
  "last_page": 3,
  "last_page_url": "https://app.example.com/api/v3/admin/homeworks?page=3",
  "next_page_url": "https://app.example.com/api/v3/admin/homeworks?page=2",
  "path": "https://app.example.com/api/v3/admin/homeworks",
  "per_page": 15,
  "prev_page_url": null,
  "to": 15,
  "total": 32
}
```

### Response Fields

<ResponseField name="current_page" type="integer">
  The current page number in the paginated result set.
</ResponseField>

<ResponseField name="data" type="array">
  Array of HomeworkObject items representing classes with PDF homework assignments.

  <Expandable title="HomeworkObject fields">
    <ResponseField name="id" type="integer">
      The unique class ID.
    </ResponseField>

    <ResponseField name="title" type="string">
      The title of the class.
    </ResponseField>

    <ResponseField name="course_id" type="integer">
      The ID of the parent course this class belongs to.
    </ResponseField>

    <ResponseField name="course_title" type="string | null">
      The title of the parent course. Returns `null` if the course has been deleted.
    </ResponseField>

    <ResponseField name="has_assignment" type="boolean">
      Indicates whether the class has a PDF homework assignment. Always `true` for results returned by this endpoint.
    </ResponseField>

    <ResponseField name="assignment_deadline" type="string | null">
      The submission deadline for the assignment, formatted as `dd/MM/YYYY hh:mm AM|PM`. Returns `null` if no deadline was set.
    </ResponseField>

    <ResponseField name="assignment_description" type="string | null">
      The instructor's written homework instructions. Returns `null` if no description was provided.
    </ResponseField>

    <ResponseField name="assignment_file_url" type="string | null">
      The URL to the instructor's homework PDF file. Returns `null` if no file has been uploaded.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      The timestamp when the class was created, formatted as `YYYY-MM-DD HH:mm:ss`.
    </ResponseField>

    <ResponseField name="submissions" type="array">
      Array of SubmissionObjects representing student homework submissions. Returns an empty array if no submissions exist.

      <Expandable title="SubmissionObject fields">
        <ResponseField name="id" type="integer">
          The unique submission ID.
        </ResponseField>

        <ResponseField name="student_id" type="integer">
          The user ID of the student who submitted the homework.
        </ResponseField>

        <ResponseField name="student_name" type="string | null">
          The full name of the student. Returns `null` if the user account has been deleted.
        </ResponseField>

        <ResponseField name="student_email" type="string | null">
          The email address of the student. Returns `null` if the user account has been deleted.
        </ResponseField>

        <ResponseField name="rating" type="integer | null">
          The grade awarded for this submission, on a scale of 1–10. Returns `null` if the submission has not yet been graded.
        </ResponseField>

        <ResponseField name="instructor_comment" type="string | null">
          Written feedback from the instructor. Returns `null` if no comment has been provided.
        </ResponseField>

        <ResponseField name="is_reviewed" type="boolean">
          Indicates whether the submission has been graded. `true` if a rating has been assigned.
        </ResponseField>

        <ResponseField name="submitted_at" type="string">
          The timestamp when the student submitted the homework, formatted as `YYYY-MM-DD HH:mm:ss`.
        </ResponseField>

        <ResponseField name="files" type="array">
          Array of FileObjects representing the files attached to this submission. This field is absent if no files were uploaded.

          <Expandable title="FileObject fields">
            <ResponseField name="id" type="integer">
              The unique file ID.
            </ResponseField>

            <ResponseField name="name" type="string">
              The original filename of the uploaded file.
            </ResponseField>

            <ResponseField name="url" type="string">
              The direct URL to access or download the file.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="download_url" type="string | null">
          A URL to download all submission files as a ZIP archive. Returns `null` if no files are attached.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="first_page_url" type="string">
  The full URL for the first page of results.
</ResponseField>

<ResponseField name="from" type="integer">
  The 1-based index of the first item on the current page.
</ResponseField>

<ResponseField name="last_page" type="integer">
  The number of the last available page.
</ResponseField>

<ResponseField name="last_page_url" type="string">
  The full URL for the last page of results.
</ResponseField>

<ResponseField name="next_page_url" type="string | null">
  The full URL for the next page of results. Returns `null` when you are on the last page.
</ResponseField>

<ResponseField name="path" type="string">
  The base URL of the endpoint, without pagination query parameters.
</ResponseField>

<ResponseField name="per_page" type="integer">
  The number of items returned per page, matching the `per_page` query parameter.
</ResponseField>

<ResponseField name="prev_page_url" type="string | null">
  The full URL for the previous page of results. Returns `null` when you are on the first page.
</ResponseField>

<ResponseField name="to" type="integer">
  The 1-based index of the last item on the current page.
</ResponseField>

<ResponseField name="total" type="integer">
  The total number of homework classes matching the query across all pages.
</ResponseField>

## Error Responses

| Status | Message               | Cause                                                                             |
| ------ | --------------------- | --------------------------------------------------------------------------------- |
| `401`  | `UnauthorizedRequest` | Missing or invalid token, or the authenticated user does not have the Admin role. |