Skip to main content

​
Exams

​
List Exams

Retrieve all exams (quizzes) in a classroom or facility.
GET /api/exams/exam
curl "http://localhost:8080/api/exams/exam?collection=classroom-uuid"

​
Query Parameters

​
collection
string
Filter by collection (classroom) UUID

​
Response Fields

​
id
string
Exam unique identifier (UUID for published exams, integer for drafts)
​
title
string
Exam title
​
question_sources
array
Array of question source objects defining which exercises to pull from
​
seed
integer
Random seed for question selection
​
question_count
integer
Total number of questions in the exam
​
active
boolean
Whether the exam is currently active
​
archive
boolean
Whether the exam is archived
​
collection
string
UUID of the classroom/collection
​
creator
string
UUID of the user who created the exam
​
date_created
string
ISO 8601 timestamp of creation
​
date_activated
string
ISO 8601 timestamp when exam was activated
​
date_archived
string
ISO 8601 timestamp when exam was archived
​
learners_see_fixed_order
boolean
Whether learners see questions in a fixed order
​
instant_report_visibility
boolean
Whether learners can see their results immediately
​
draft
boolean
Whether this is a draft exam (not yet published)
​
assignments
array
Array of collection UUIDs (groups) assigned to
​
learner_ids
array
Array of individual learner UUIDs assigned to
​
data_model_version
integer
Version of the exam data model

​
Get Exam

Retrieve details of a specific exam.
GET /api/exams/exam/:id
curl http://localhost:8080/api/exams/exam/exam-uuid-here

​
Create Exam

Create a new exam (initially as a draft).
POST /api/exams/exam
curl -X POST http://localhost:8080/api/exams/exam \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Mathematics Quiz",
    "question_count": 10,
    "question_sources": [
      {
        "exercise_id": "exercise-node-uuid",
        "number_of_questions": 5,
        "title": "Addition"
      },
      {
        "exercise_id": "exercise-node-uuid-2",
        "number_of_questions": 5,
        "title": "Subtraction"
      }
    ],
    "seed": 12345,
    "learners_see_fixed_order": false,
    "instant_report_visibility": true,
    "collection": "classroom-uuid",
    "assignments": ["group-uuid"],
    "learner_ids": ["learner-uuid"]
  }'

​
Request Parameters

​
title
string
required
Exam title
​
question_count
integer
required
Total number of questions in the exam
​
question_sources
array
required
Array of question source objects, each with exercise_id, number_of_questions, and title
​
seed
integer
required
Random seed for reproducible question selection
​
collection
string
required
UUID of the classroom this exam belongs to
​
learners_see_fixed_order
boolean
Whether to show questions in fixed order (default: false)
​
instant_report_visibility
boolean
Whether learners see results immediately (default: true)
​
assignments
array
Array of collection (group) UUIDs to assign this exam to
​
learner_ids
array
Array of individual learner UUIDs to assign this exam to

​
Update Exam

Update an existing exam or draft.
PATCH /api/exams/exam/:id
curl -X PATCH http://localhost:8080/api/exams/exam/exam-uuid-here \
  -H "Content-Type: application/json" \
  -d '{
    "active": true,
    "title": "Updated Quiz Title"
  }'

​
Common Update Operations

Activate an exam (publish from draft): 
{
  "active": true
}
Deactivate an exam: 
{
  "active": false
}
Archive an exam: 
{
  "archive": true
}

​
Delete Exam

Delete an exam or draft.
DELETE /api/exams/exam/:id
curl -X DELETE http://localhost:8080/api/exams/exam/exam-uuid-here

​
Get Exam Sizes

Calculate the total size of all resources (exercises) in exams.
GET /api/exams/exam/size
curl "http://localhost:8080/api/exams/exam/size?collection=classroom-uuid"

​
Response

Returns an array of objects with exam IDs as keys and sizes in bytes as values: 
[
  {
    "exam-uuid-1": 10485760
  },
  {
    "exam-uuid-2": 5242880
  }
]

​
Question Sources

Question sources define which exercises to pull questions from. Each source object contains:
​
exercise_id
string
UUID of the exercise content node
​
number_of_questions
integer
How many questions to include from this exercise
​
title
string
Title of the exercise
​
counter_in_exercise
integer
Question counter within the exercise

​
Exam Lifecycle

Exams go through several states:
  1. Draft: Initial state when created (draft: true). Can be edited freely.
  2. Active: Published and available to learners (active: true, draft: false).
  3. Inactive: Published but not currently available (active: false, archive: false).
  4. Archived: Closed and marked complete (archive: true).
When an exam is activated (active: true), it transitions from draft to published exam and receives a UUID identifier. When an exam is archived, all associated MasteryLog records are marked as complete.

​
Exam Assignments

Exam assignments work the same way as lesson assignments:
  • assignments: Array of collection (group) UUIDs
  • learner_ids: Array of individual learner UUIDs
These fields automatically create ExamAssignment records when the exam is created or updated.

Build docs developers (and LLMs) love

Get started for freeTalk to us