Practice Tests API

Overview

The Practice Tests API allows users to create comprehensive practice tests from study materials. Unlike regular quizzes, practice tests support question banks, custom test creation, and detailed performance tracking.

Endpoints

Create Question Bank

curl -X POST https://api.inspir.uk/api/practice-tests/banks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "name": "Biology Chapter 5",
    "description": "Photosynthesis and cellular respiration",
    "topic": "Biology"
  }'

Create a question bank to organize practice questions. Authentication: Required

Request Body

name

string

required

Name of the question bank

description

string

Description of the question bank content

topic

string

Subject area

Generate Practice Questions

curl -X POST https://api.inspir.uk/api/practice-tests/generate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "content": "Study material text...",
    "questionCount": 20,
    "difficultyMix": "balanced"
  }'

Generate practice questions from content or uploaded file. Authentication: Optional (guests get questions without saving)

Request Body

content

string

Text content to generate questions from (required if no file)

file

PDF, DOCX, or TXT file (max 10MB, required if no content)

questionCount

number

default:15

Number of questions to generate (5-50)

difficultyMix

string

default:"balanced"

Difficulty distribution: easy, balanced, hard, or mixed

questionTypes

array

Question types to include: multiple-choice, true-false, short-answer, fill-blank

bankId

string

Optional question bank ID to save questions to

Response

success

boolean

Whether the request was successful

questions

array

Generated questions

Show question object

string

Question ID

questionText

string

The question

questionType

string

Type: multiple-choice, true-false, short-answer, or fill-blank

options

array

Answer options (for multiple-choice and true-false)

correctAnswer

string

Correct answer

explanation

string

Explanation of the correct answer

difficulty

string

Difficulty: easy, medium, or hard

topic

string

Specific topic this question covers

saved

boolean

Whether questions were saved (true for authenticated users)

Create Practice Test

curl -X POST https://api.inspir.uk/api/practice-tests/tests \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "title": "Biology Midterm Practice",
    "questionIds": ["q1", "q2", "q3"],
    "timeLimit": 60,
    "passingScore": 70
  }'

Create a custom practice test from question bank. Authentication: Required

Request Body

title

string

required

Test title

questionIds

array

required

Array of question IDs to include in the test

timeLimit

number

Time limit in minutes (optional)

passingScore

number

Passing score percentage (0-100)

shuffleQuestions

boolean

default:true

Whether to randomize question order

showFeedback

boolean

default:true

Show immediate feedback after each question

Submit Test Attempt

curl -X POST https://api.inspir.uk/api/practice-tests/tests/test123/submit \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "answers": [
      {"questionId": "q1", "answer": "A"},
      {"questionId": "q2", "answer": "True"}
    ],
    "timeSpent": 45
  }'

Submit answers for a practice test. Authentication: Required

Request Body

answers

array

required

Array of answer objects

Show answer object

questionId

string

required

Question ID

answer

string

required

User’s answer

timeSpent

number

Total time spent in minutes

Response

success

boolean

Whether the submission was successful

results

object

Test results

Show properties

score

number

Score percentage (0-100)

correctCount

number

Number of correct answers

totalQuestions

number

Total number of questions

passed

boolean

Whether the user passed (based on passingScore)

timeSpent

number

Time spent in minutes

questionResults

array

Detailed results per question

Show question result

questionId

string

Question ID

correct

boolean

Whether answer was correct

userAnswer

string

User’s answer

correctAnswer

string

Correct answer

explanation

string

Explanation of correct answer

feedback

string

AI-generated personalized feedback

weakTopics

array

Topics where user needs improvement

Get Practice Tests

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

Get user’s practice tests. Authentication: Required

Get Practice Test by ID

curl -X GET https://api.inspir.uk/api/practice-tests/tests/test123

Get a specific practice test. Authentication: Optional (public tests only)

Error Responses

400 - Invalid request (missing fields, invalid file type)
401 - Authentication required
404 - Test or question not found
413 - File too large (max 10MB)
500 - AI generation failed

Supported File Types

PDF (.pdf)
Word Documents (.docx)
Text Files (.txt)

Maximum file size: 10 MB

Practice tests support advanced features like time limits, passing scores, and detailed analytics to help students prepare for exams effectively.

Use the difficultyMix parameter to create tests that match your exam difficulty. Start with “balanced” and adjust based on your performance.

Overview

Endpoints

​Overview

​Endpoints

​Create Question Bank

​Request Body

​Generate Practice Questions

​Request Body

​Response

​Create Practice Test

​Request Body

​Submit Test Attempt

​Request Body

​Response

​Get Practice Tests

​Get Practice Test by ID

​Error Responses

​Supported File Types

Build docs developers (and LLMs) love

Overview

Endpoints

Create Question Bank

Request Body

Generate Practice Questions

Request Body

Response

Create Practice Test

Request Body

Submit Test Attempt

Request Body

Response

Get Practice Tests

Get Practice Test by ID

Error Responses

Supported File Types