Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Saurabh-07586/examplatform/llms.txt

Use this file to discover all available pages before exploring further.

The Submissions API gives examiners and admins visibility into and control over student exam sessions. Once a student completes an exam, a submission record is created capturing their answers, timing metadata, and (where AI evaluation is enabled) automated scores. Examiners use this API to review and override AI grades on subjective questions. Admins can force-submit an in-progress session when necessary — for example, if a student’s connection drops and the session cannot be auto-submitted.

​
GET /api/submissions

Retrieve a list of exam submissions. Requires Examiner or Admin role. Results are scoped to exams that the authenticated user has access to.

​
Query Parameters

​
exam_id
string
Filter submissions by exam. Returns only submissions belonging to the specified exam ID.
​
status
string
Filter by submission status. Accepted values: submitted, graded, published.
  • submitted — The exam has been completed but not fully graded.
  • graded — All answers have been scored (by AI and/or manual review).
  • published — The result has been released to the student.

​
Example Request

curl "https://your-domain.com/api/submissions?exam_id=exam_01J5CKWPNR&status=submitted" \
  -H "Authorization: Bearer <token>"

​
Example Response

[
  {
    "id": "sub_01J7NQVRMZ",
    "exam_id": "exam_01J5CKWPNR",
    "student_id": "usr_01J3P7RQZN",
    "student_name": "Arjun Sharma",
    "submitted_at": "2024-12-10T11:48:35Z",
    "status": "submitted",
    "score": null
  },
  {
    "id": "sub_01J7NQVS4K",
    "exam_id": "exam_01J5CKWPNR",
    "student_id": "usr_01J4HQRZMB",
    "student_name": "Priya Menon",
    "submitted_at": "2024-12-10T11:55:12Z",
    "status": "graded",
    "score": 78.5
  }
]

​
POST /api/submissions/:id/grade

Submit a manual grade for a specific subjective answer within a submission. This is used by examiners to review AI-suggested scores and either confirm or override them. The grade provided becomes the final, authoritative score for that answer. Requires Examiner or Admin role.

​
Path Parameters

​
id
string
required
The unique identifier of the submission being graded.

​
Request Body

​
question_id
string
required
The ID of the question whose answer is being graded.
​
grade
float
required
The score to award for this answer. This value overrides any AI-assigned suggestion and becomes the final score for the answer. Must be between 0 and the question’s configured marks value.
​
feedback
string
Optional written feedback for the student explaining the grade. Included in the student’s result report if results are published.

​
Example Request

curl -X POST https://your-domain.com/api/submissions/sub_01J7NQVRMZ/grade \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "question_id": "qst_01J6MNPWRK",
    "grade": 7.5,
    "feedback": "Good analysis, but the conclusion was incomplete. Deducted 0.5 marks."
  }'

​
Example Response

{
  "submission_id": "sub_01J7NQVRMZ",
  "question_id": "qst_01J6MNPWRK",
  "grade": 7.5,
  "ai_suggested_grade": 8.0,
  "feedback": "Good analysis, but the conclusion was incomplete. Deducted 0.5 marks.",
  "graded_by": "usr_01J2K9XMAB",
  "graded_at": "2024-12-11T10:22:05Z"
}
The grade value you provide fully overrides the AI suggestion — there is no blending or averaging. The value you submit here is the final score recorded for the answer. If allow_manual_review is enabled on the exam, this endpoint is the intended mechanism for examiner sign-off.

​
POST /api/submissions/:id/force-submit

Force-submit an active exam session on behalf of a student. When called, the student’s current saved answers are immediately locked and the submission is finalized as if the student had clicked “Submit”. This is an administrative action intended for edge cases such as connectivity failures, browser crashes where auto-submit did not fire, or disciplinary incidents. Requires Admin role.

​
Path Parameters

​
id
string
required
The unique identifier of the active submission (session) to force-submit.

​
Request Body

No request body is required for this endpoint.

​
Example Request

curl -X POST https://your-domain.com/api/submissions/sub_01J7NQVRMZ/force-submit \
  -H "Authorization: Bearer <token>"

​
Example Response

{
  "id": "sub_01J7NQVRMZ",
  "exam_id": "exam_01J5CKWPNR",
  "student_id": "usr_01J3P7RQZN",
  "student_name": "Arjun Sharma",
  "submitted_at": "2024-12-10T11:03:47Z",
  "status": "submitted",
  "force_submitted": true,
  "force_submitted_by": "usr_00J1ADMINXZ"
}
Force-submit is irreversible. The student’s answers as saved at the moment of the call are submitted immediately — any unsaved progress in the student’s browser session is lost. Use this endpoint only when necessary, and ensure the action is recorded in your administrative notes. All force-submit events are captured in the audit log.

Build docs developers (and LLMs) love

Get started for freeTalk to us