> ## 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 Started with the vClasses REST API in 5 Minutes
> Learn how to authenticate and make your first vClasses API calls to list homework assignments, inspect submissions, and grade student work.
This quickstart walks you through the most common admin workflow in the vClasses API: listing homework assignments, inspecting a single assignment, and recording a grade on a student submission. By the end, you will have made four real API calls and seen the shape of the core response objects your integration will work with every day. All examples use `curl` so you can run them directly from your terminal without any additional tooling.
## Prerequisites
* **Bearer token** — You need a valid admin-scoped Bearer token before making any API call. See the [Authentication](/docs/authentication) guide for instructions on obtaining and refreshing your token.
* **A homework submission to grade** — Steps 3 and 4 reference specific resource IDs (`42` for a homework, `101` for a submission). Replace these with real IDs from your account as you follow along.
***
Every vClasses API request requires two headers. Set them once in your HTTP client or export them as shell variables so you do not have to repeat them in every command.
```bash theme={null}
Authorization: Bearer
Accept: application/json
```
In `curl`, you pass headers with the `-H` flag. All examples in this guide use the following shell variable pattern so the headers stay readable:
```bash theme={null}
TOKEN="your-token-here"
```
With `$TOKEN` set in your shell, you can copy and run every subsequent example without modification beyond replacing resource IDs.
Retrieve a paginated list of all homework assignments visible to your admin account. This is typically the first call you make when building a review queue or a reporting dashboard.
```bash theme={null}
curl https://app.example.com/api/v3/admin/homeworks \
-H "Authorization: Bearer $TOKEN" \
-H "Accept: application/json"
```
**Example response:**
```json theme={null}
{
"data": [
{
"id": 42,
"title": "Week 3 Reading Comprehension",
"description": "Answer all questions on pages 4–7 of the attached PDF.",
"pdf_url": "https://app.example.com/storage/homeworks/week3-reading.pdf",
"due_at": "2025-02-14T23:59:00Z",
"max_score": 10,
"submissions_count": 24,
"graded_count": 17,
"created_at": "2025-02-01T09:00:00Z"
}
],
"current_page": 1,
"last_page": 4,
"per_page": 15,
"total": 58
}
```
The response wraps all records in a `data` array and includes pagination metadata. Use the `page` query parameter — e.g., `?page=2` — to advance through additional pages. The `submissions_count` and `graded_count` fields give you an at-a-glance progress indicator for each assignment.
Once you have a homework ID from the list, fetch its full detail record. This includes the complete assignment metadata and is useful for displaying assignment details in a student or instructor view.
```bash theme={null}
curl https://app.example.com/api/v3/admin/homeworks/42 \
-H "Authorization: Bearer $TOKEN" \
-H "Accept: application/json"
```
**Example response:**
```json theme={null}
{
"data": {
"id": 42,
"title": "Week 3 Reading Comprehension",
"description": "Answer all questions on pages 4–7 of the attached PDF.",
"pdf_url": "https://app.example.com/storage/homeworks/week3-reading.pdf",
"due_at": "2025-02-14T23:59:00Z",
"max_score": 10,
"submissions_count": 24,
"graded_count": 17,
"created_at": "2025-02-01T09:00:00Z",
"updated_at": "2025-02-10T14:22:00Z",
"submissions": [
{
"id": 101,
"student_id": 305,
"student_name": "Alex Rivera",
"submitted_at": "2025-02-12T18:44:00Z",
"status": "pending_review",
"rating": null,
"comment": null
}
]
}
}
```
The `submissions` array lists every student submission linked to this homework. A `status` of `"pending_review"` means the submission has not yet been graded. Note the submission `id` field — you will pass that value to the grading endpoint in the next step.
Record a numerical rating and written feedback for a specific student submission. You target the submission by its ID (here, `101`) in the endpoint path and pass the grade data as a JSON body.
```bash theme={null}
curl -X POST https://app.example.com/api/v3/admin/homeworks/grade/101 \
-H "Authorization: Bearer $TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"rating": 8,
"comment": "Great effort. Review question 4."
}'
```
| Field | Type | Description |
| --------- | ------- | --------------------------------------------------------------------------------------- |
| `rating` | integer | Numeric score for the submission. Must be between `0` and the assignment's `max_score`. |
| `comment` | string | Written feedback visible to the student. Optional but strongly recommended. |
**Example success response:**
```json theme={null}
{
"message": "Submission graded successfully.",
"data": {
"id": 101,
"student_id": 305,
"student_name": "Alex Rivera",
"homework_id": 42,
"submitted_at": "2025-02-12T18:44:00Z",
"graded_at": "2025-02-13T10:05:00Z",
"status": "graded",
"rating": 8,
"comment": "Great effort. Review question 4."
}
}
```
A `200 OK` response with `"status": "graded"` confirms the grade was saved. The student can now see their score and feedback through the student-facing status endpoint. If you need to correct a grade, call the same endpoint again with updated values — the latest submission always overwrites the previous grade.
You have now completed the core admin workflow. To explore quizzes (`GET /api/v3/quiz/pdf-quizzes`), student submissions (`POST /api/v3/quiz/submit-pdf`), and quiz grading (`POST /api/v3/quiz/pdf-quizzes/grade/{grade_id}`), head to the [full API Reference](/docs/api-reference) for complete endpoint documentation, all request parameters, and every possible response shape.