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

# VClasses REST API — Overview, Base URL, and Conventions

> The VClasses REST API base URL, versioning scheme, required request headers, and response format conventions every integration must follow.

The VClasses REST API lets you programmatically manage PDF homework, quizzes, and grading from any HTTP client. Use it to build integrations that automate submission workflows, retrieve grading data, or embed VClasses functionality into your own tools and dashboards.

## Base URL

All endpoints share a single base URL. Every request you make must begin with this prefix:

```text theme={null}
https://app.example.com/api/v3
```

## API Version

The current API version is **v3**. The version segment is part of every endpoint path — you must include it in every URL you construct. There is no versionless alias.

## Request Format

### Required Headers

Include these headers on every request:

```http theme={null}
Authorization: Bearer <token>
Accept: application/json
```

### POST Requests — JSON Body

When sending a JSON payload in a POST request, add the `Content-Type` header:

```http theme={null}
Authorization: Bearer <token>
Accept: application/json
Content-Type: application/json
```

### POST Requests — File Upload

When uploading a file (such as a PDF submission), use multipart form data instead:

```http theme={null}
Authorization: Bearer <token>
Accept: application/json
Content-Type: multipart/form-data
```

## Response Format

All successful responses return JSON. Paginated list endpoints return a standard pagination envelope with the following structure:

```json theme={null}
{
  "current_page": 1,
  "data": [],
  "last_page": 4,
  "next_page_url": "https://app.example.com/api/v3/admin/homeworks?page=2",
  "per_page": 15,
  "total": 60
}
```

Non-paginated success responses return the resource object or a confirmation message directly in the JSON body.

## Endpoints Summary

| Method | Path                                        | Role    | Description                            |
| ------ | ------------------------------------------- | ------- | -------------------------------------- |
| GET    | `/api/v3/admin/homeworks`                   | Admin   | List homework classes with submissions |
| GET    | `/api/v3/admin/homeworks/{id}`              | Admin   | Get single homework with submissions   |
| POST   | `/api/v3/admin/homeworks/grade/{id}`        | Admin   | Grade a homework submission            |
| POST   | `/api/v3/quiz/submit-pdf`                   | Student | Submit PDF quiz answers                |
| GET    | `/api/v3/quiz/pdf-quizzes`                  | Admin   | List all PDF quizzes                   |
| GET    | `/api/v3/quiz/pdf-quizzes/{id}`             | Admin   | Get single PDF quiz with submissions   |
| POST   | `/api/v3/quiz/pdf-quizzes/grade/{grade_id}` | Admin   | Grade a quiz submission                |

<Tip>
  All endpoint paths in the table above are relative to `https://app.example.com`. Combine the base URL with the path to form a complete request URL — for example, `https://app.example.com/api/v3/admin/homeworks`.
</Tip>