Get Started with the vClasses REST API in 5 Minutes

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

Set up your request headers

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.

Authorization: Bearer <your-token>
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:

TOKEN="your-token-here"

With $TOKEN set in your shell, you can copy and run every subsequent example without modification beyond replacing resource IDs.

List homework classes

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.

curl https://app.example.com/api/v3/admin/homeworks \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

Example response:

{
  "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.

Retrieve a single homework

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.

curl https://app.example.com/api/v3/admin/homeworks/42 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

Example response:

{
  "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.

Grade a submission

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.

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:

{
  "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 for complete endpoint documentation, all request parameters, and every possible response shape.

​Prerequisites

Prerequisites