Questions API: Manage and AI-Generate Quiz Questions

Questions are the atomic unit of learning in Sealearn. Each question belongs to a specific lesson and has a type that governs the interaction model — from tapping a single correct option to writing Python code executed against test cases. Administrators create and review questions via this API; the AI generation endpoint lets them seed an entire lesson’s question pool from a single request. All authenticated users can report a question and submit open-ended answers for AI evaluation.

Question model

The fields below are shared by every question type. Type-specific fields are described in the table that follows.

lesson

ObjectId

required

Reference to the parent Lesson document.

type

string

required

One of: multiple_choice, true_false, fill_blank, order_items, match_pairs, sentence_builder, free_text, typing, code_python.

prompt

string

required

The question text shown to the learner. For sentence_builder questions, the server normalises spacing around ___ markers on save.

explanation

string

Post-answer explanation shown regardless of whether the learner was correct.

hint

string | null

Optional hint shown when the learner requests help. Using a hint halves xpValue earned for a correct answer.

imageUrl

string | null

Optional image URL displayed with the question prompt.

difficulty

string

easy, medium, or hard. Used by the adaptive engine to compose difficulty-balanced question sets. Defaults to easy.

xpValue

number

XP earned for a correct answer. Defaults to 2. Halved when hintUsed is true.

Type-specific fields

Type	Required field(s)	Description
`multiple_choice`	`options`	Array of option objects (`text`, `isCorrect`, optional `explanation`). At least 2 options required, at least 1 must be correct, no duplicate option text.
`true_false`	`correctBoolean`	The correct boolean value (`true` or `false`).
`fill_blank`	`correctAnswers`	Array of accepted answer strings. On save, the server automatically adds normalised variants (lowercase, diacritics stripped) to widen matching. `caseSensitive` defaults to `false`.
`order_items`	`items`	Array of strings representing the correct sequence. At least 2 items required.
`match_pairs`	`pairs`	Array of `{ left, right }` pair objects. At least 2 pairs required. Right-column values must be unique.
`sentence_builder`	`wordBank`, `correctAnswers`	`wordBank`: array of words (≥ 2) shown shuffled. `correctAnswers`: the correct word sequence.
`free_text`	(none beyond `prompt`)	`evaluationCriteria` guides the AI evaluator. `maxScore` sets the top numeric score (default `10`). `isCodeExercise` (`boolean`) hints to the AI that the answer involves code.
`typing`	`typingText`	The exact string the user must reproduce character-for-character.
`code_python`	`testCases`	Array of test case objects. Each requires `expectedOutput` (string). Optional fields: `description`, `testType` (`stdout` or `return`), `callCode`. At least 1 test case required, every case must have a non-empty `expectedOutput`.

Endpoints

GET /api/questions

Returns all questions matching the provided filters, sorted by creation date descending. Each question has its lesson field populated with the lesson name. Authentication: Bearer token + admin role required. Query parameters

lesson

string

Filter by lesson ObjectId.

type

string

Filter by question type (e.g. multiple_choice).

difficulty

string

Filter by difficulty: easy, medium, or hard.

isReviewed

boolean

Filter by review status. Pass true or false as a string query parameter.

curl "https://api.sealearn.app/api/questions?lesson=665f3c4d5e6f7a8b9c0f1a2b&isReviewed=false" \
  -H "Authorization: Bearer <admin-token>"

boolean

true on success.

data

object[]

Array of question documents.

total

number

Count of matched questions.

POST /api/questions

Creates a single question manually. All validation rules defined in the model are enforced (see the type-specific table above). For fill_blank, the server automatically expands correctAnswers with normalised accent variants on save. Authentication: Bearer token + admin role required. Request body — any valid question document. See the model fields and type-specific table above for required fields.

curl -X POST https://api.sealearn.app/api/questions \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "lesson": "665f3c4d5e6f7a8b9c0f1a2b",
    "type": "multiple_choice",
    "prompt": "Which planet is closest to the Sun?",
    "options": [
      { "text": "Mercury", "isCorrect": true },
      { "text": "Venus",   "isCorrect": false },
      { "text": "Earth",   "isCorrect": false },
      { "text": "Mars",    "isCorrect": false }
    ],
    "explanation": "Mercury is the innermost planet at ~57.9 million km from the Sun.",
    "difficulty": "easy",
    "xpValue": 2
  }'

Returns 201 Created with the new question document under data.

POST /api/questions/generate

Instructs the AI to generate a batch of questions for a lesson. The generated questions are saved with isReviewed: false and isActive: false, so they do not appear in learner sessions until an admin reviews them. The endpoint resolves the lesson’s full context (subject name, unit name, subject AI prompt context) before calling the generation service. Authentication: Bearer token + admin role required. Request body

lessonId

string

required

ObjectId of the lesson to generate questions for.

count

number

Number of questions to generate. Defaults to 5.

difficulty

string

Desired difficulty for the generated questions: easy, medium, or hard. Defaults to easy.

allowedTypes

string[]

Array of question types the AI may produce. Defaults to all nine types: multiple_choice, true_false, fill_blank, order_items, match_pairs, sentence_builder, free_text, typing, code_python.

curl -X POST https://api.sealearn.app/api/questions/generate \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "lessonId": "665f3c4d5e6f7a8b9c0f1a2b",
    "count": 8,
    "difficulty": "medium",
    "allowedTypes": ["multiple_choice", "true_false", "fill_blank"]
  }'

boolean

true on success.

message

string

Human-readable summary, e.g. "8 preguntas generadas correctamente para la lección "Adding and Subtracting". Deben ser revisadas antes de activarse."

data

object[]

Array of the newly created (unreviewed) question documents.

Generated questions must be approved via PUT /api/questions/:id/review before they become available to learners. This two-step workflow lets admins catch AI mistakes before they reach production.

POST /api/questions/evaluate-open

Sends a free-text or code answer to the AI for evaluation. This endpoint is available to all authenticated users and is called automatically by POST /api/lessons/:id/answer for free_text questions, but can also be called standalone — for example, in a preview or practice mode. Authentication: Bearer token required. Request body

prompt

string

required

The original question text.

userAnswer

string

required

The learner’s answer to evaluate.

evaluationCriteria

string

Rubric text guiding the AI. Defaults to a general relevance and comprehension rubric if omitted.

maxScore

number

Maximum possible score the AI should award. Defaults to 10.

curl -X POST https://api.sealearn.app/api/questions/evaluate-open \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Explain what a variable is in programming.",
    "userAnswer": "A variable is a named storage location in memory that holds a value which can change during program execution.",
    "evaluationCriteria": "Award full marks for answers that mention storage, naming, and mutability.",
    "maxScore": 10
  }'

boolean

true on success.

data

object

Show AI evaluation result

approved

boolean

Whether the AI considers the answer acceptable.

score

number

Numeric score (0 to maxScore).

feedback

string

Overall feedback from the AI.

strengths

string[]

Aspects the AI identified as strong.

improvements

string[]

Suggested improvements.

PUT /api/questions/:id

Updates an existing question. Runs all model validators on the new values. Returns the updated document. Authentication: Bearer token + admin role required. Path parameters

string

required

ObjectId of the question to update.

Request body — Any subset of question fields (see the model description above).

curl -X PUT https://api.sealearn.app/api/questions/665fabc123def456 \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{ "difficulty": "hard", "xpValue": 4 }'

Returns 200 OK with the updated question under data. Returns 404 if not found.

PUT /api/questions/:id/review

Reviews an AI-generated (or manually created) question. Setting approved: true marks it as reviewed and active; approved: false deactivates it. Optionally accepts edited field values to apply before saving, enabling inline correction. Authentication: Bearer token + admin role required. Path parameters

string

required

ObjectId of the question to review.

Request body

approved

boolean

required

true to approve and activate the question; false to reject and deactivate it. In both cases isReviewed is set to true.

editedData

object

Optional partial question document. Fields here are merged into the update, allowing the reviewer to fix the question in the same request.

# Approve with a prompt correction
curl -X PUT https://api.sealearn.app/api/questions/665fabc123def456/review \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "approved": true,
    "editedData": {
      "prompt": "Which of the following is NOT a primitive data type in Python?"
    }
  }'

Returns 200 OK with the reviewed question document under data.

DELETE /api/questions/:id

Performs a soft delete by setting isActive: false. The question is excluded from future session question pools but its data is preserved. Authentication: Bearer token + admin role required. Path parameters

string

required

ObjectId of the question to deactivate.

curl -X DELETE https://api.sealearn.app/api/questions/665fabc123def456 \
  -H "Authorization: Bearer <admin-token>"

Example response

{ "ok": true, "message": "Pregunta desactivada" }

POST /api/questions/:questionId/report

Allows any authenticated user to flag a question for admin review. The report is appended to the question’s reports array and does not immediately alter the question’s active status. Admins can then review flagged questions through the admin dashboard. Authentication: Bearer token required. Path parameters

questionId

string

required

ObjectId of the question to report.

Request body

reason

string

required

The category of the problem. Must be one of:

Value	Meaning
`wrong_answer`	The marked correct answer is incorrect.
`unclear`	The question is ambiguous or confusing.
`typo`	The question or answers contain a spelling or grammar error.
`too_hard`	The question is disproportionately difficult for its lesson.
`other`	Any other issue (requires a `comment`).

comment

string

Optional free-text description of the problem. Maximum 300 characters.

curl -X POST https://api.sealearn.app/api/questions/665fabc123def456/report \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "wrong_answer",
    "comment": "The correct answer should be Venus, not Mercury."
  }'

Example response

{
  "ok": true,
  "message": "Pregunta reportada correctamente. Gracias por tu feedback."
}

Submitting an invalid reason value returns 400 Bad Request. The only accepted values are wrong_answer, unclear, typo, too_hard, and other.

Authentication

Learning

Social & Competitive

Shop & Admin

Questions API: Manage and AI-Generate Quiz Questions

Question model

Type-specific fields

Endpoints

GET /api/questions

POST /api/questions

POST /api/questions/generate

POST /api/questions/evaluate-open

PUT /api/questions/:id

PUT /api/questions/:id/review

DELETE /api/questions/:id

POST /api/questions/:questionId/report

Build docs developers (and LLMs) love

Authentication

Learning

Social & Competitive

Shop & Admin

Documentation Index

​Question model

​Type-specific fields

​Endpoints

​GET /api/questions

​POST /api/questions

​POST /api/questions/generate

​POST /api/questions/evaluate-open

​PUT /api/questions/:id

​PUT /api/questions/:id/review

​DELETE /api/questions/:id

​POST /api/questions/:questionId/report

Build docs developers (and LLMs) love

Question model

Type-specific fields

Endpoints

GET /api/questions

POST /api/questions

POST /api/questions/generate

POST /api/questions/evaluate-open

PUT /api/questions/:id

PUT /api/questions/:id/review

DELETE /api/questions/:id

POST /api/questions/:questionId/report