Sharh

Ramadan Last 10 Nights Campaign

Used by thousands of students worldwide - help us reach 150 members

... / 150 members...
APIQuizzes

Quizzes

/quiz

AI-generated multiple-choice quizzes for books. A quiz belongs to one book and holds a list of questions, each with exactly 4 options (one correct) and a rationale. Reading quizzes is public; generating, editing and deleting them is limited to editors and admins.

POSTGenerate a new quiz for a bookGETList quizzes for a bookGETGet the most recent quiz for a bookGETGet a quiz by idPUTReplace a question in a quizPOSTAdd a question to a quizDELETEDelete a question from a quizDELETEDelete a quiz
POST/quiz/generate/:bookId

Generate a new quiz for a book

Auth requirededitor / admin only

Sends the full content of the book (Arabic, English, commentary and root words of every line, plus title and author) to Google Gemini and asks for a multiple-choice quiz covering every major topic, with 4 options per question, exactly one correct, and a rationale. The model output is parsed as JSON, must contain a non-empty questions array, and is saved as a new Quiz linked to the book; existing quizzes for the book are kept. The call is synchronous and can take a while for large books. The response includes summary fields, the username of the caller as createdBy (not stored on the quiz) and the full saved quiz. Only the role is checked; there is no book ownership check.

Path parameters

bookId
string
Book ObjectId

Errors

  • 401No bearer token provided (plain-text body)
  • 403Invalid or expired token, or the user has neither the editor nor the admin role (plain-text body)
  • 404Book not found (or, as plain text, the user behind the token no longer exists)
  • 500Quiz generation failed (AI provider error, unparseable or empty model output, malformed bookId); error carries the failure message
Request
curl -X POST "https://app.ummahspot.com/quiz/generate/:bookId" \
  -H "Authorization: Bearer $SHARH_TOKEN"
Response · 201
{
  "id": "66f2d3b0a1b2c3d4e5f60718",
  "bookId": "665f1b2c3d4e5f6a7b8c9d0e",
  "questionsCount": 25,
  "createdAt": "2025-01-15T10:30:00.000Z",
  "createdBy": "ustadh_ahmad",
  "quiz": {
    "_id": "66f2d3b0a1b2c3d4e5f60718",
    "book": "665f1b2c3d4e5f6a7b8c9d0e",
    "questions": [
      {
        "_id": "66f2d3b0a1b2c3d4e5f60719",
        "questionText": "How does the author define speech (kalam)?",
        "options": [
          { "_id": "66f2d3b0a1b2c3d4e5f6071a", "text": "Any sound produced by the tongue", "isCorrect": false },
          { "_id": "66f2d3b0a1b2c3d4e5f6071b", "text": "A composed utterance that conveys meaning by convention", "isCorrect": true },
          { "_id": "66f2d3b0a1b2c3d4e5f6071c", "text": "A single word with a meaning", "isCorrect": false },
          { "_id": "66f2d3b0a1b2c3d4e5f6071d", "text": "Written text only", "isCorrect": false }
        ],
        "rationale": "The text defines speech as a composed, meaningful utterance established by convention; the other options omit one of these conditions."
      }
    ],
    "createdAt": "2025-01-15T10:30:00.000Z",
    "__v": 0
  }
}
GET/quiz/book/:bookId

List quizzes for a book

Public

Returns summary information (id, question count, creation date) for every quiz generated for the book, newest first. quizzes is an empty array when the book has none. No authentication or book visibility check is performed.

Path parameters

bookId
string
Book ObjectId

Errors

  • 404Book not found
  • 500Failed to fetch quizzes (including a malformed bookId)
Request
curl -X GET "https://app.ummahspot.com/quiz/book/:bookId"
Response · 200
{
  "bookId": "665f1b2c3d4e5f6a7b8c9d0e",
  "bookTitle": "Al-Ajrumiyyah",
  "quizzes": [
    {
      "id": "66f2d3b0a1b2c3d4e5f60718",
      "questionsCount": 25,
      "createdAt": "2025-01-15T10:30:00.000Z"
    }
  ],
  "total": 1
}
GET/quiz/book/:bookId/latest

Get the most recent quiz for a book

Public

Returns the full, most recently generated quiz for the book, including every question with its options, the isCorrect flags and rationales. The book field is populated with the book title, author and difficulty. No authentication is required, so correct answers are visible to any caller.

Path parameters

bookId
string
Book ObjectId

Errors

  • 404No quiz found for this book
  • 500Failed to fetch latest quiz (including a malformed bookId)
Request
curl -X GET "https://app.ummahspot.com/quiz/book/:bookId/latest"
Response · 200
{
  "_id": "66f2d3b0a1b2c3d4e5f60718",
  "book": {
    "_id": "665f1b2c3d4e5f6a7b8c9d0e",
    "title": "Al-Ajrumiyyah",
    "author": "Ibn Ajurrum",
    "difficulty": "Beginner"
  },
  "questions": [
    {
      "_id": "66f2d3b0a1b2c3d4e5f60719",
      "questionText": "How does the author define speech (kalam)?",
      "options": [
        { "_id": "66f2d3b0a1b2c3d4e5f6071a", "text": "Any sound produced by the tongue", "isCorrect": false },
        { "_id": "66f2d3b0a1b2c3d4e5f6071b", "text": "A composed utterance that conveys meaning by convention", "isCorrect": true },
        { "_id": "66f2d3b0a1b2c3d4e5f6071c", "text": "A single word with a meaning", "isCorrect": false },
        { "_id": "66f2d3b0a1b2c3d4e5f6071d", "text": "Written text only", "isCorrect": false }
      ],
      "rationale": "The text defines speech as a composed, meaningful utterance established by convention; the other options omit one of these conditions."
    }
  ],
  "createdAt": "2025-01-15T10:30:00.000Z",
  "__v": 0
}
GET/quiz/:quizId

Get a quiz by id

Public

Returns the full quiz, including every question with its options, the isCorrect flags and rationales. The book field is populated with the book title, author, category and difficulty. No authentication is required, so correct answers are visible to any caller.

Path parameters

quizId
string
Quiz ObjectId

Errors

  • 404Quiz not found
  • 500Failed to fetch quiz (including a malformed quizId)
Request
curl -X GET "https://app.ummahspot.com/quiz/:quizId"
Response · 200
{
  "_id": "66f2d3b0a1b2c3d4e5f60718",
  "book": {
    "_id": "665f1b2c3d4e5f6a7b8c9d0e",
    "title": "Al-Ajrumiyyah",
    "author": "Ibn Ajurrum",
    "category": "Grammar",
    "difficulty": "Beginner"
  },
  "questions": [
    {
      "_id": "66f2d3b0a1b2c3d4e5f60719",
      "questionText": "How does the author define speech (kalam)?",
      "options": [
        { "_id": "66f2d3b0a1b2c3d4e5f6071a", "text": "Any sound produced by the tongue", "isCorrect": false },
        { "_id": "66f2d3b0a1b2c3d4e5f6071b", "text": "A composed utterance that conveys meaning by convention", "isCorrect": true },
        { "_id": "66f2d3b0a1b2c3d4e5f6071c", "text": "A single word with a meaning", "isCorrect": false },
        { "_id": "66f2d3b0a1b2c3d4e5f6071d", "text": "Written text only", "isCorrect": false }
      ],
      "rationale": "The text defines speech as a composed, meaningful utterance established by convention; the other options omit one of these conditions."
    }
  ],
  "createdAt": "2025-01-15T10:30:00.000Z",
  "__v": 0
}
PUT/quiz/:quizId/questions/:questionIndex

Replace a question in a quiz

Auth requirededitor / admin only

Replaces the question at the given zero-based position with the supplied question text, options and rationale. The whole question is overwritten; partial updates are not supported. Only the role is checked, so any editor or admin can edit any quiz.

Path parameters

quizId
string
Quiz ObjectId
questionIndex
number
Zero-based index of the question in the quiz questions array

Body parameters

questionTextrequired
string
The question text
optionsrequired
object[]
Exactly 4 answer options, each shaped { text: string, isCorrect: boolean }. Every option needs a non-empty string text, and exactly one option must have isCorrect set to true.
rationalerequired
string
Explanation of why the correct answer is right

Errors

  • 400Validation failed: questionText, options and rationale are required; options must be an array of exactly 4 items; exactly one option must be marked as correct; all options must have text; or Invalid question index (out of range)
  • 401No bearer token provided (plain-text body)
  • 403Invalid or expired token, or the user has neither the editor nor the admin role (plain-text body)
  • 404Quiz not found (or, as plain text, the user behind the token no longer exists)
  • 500Failed to update question (including a malformed quizId)
Request
curl -X PUT "https://app.ummahspot.com/quiz/:quizId/questions/:questionIndex" \
  -H "Authorization: Bearer $SHARH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"questionText":"string","options":[],"rationale":"string"}'
Response · 200
{
  "message": "Question updated successfully",
  "updatedQuestion": {
    "_id": "66f2e4c1a1b2c3d4e5f60801",
    "questionText": "How does the author define speech (kalam)?",
    "options": [
      { "_id": "66f2e4c1a1b2c3d4e5f60802", "text": "Any sound produced by the tongue", "isCorrect": false },
      { "_id": "66f2e4c1a1b2c3d4e5f60803", "text": "A composed utterance that conveys meaning by convention", "isCorrect": true },
      { "_id": "66f2e4c1a1b2c3d4e5f60804", "text": "A single word with a meaning", "isCorrect": false },
      { "_id": "66f2e4c1a1b2c3d4e5f60805", "text": "Written text only", "isCorrect": false }
    ],
    "rationale": "The text defines speech as a composed, meaningful utterance established by convention."
  },
  "questionIndex": 0
}
POST/quiz/:quizId/questions

Add a question to a quiz

Auth requirededitor / admin only

Appends a new question to the end of the quiz. The response echoes the question as submitted (normalised to text and isCorrect per option), its zero-based index and the new total. Only the role is checked, so any editor or admin can edit any quiz.

Path parameters

quizId
string
Quiz ObjectId

Body parameters

questionTextrequired
string
The question text
optionsrequired
object[]
Exactly 4 answer options, each shaped { text: string, isCorrect: boolean }. Every option needs a non-empty string text, and exactly one option must have isCorrect set to true.
rationalerequired
string
Explanation of why the correct answer is right

Errors

  • 400Validation failed: questionText, options and rationale are required; options must be an array of exactly 4 items; exactly one option must be marked as correct; all options must have text
  • 401No bearer token provided (plain-text body)
  • 403Invalid or expired token, or the user has neither the editor nor the admin role (plain-text body)
  • 404Quiz not found (or, as plain text, the user behind the token no longer exists)
  • 500Failed to add question (including a malformed quizId)
Request
curl -X POST "https://app.ummahspot.com/quiz/:quizId/questions" \
  -H "Authorization: Bearer $SHARH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"questionText":"string","options":[],"rationale":"string"}'
Response · 201
{
  "message": "Question added successfully",
  "addedQuestion": {
    "questionText": "Which of the following is a sign of a noun?",
    "options": [
      { "text": "Accepting the definite article", "isCorrect": true },
      { "text": "Accepting the particle of negation lam", "isCorrect": false },
      { "text": "Accepting the feminine ta of the verb", "isCorrect": false },
      { "text": "None of the above", "isCorrect": false }
    ],
    "rationale": "Nouns are recognised by the definite article, tanwin and the genitive case; the other signs belong to verbs."
  },
  "questionIndex": 25,
  "totalQuestions": 26
}
DELETE/quiz/:quizId/questions/:questionIndex

Delete a question from a quiz

Auth requirededitor / admin only

Removes the question at the given zero-based position and returns it along with the number of questions left. The last remaining question of a quiz cannot be deleted; delete the quiz instead. Indexes of later questions shift down by one. Only the role is checked, so any editor or admin can edit any quiz.

Path parameters

quizId
string
Quiz ObjectId
questionIndex
number
Zero-based index of the question in the quiz questions array

Errors

  • 400Invalid question index (out of range), or Cannot delete the last question in a quiz
  • 401No bearer token provided (plain-text body)
  • 403Invalid or expired token, or the user has neither the editor nor the admin role (plain-text body)
  • 404Quiz not found (or, as plain text, the user behind the token no longer exists)
  • 500Failed to delete question (including a malformed quizId)
Request
curl -X DELETE "https://app.ummahspot.com/quiz/:quizId/questions/:questionIndex" \
  -H "Authorization: Bearer $SHARH_TOKEN"
Response · 200
{
  "message": "Question deleted successfully",
  "deletedQuestion": {
    "_id": "66f2d3b0a1b2c3d4e5f60719",
    "questionText": "How does the author define speech (kalam)?",
    "options": [
      { "_id": "66f2d3b0a1b2c3d4e5f6071a", "text": "Any sound produced by the tongue", "isCorrect": false },
      { "_id": "66f2d3b0a1b2c3d4e5f6071b", "text": "A composed utterance that conveys meaning by convention", "isCorrect": true },
      { "_id": "66f2d3b0a1b2c3d4e5f6071c", "text": "A single word with a meaning", "isCorrect": false },
      { "_id": "66f2d3b0a1b2c3d4e5f6071d", "text": "Written text only", "isCorrect": false }
    ],
    "rationale": "The text defines speech as a composed, meaningful utterance established by convention."
  },
  "remainingQuestions": 24
}
DELETE/quiz/:quizId

Delete a quiz

Auth requirededitor / admin only

Permanently deletes the quiz and all of its questions, and returns the id and creation date of the deleted quiz. Only the role is checked, so any editor or admin can delete any quiz.

Path parameters

quizId
string
Quiz ObjectId

Errors

  • 401No bearer token provided (plain-text body)
  • 403Invalid or expired token, or the user has neither the editor nor the admin role (plain-text body)
  • 404Quiz not found (or, as plain text, the user behind the token no longer exists)
  • 500Failed to delete quiz (including a malformed quizId)
Request
curl -X DELETE "https://app.ummahspot.com/quiz/:quizId" \
  -H "Authorization: Bearer $SHARH_TOKEN"
Response · 200
{
  "message": "Quiz deleted successfully",
  "deletedQuiz": {
    "id": "66f2d3b0a1b2c3d4e5f60718",
    "createdAt": "2025-01-15T10:30:00.000Z"
  }
}