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 Questions API manages ExamPlatform’s centralized question bank — the library of questions that examiners draw from when composing exams. Questions support five answer types, configurable difficulty levels, per-question marks and negative marks, and word-count constraints for written responses. The bank can be populated manually through the API or via bulk import from CSV files, PDF documents, or Google Form exports. All endpoints require at minimum the examiner role.

​
GET /api/questions

Retrieve a filtered list of questions from the question bank. Requires Examiner or Admin role.

​
Query Parameters

​
subject
string
Filter questions by subject (case-insensitive partial match).
​
type
string
Filter by question type. Accepted values: mcq, multiselect, short_answer, long_answer, image_upload.
​
difficulty
string
Filter by difficulty level. Accepted values: easy, medium, hard.
​
search
string
Full-text search across question text and topic fields.

​
Example Request

curl "https://your-domain.com/api/questions?subject=Physics&type=mcq&difficulty=hard" \
  -H "Authorization: Bearer <token>"

​
Example Response

[
  {
    "id": "qst_01J6MNPWRK",
    "subject": "Physics",
    "question_type": "mcq",
    "question_text": "A body moving in a circular path with constant speed has:",
    "difficulty": "hard",
    "marks": 2.0,
    "negative": 0.5,
    "topic": "Circular Motion",
    "options": [
      { "key": "A", "text": "Constant velocity" },
      { "key": "B", "text": "Constant acceleration" },
      { "key": "C", "text": "Constant kinetic energy" },
      { "key": "D", "text": "No net force acting on it" }
    ],
    "correct_answers": ["C"]
  }
]

​
POST /api/questions

Add a new question to the question bank. Requires Examiner or Admin role.

​
Request Body

​
subject
string
required
The subject this question belongs to (e.g., "Physics", "History").
​
question_type
string
required
The answer type for this question. Accepted values: mcq, multiselect, short_answer, long_answer, image_upload.
​
question_text
string
required
The full text of the question as shown to students.
​
difficulty
string
required
Difficulty classification. Accepted values: easy, medium, hard.
​
marks
float
required
Points awarded for a fully correct answer.
​
options
array
Required for mcq and multiselect types. Array of option objects, each with key (string) and text (string) fields. Example: [{ "key": "A", "text": "Option text" }].
​
correct_answers
array
Required for mcq and multiselect types. Array of option keys that represent correct answers. For mcq, provide exactly one key. For multiselect, provide one or more.
​
negative
float
Marks deducted for an incorrect answer (when negative marking is enabled on the exam). Defaults to 0.
​
topic
string
Optional subtopic or chapter tag (e.g., "Thermodynamics"). Useful for filtering and analytics.
​
min_word_count
integer
Minimum word count for student responses. Applies to short_answer and long_answer types only.
​
max_word_count
integer
Maximum word count for student responses. Applies to short_answer and long_answer types only.

​
Example Request

curl -X POST https://your-domain.com/api/questions \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Physics",
    "question_type": "mcq",
    "question_text": "A body moving in a circular path with constant speed has:",
    "difficulty": "hard",
    "marks": 2.0,
    "negative": 0.5,
    "topic": "Circular Motion",
    "options": [
      { "key": "A", "text": "Constant velocity" },
      { "key": "B", "text": "Constant acceleration" },
      { "key": "C", "text": "Constant kinetic energy" },
      { "key": "D", "text": "No net force acting on it" }
    ],
    "correct_answers": ["C"]
  }'

​
Example Response

{
  "id": "qst_01J6MNPWRK",
  "subject": "Physics",
  "question_type": "mcq",
  "question_text": "A body moving in a circular path with constant speed has:",
  "difficulty": "hard",
  "marks": 2.0,
  "negative": 0.5,
  "topic": "Circular Motion",
  "options": [
    { "key": "A", "text": "Constant velocity" },
    { "key": "B", "text": "Constant acceleration" },
    { "key": "C", "text": "Constant kinetic energy" },
    { "key": "D", "text": "No net force acting on it" }
  ],
  "correct_answers": ["C"],
  "created_at": "2024-11-01T16:40:22Z"
}

​
PATCH /api/questions/:id

Update an existing question in the question bank. Send only the fields you want to change; all other fields retain their current values. Requires Examiner or Admin role.

​
Path Parameters

​
id
string
required
The unique identifier of the question to update.

​
Request Body

Any subset of the fields accepted by POST /api/questions.

​
Example Request

curl -X PATCH https://your-domain.com/api/questions/qst_01J6MNPWRK \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "difficulty": "medium",
    "marks": 1.5,
    "negative": 0.25
  }'

​
Example Response

{
  "id": "qst_01J6MNPWRK",
  "subject": "Physics",
  "question_type": "mcq",
  "question_text": "A body moving in a circular path with constant speed has:",
  "difficulty": "medium",
  "marks": 1.5,
  "negative": 0.25,
  "topic": "Circular Motion"
}

​
DELETE /api/questions/:id

Permanently delete a question from the question bank. Requires Examiner or Admin role.

​
Path Parameters

​
id
string
required
The unique identifier of the question to delete.

​
Example Request

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

​
Response

Returns 204 No Content on success with no response body.
Deleting a question removes it from the question bank and prevents it from being added to future exams. It does not retroactively affect historical exam records or student submissions that already include this question — those records are preserved as-is.

​
POST /api/questions/import

Bulk-import questions into the question bank from a file. Supported file formats are CSV, PDF (structured question documents), and Google Form exports. The endpoint processes the file asynchronously and returns a summary of imported questions and any rows that could not be parsed. Requires Examiner or Admin role.

​
Request

This endpoint accepts multipart/form-data — not application/json.
​
file
file
required
The file to import. Accepted MIME types: text/csv, application/pdf, or a Google Form JSON export file.
​
format
string
required
The format of the uploaded file. Accepted values: csv, pdf, google_form.
​
subject
string
required
Subject to assign to all imported questions. All questions in a single import batch are tagged with this subject.

​
Example Request

curl -X POST https://your-domain.com/api/questions/import \
  -H "Authorization: Bearer <token>" \
  -F "file=@questions_batch.csv" \
  -F "format=csv" \
  -F "subject=Chemistry"

​
Example Response

{
  "imported": 42,
  "errors": [
    {
      "row": 7,
      "reason": "Missing 'correct_answers' field for question type 'mcq'"
    },
    {
      "row": 15,
      "reason": "Invalid difficulty value 'medium-hard'; expected 'easy', 'medium', or 'hard'"
    }
  ]
}
Download the CSV template from the ExamPlatform dashboard to ensure your import file matches the expected column structure. Common import errors include missing correct_answers for objective questions and unrecognized question_type values.

Build docs developers (and LLMs) love

Get started for freeTalk to us