Assessment Tools

Build comprehensive assessment systems with quiz creation, automatic grading, and detailed feedback. Support multiple question types and adaptive difficulty.

Creating an Assessment

javascript

const assessment = await client.assessments.create({
  title: "Chapter 5 — Forces and Motion",
  type: "quiz",
  subject: "physics",
  grade: "11",
  time_limit: "30min",
  passing_score: 70,
  shuffle_questions: true,
  questions: [
    {
      type: "multiple_choice",
      question: "What is Newton's Second Law of Motion?",
      options: [
        "An object at rest stays at rest",
        "F = ma",
        "Every action has an equal and opposite reaction",
        "Energy cannot be created or destroyed"
      ],
      correct_answer: 1,
      points: 5,
      explanation: "Newton's Second Law states that Force = mass × acceleration."
    },
    {
      type: "short_answer",
      question: "Calculate the force needed to accelerate a 10kg object at 5 m/s².",
      correct_answer: "50 N",
      points: 10,
      rubric: "Award full marks for correct value and unit."
    },
    {
      type: "true_false",
      question: "Friction always opposes the direction of motion.",
      correct_answer: true,
      points: 3
    }
  ]
});

Endpoints

GET /v1/assessments

List assessments with filtering by subject, type, grade, or lesson.

Query Parameters

type string - Assessment type (quiz, exam, assignment, practice)
subject string - Filter by subject
lesson_id string - Filter by associated lesson
limit integer - Records per page (default: 20)

POST /v1/assessments

Create a new assessment with questions, grading criteria, and configuration options.

Request Body

title string required
type string required - quiz, exam, assignment, practice
time_limit string - Time allowed (e.g. 30min, 2h)
passing_score number - Minimum passing percentage
shuffle_questions boolean - Randomize question order
questions object[] required - Array of question objects

POST /v1/assessments/:id/submit

Submit answers for grading. Returns scores, feedback, and correct answers.

response

{
  "submission_id": "sub_def456",
  "assessment_id": "asmt_abc123",
  "student_id": "stu_001",
  "score": 85,
  "max_score": 100,
  "passed": true,
  "time_taken": "22:45",
  "results": [
    {
      "question_index": 0,
      "correct": true,
      "points_awarded": 5,
      "points_possible": 5
    },
    {
      "question_index": 1,
      "correct": true,
      "points_awarded": 10,
      "points_possible": 10,
      "feedback": "Correct calculation with proper units."
    },
    {
      "question_index": 2,
      "correct": false,
      "points_awarded": 0,
      "points_possible": 3,
      "explanation": "Friction always opposes the direction of motion."
    }
  ]
}

GET /v1/assessments/:id/results

Retrieve aggregated results for an assessment — class averages, score distribution, and question-level analytics.

Question Types

multiple_choice Single correct answer from a list of options

multi_select Multiple correct answers from a list

true_false Boolean true/false questions

short_answer Free-text response with keyword matching

essay Long-form response graded by rubric or AI

fill_in_blank Complete sentences with missing words

matching Match items from two columns