Quiz API

Generate Quiz

Supports both text input and file upload (TXT, DOC, DOCX). Authentication is optional - authenticated users can save quizzes to their history.

POST /api/quiz/generate

curl -X POST https://api.inspir.uk/api/quiz/generate \
  -H "Content-Type: multipart/form-data" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "sourceName=Biology Chapter 3" \
  -F "content=Photosynthesis is the process by which plants convert light energy..."

Request Parameters

sourceName

string

Name/topic of the quiz source (e.g., “Biology Chapter 3”). Defaults to “Untitled Quiz” if not provided.

content

string

Text content to generate quiz from. If not provided, quiz will be generated based on the topic name.

file

Optional file upload (TXT, DOC, DOCX). Maximum 10MB. File content takes precedence over text content.

Response

quizId

string

Unique identifier for the saved quiz (only present for authenticated users)

sourceName

string

Name of the quiz source

questions

array

Array of generated quiz questions

Show Question Object

question

string

The question text

options

array

Array of answer options (typically 4 options)

correctAnswer

string

The correct answer from the options

explanation

string

Explanation of why the answer is correct

Error Responses

Show 400 Bad Request

{
  "error": "Please provide either a topic or content for quiz generation."
}

{
  "error": "Only TXT, DOC, and DOCX files are allowed"
}

Show 503 Service Unavailable

{
  "error": "AI is currently busy. Please try again in 30–60 seconds.",
  "message": "Service overloaded"
}

Show 504 Gateway Timeout

{
  "error": "Quiz generation timed out",
  "message": "Connection timeout"
}

Submit Quiz

Submit quiz answers for AI-powered grading and detailed feedback.

POST /api/quiz/submit

curl -X POST https://api.inspir.uk/api/quiz/submit \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "quizId": "123e4567-e89b-12d3-a456-426614174000",
    "questions": [
      {
        "question": "What is photosynthesis?",
        "options": ["..."],
        "correctAnswer": "The process by which plants..."
      }
    ],
    "answers": ["The process by which plants..."]
  }'

Request Parameters

quizId

string

ID of the quiz being submitted (required for saving results to history)

questions

array

required

Array of quiz questions (must match the generated quiz structure)

answers

array

required

Array of user’s answers corresponding to each question. Length must match questions array.

Response

score

number

Number of correct answers

totalQuestions

number

Total number of questions in the quiz

percentage

number

Score as a percentage (0-100)

results

array

Detailed results for each question

Show Result Object

question

string

The question text

userAnswer

string

The answer provided by the user

correctAnswer

string

The correct answer

isCorrect

boolean

Whether the user’s answer was correct

explanation

string

Explanation of the correct answer

Error Responses

Show 400 Bad Request

{
  "error": "Invalid submission data"
}

Returned when questions and answers arrays don’t match in length.

Get Quiz History

Retrieve all quiz attempts and results for the authenticated user.

This endpoint requires authentication.

GET /api/quiz/history

curl -X GET https://api.inspir.uk/api/quiz/history \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

Returns an array of quiz result objects:

string

Unique identifier for the quiz result

quiz_id

string

ID of the associated quiz

score

number

Number of correct answers

total_questions

number

Total number of questions

percentage

number

Score as a percentage

submitted_at

string

ISO 8601 timestamp of submission

quizzes

object

Associated quiz information

Show Quiz Info

string

Quiz ID

source_name

string

Name of the quiz source

created_at

string

ISO 8601 timestamp of quiz creation

Get Quiz by ID

Retrieve a specific quiz by its ID.

GET /api/quiz/:id

curl -X GET https://api.inspir.uk/api/quiz/123e4567-e89b-12d3-a456-426614174000 \
  -H "Authorization: Bearer YOUR_TOKEN"

Path Parameters

string

required

The unique identifier of the quiz

Response

string

Quiz ID

user_id

string

ID of the user who created the quiz

source_name

string

Name of the quiz source

questions

array

Array of quiz questions (same structure as generate endpoint)

created_at

string

ISO 8601 timestamp of quiz creation

created_by_username

string

Username of the quiz creator

Error Responses

Show 403 Forbidden

{
  "error": "Access denied"
}

Returned when attempting to access another user’s quiz.

Show 404 Not Found

{
  "error": "Quiz not found"
}

Generate a shareable link for a quiz. Others can take the quiz using this link.

This endpoint requires authentication. You can only share your own quizzes.

POST /api/quiz/:quizId/share

curl -X POST https://api.inspir.uk/api/quiz/123e4567-e89b-12d3-a456-426614174000/share \
  -H "Authorization: Bearer YOUR_TOKEN"

Path Parameters

quizId

string

required

The unique identifier of the quiz to share

Response

Unique token for the shared quiz

Complete shareable URL

Get Shared Quiz

Retrieve a quiz using its share token (public endpoint).

GET /api/quiz/shared/:shareToken

curl -X GET https://api.inspir.uk/api/quiz/shared/abc123def456

Path Parameters

The share token for the quiz

Response

quizId

string

Quiz ID

sourceName

string

Name of the quiz source

questions

array

Array of quiz questions

createdBy

string

Username of the quiz creator

createdAt

string

ISO 8601 timestamp

Submit Shared Quiz

Submit answers for a shared quiz attempt.

POST /api/quiz/shared/:shareToken/submit

curl -X POST https://api.inspir.uk/api/quiz/shared/abc123def456/submit \
  -H "Content-Type: application/json" \
  -d '{
    "questions": [...],
    "answers": [...],
    "attemptName": "John Doe",
    "isGuest": true
  }'

Path Parameters

The share token for the quiz

Request Parameters

questions

array

required

Array of quiz questions

answers

array

required

Array of user’s answers

attemptName

string

required

Name of the person taking the quiz (max 100 characters)

isGuest

boolean

Whether this is a guest attempt (default: false)

Response

Same structure as the regular submit quiz endpoint (score, results, etc.)

Get Quiz Attempts

View all attempts and statistics for a shared quiz (quiz creator only).

This endpoint requires authentication and quiz ownership.

GET /api/quiz/:quizId/attempts

curl -X GET https://api.inspir.uk/api/quiz/123e4567-e89b-12d3-a456-426614174000/attempts \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

quizInfo

object

Basic quiz information

Show Quiz Info

string

Quiz ID

sourceName

string

Quiz source name

isShared

boolean

Whether the quiz is currently shared

stats

object

Overall statistics for all attempts

Show Statistics

totalAttempts

number

Total number of attempts

averageScore

number

Average score across all attempts

averagePercentage

number

Average percentage across all attempts

highestScore

number

Highest score achieved

lowestScore

number

Lowest score achieved

attempts

array

Array of individual quiz attempts

Show Attempt Object

string

Attempt ID

attemptName

string

Name of the person who took the quiz

isGuest

boolean

Whether this was a guest attempt

score

number

Score achieved

percentage

number

Percentage score

completedAt

string

ISO 8601 timestamp

answers

array

Detailed answer results

Overview

Endpoints

Generate Quiz

Request Parameters

Response

Error Responses

Submit Quiz

Request Parameters

Response

Error Responses

Get Quiz History

Response

Get Quiz by ID

Path Parameters

Response

Error Responses

Path Parameters

Response

Get Shared Quiz

Path Parameters

Response

Submit Shared Quiz

Path Parameters

Request Parameters

Response

Get Quiz Attempts

Response

Build docs developers (and LLMs) love

Overview

Endpoints

​Generate Quiz

​Request Parameters

​Response

​Error Responses

​Submit Quiz

​Request Parameters

​Response

​Error Responses

​Get Quiz History

​Response

​Get Quiz by ID

​Path Parameters

​Response

​Error Responses

​Share Quiz

​Path Parameters

​Response

​Get Shared Quiz

​Path Parameters

​Response

​Submit Shared Quiz

​Path Parameters

​Request Parameters

​Response

​Get Quiz Attempts

​Response

Build docs developers (and LLMs) love

Generate Quiz

Request Parameters

Response

Error Responses

Submit Quiz

Request Parameters

Response

Error Responses

Get Quiz History

Response

Get Quiz by ID

Path Parameters

Response

Error Responses

Share Quiz

Path Parameters

Response

Get Shared Quiz

Path Parameters

Response

Submit Shared Quiz

Path Parameters

Request Parameters

Response

Get Quiz Attempts

Response