Exams API: Create, Publish, and Assign Student Exams

The Exams API is the core of ExamPlatform’s content management surface. Examiners and admins use these endpoints to draft new exams, configure scoring rules and AI evaluation settings, assign students, and publish exams when they are ready. Students accessing the API see only the exams they have been assigned to. All mutating endpoints require at minimum the examiner role; deletion and force-sensitive operations require admin.

GET /api/exams

Retrieve the list of exams accessible to the authenticated user. For examiners and admins, this returns all exams on the platform. For students, only exams they have been assigned to are returned.

Query Parameters

status

string

Filter by exam status. Accepted values: draft, upcoming, active, live, completed.

subject

string

Filter by subject name (case-insensitive partial match).

Example Request

curl https://your-domain.com/api/exams?status=upcoming&subject=Mathematics \
  -H "Authorization: Bearer <token>"

Example Response

[
  {
    "id": "exam_01J4HQRZMB",
    "title": "Mid-Semester Mathematics",
    "subject": "Mathematics",
    "start_time": "2024-11-15T09:00:00Z",
    "end_time": "2024-11-15T12:00:00Z",
    "duration_minutes": 180,
    "status": "upcoming",
    "total_questions": 50
  }
]

POST /api/exams

Create a new exam in draft status. The exam is not visible to students and cannot be started until it is published via POST /api/exams/:id/publish. Requires Examiner or Admin role.

Request Body

title

string

required

Display title of the exam (e.g., "Final Examination — Computer Science").

subject

string

required

Subject or course the exam belongs to.

start_time

string

required

ISO 8601 datetime for when the exam window opens (e.g., "2024-11-15T09:00:00Z").

end_time

string

required

ISO 8601 datetime for when the exam window closes. Must be after start_time.

duration_minutes

integer

required

Time limit in minutes that a student has to complete the exam once they begin.

total_questions

integer

required

Number of questions to include in this exam.

negative_marking

boolean

required

If true, incorrect answers deduct marks as configured per question.

enable_ai_evaluation

boolean

required

If true, subjective answers are automatically evaluated by the AI grading engine after submission.

allow_manual_review

boolean

required

If true, examiners can manually override AI-assigned grades.

route_to_manual_after_ai

boolean

required

If true, all AI-evaluated answers are flagged for human review before results are published.

passing_percentage

float

Minimum score percentage required to pass the exam. Defaults to 40 if not provided.

instructions

string

Exam instructions shown to students before they begin. Supports plain text.

Example Request

curl -X POST https://your-domain.com/api/exams \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Final Examination — Computer Science",
    "subject": "Computer Science",
    "start_time": "2024-12-10T09:00:00Z",
    "end_time": "2024-12-10T12:00:00Z",
    "duration_minutes": 180,
    "total_questions": 60,
    "passing_percentage": 50,
    "negative_marking": true,
    "instructions": "Read all questions carefully. Use of electronic devices is prohibited.",
    "enable_ai_evaluation": true,
    "allow_manual_review": true,
    "route_to_manual_after_ai": false
  }'

Example Response

{
  "id": "exam_01J5CKWPNR",
  "title": "Final Examination — Computer Science",
  "subject": "Computer Science",
  "start_time": "2024-12-10T09:00:00Z",
  "end_time": "2024-12-10T12:00:00Z",
  "duration_minutes": 180,
  "total_questions": 60,
  "passing_percentage": 50,
  "negative_marking": true,
  "enable_ai_evaluation": true,
  "allow_manual_review": true,
  "route_to_manual_after_ai": false,
  "status": "draft",
  "created_at": "2024-11-01T14:22:10Z"
}

PATCH /api/exams/:id

Update fields on an existing exam. Most fields are editable while the exam is in draft status. Structural changes (questions, timing, scoring) may be restricted once the exam is published. Requires Examiner or Admin role.

Path Parameters

string

required

The unique identifier of the exam to update.

Request Body

Send any subset of the fields accepted by POST /api/exams. Only provided fields are updated; omitted fields remain unchanged.

Example Request

curl -X PATCH https://your-domain.com/api/exams/exam_01J5CKWPNR \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "passing_percentage": 55,
    "instructions": "Updated instructions: Attempt all sections."
  }'

Example Response

{
  "id": "exam_01J5CKWPNR",
  "title": "Final Examination — Computer Science",
  "passing_percentage": 55,
  "instructions": "Updated instructions: Attempt all sections.",
  "status": "draft"
}

DELETE /api/exams/:id

Permanently delete an exam draft. Requires Admin role. Only exams in draft status can be deleted; published or live exams must be handled through other administrative workflows.

Path Parameters

string

required

The unique identifier of the exam to delete.

Example Request

curl -X DELETE https://your-domain.com/api/exams/exam_01J5CKWPNR \
  -H "Authorization: Bearer <token>"

Response

Returns 204 No Content on success with no response body.

POST /api/exams/:id/publish

Publish an exam, transitioning its status from draft to upcoming. Once published, the exam becomes visible to assigned students and will become live when the start_time is reached. Requires Examiner or Admin role.

Path Parameters

string

required

The unique identifier of the exam to publish.

Example Request

curl -X POST https://your-domain.com/api/exams/exam_01J5CKWPNR/publish \
  -H "Authorization: Bearer <token>"

Example Response

{
  "id": "exam_01J5CKWPNR",
  "title": "Final Examination — Computer Science",
  "status": "upcoming",
  "published_at": "2024-11-02T08:00:00Z"
}

Publishing an exam is difficult to reverse. Before publishing, verify that all questions have been added and configured correctly, that student assignments are complete, and that the exam window (start/end time) and duration are accurate. Editing structural fields after publishing may not be possible without admin intervention.

POST /api/exams/:id/assign

Assign one or more students to an exam. Only assigned students can access and sit the exam. This endpoint can be called multiple times to add students incrementally; re-assigning a student who is already enrolled has no effect. Requires Examiner or Admin role.

Path Parameters

string

required

The unique identifier of the exam.

Request Body

student_ids

array

required

An array of user ID strings identifying the students to assign. Example: ["usr_01J2K9XMAB", "usr_01J3P7RQZN"].

Example Request

curl -X POST https://your-domain.com/api/exams/exam_01J5CKWPNR/assign \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "student_ids": ["usr_01J2K9XMAB", "usr_01J3P7RQZN", "usr_01J4HQRZMB"]
  }'

Example Response

{
  "exam_id": "exam_01J5CKWPNR",
  "assigned_count": 3,
  "message": "3 student(s) successfully assigned to the exam."
}

Configuration

API Reference

Exams API: Create, Publish, and Assign Student Exams

GET /api/exams

Query Parameters

Example Request

Example Response

POST /api/exams

Request Body

Example Request

Example Response

PATCH /api/exams/:id

Path Parameters

Request Body

Example Request

Example Response

DELETE /api/exams/:id

Path Parameters

Example Request

Response

POST /api/exams/:id/publish

Path Parameters

Example Request

Example Response

POST /api/exams/:id/assign

Path Parameters

Request Body

Example Request

Example Response

Build docs developers (and LLMs) love

Configuration

API Reference

Documentation Index

​GET /api/exams

​Query Parameters

​Example Request

​Example Response

​POST /api/exams

​Request Body

​Example Request

​Example Response

​PATCH /api/exams/:id

​Path Parameters

​Request Body

​Example Request

​Example Response

​DELETE /api/exams/:id

​Path Parameters

​Example Request

​Response

​POST /api/exams/:id/publish

​Path Parameters

​Example Request

​Example Response

​POST /api/exams/:id/assign

​Path Parameters

​Request Body

​Example Request

​Example Response

Build docs developers (and LLMs) love

GET /api/exams

Query Parameters

Example Request

Example Response

POST /api/exams

Request Body

Example Request

Example Response

PATCH /api/exams/:id

Path Parameters

Request Body

Example Request

Example Response

DELETE /api/exams/:id

Path Parameters

Example Request

Response

POST /api/exams/:id/publish

Path Parameters

Example Request

Example Response

POST /api/exams/:id/assign

Path Parameters

Request Body

Example Request

Example Response