Skip to main content
Grades are generated automatically by the background grading worker after a session ends. There is no endpoint to create grades manually — they are produced asynchronously via Celery. Grading rubric (current):
CriterionWeight
Critical Thinking40%
Comprehension30%
Communication30%

​
List Grades

GET /v1/grades
Returns a paginated list of grades. Students see only their own grades. Admins and faculty can filter by any user.

​
Authentication

Requires a valid access token (any role). Students are automatically scoped to their own grades.

​
Query parameters

​
user_id
string
Filter by user ID. Only available to ADMIN, SUPER_ADMIN, and FACULTY roles.
​
content_id
string
Filter by case study ID.
​
skip
integer
default:"0"
Number of records to skip.
​
limit
integer
default:"20"
Max records to return (1–100).

​
Example request

curl "https://mind-be.staging.miva.university/v1/grades?content_id=6650e5f6a7b8c9d0e1f2a3b4" \
  -H "Authorization: Bearer <access_token>"

​
Response

{
  "success": true,
  "data": [
    {
      "id": "6651b2c3d4e5f6a7b8c9d0e1",
      "user_id": "6650a1b2c3d4e5f6a7b8c9d0",
      "session_id": "6651a1b2c3d4e5f6a7b8c9d0",
      "final_score": 78.5,
      "created_at": "2025-06-01T14:30:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 20,
  "total_pages": 1,
  "message": null
}

​
Get Grade by Session

GET /v1/grades/session/{session_id}
Get the full grade report for a specific session. This is the most common way to look up a grade — by the session it belongs to.

​
Authentication

Requires a valid access token. Students can only view grades for their own sessions. Admins and faculty can view any session’s grade.

​
Path parameters

​
session_id
string
required
The session ID.

​
Example request

curl https://mind-be.staging.miva.university/v1/grades/session/6651a1b2c3d4e5f6a7b8c9d0 \
  -H "Authorization: Bearer <access_token>"

​
Response

{
  "success": true,
  "data": {
    "id": "6651b2c3d4e5f6a7b8c9d0e1",
    "user_id": "6650a1b2c3d4e5f6a7b8c9d0",
    "user_name": "Jane Doe",
    "session_id": "6651a1b2c3d4e5f6a7b8c9d0",
    "content_type_id": "case_study",
    "content_id": "6650e5f6a7b8c9d0e1f2a3b4",
    "rubric_id": null,
    "overall_summary": "The student demonstrated solid clinical reasoning and asked appropriate follow-up questions. Communication was clear and empathetic.",
    "final_score": 78.5,
    "items": [
      {
        "criterion_name": "Critical Thinking",
        "score": 32.0,
        "max_score": 40.0,
        "weight": 0.4,
        "feedback": "Good differential diagnosis approach. Could have explored medication history more thoroughly.",
        "sequence": 1
      },
      {
        "criterion_name": "Comprehension",
        "score": 24.0,
        "max_score": 30.0,
        "weight": 0.3,
        "feedback": "Demonstrated understanding of the patient's condition and symptoms.",
        "sequence": 2
      },
      {
        "criterion_name": "Communication",
        "score": 22.5,
        "max_score": 30.0,
        "weight": 0.3,
        "feedback": "Clear and empathetic communication. Used appropriate medical terminology while remaining accessible.",
        "sequence": 3
      }
    ],
    "strengths": [
      {
        "title": "Empathetic Communication",
        "description": "Showed genuine concern for the patient's wellbeing and used reassuring language."
      },
      {
        "title": "Systematic Assessment",
        "description": "Followed a logical assessment structure covering key areas."
      }
    ],
    "weaknesses": [
      {
        "title": "Medication History",
        "description": "Did not ask about current medications or allergies early in the consultation."
      }
    ],
    "score_justifications": {
      "critical_thinking": "Scored 80% — demonstrated good clinical reasoning but missed medication review.",
      "comprehension": "Scored 80% — understood the case context well.",
      "communication": "Scored 75% — effective communication with minor areas for improvement."
    },
    "created_at": "2025-06-01T14:30:00Z"
  },
  "message": null
}

​
Grade item schema

FieldTypeDescription
user_namestring | nullDisplay name of the graded user
criterion_namestringName of the rubric criterion
scorefloatPoints earned
max_scorefloatMaximum possible points
weightfloatWeight of this criterion (0–1)
feedbackstringAI-generated feedback for this criterion
sequenceintegerDisplay order
score_justifications uses snake_case keys:
  • critical_thinking
  • comprehension
  • communication

​
Error responses

StatusCodeCondition
404NOT_FOUNDNo grade found for this session (grading may still be in progress)
403AUTHORIZATION_ERRORStudent trying to view another user’s grade

​
Get Grade by ID

GET /v1/grades/{grade_id}
Get a grade by its own ID. Returns the same full grade report as Get Grade by Session.

​
Authentication

Requires a valid access token. Students can only view their own grades.

​
Path parameters

​
grade_id
string
required
The grade ID.

​
Example request

curl https://mind-be.staging.miva.university/v1/grades/6651b2c3d4e5f6a7b8c9d0e1 \
  -H "Authorization: Bearer <access_token>"

​
Response

Same shape as Get Grade by Session.

​
Error responses

StatusCodeCondition
404NOT_FOUNDGrade not found
403AUTHORIZATION_ERRORStudent trying to view another user’s grade