Skip to main content
Assessments are quizzes attached to courses. Instructors create assessments with a set of questions and a passing score threshold. Learners submit answers and receive a scored result indicating whether they passed.
Assessments are linked to courses. A learner must be actively enrolled in a course to submit its assessments.

​
The assessment object

​
id
string
required
Unique identifier for the assessment. Format: asmnt_<alphanumeric>.
​
course_id
string
required
The ID of the course this assessment belongs to.
​
title
string
required
Display title of the assessment.
​
passing_score
number
required
Minimum percentage score required to pass, e.g. 70 for 70%.
​
time_limit_minutes
number
Time allowed to complete the assessment in minutes. null means no time limit.
​
question_count
number
required
Total number of questions in the assessment.

​
List assessments

GET /api/v1/assessments Returns a paginated list of assessments. Filter by course to retrieve all assessments for a specific course.

​
Query parameters

​
course_id
string
Filter assessments by course ID. Recommended when retrieving assessments for a specific course.
​
page
number
default:"1"
Page number to retrieve.
​
per_page
number
default:"20"
Number of assessments per page. Maximum 100.

​
Example

curl "https://your-domain.com/api/v1/assessments?course_id=crs_abc123" \
  -H "Authorization: Bearer <access_token>"

​
Get an assessment

GET /api/v1/assessments/:id Returns a single assessment by its ID, including the full list of questions. 
curl https://your-domain.com/api/v1/assessments/asmnt_qrs001 \
  -H "Authorization: Bearer <access_token>"

​
Create an assessment

POST /api/v1/assessments Creates a new assessment for a course. Requires the admin or instructor role. Questions are added after creation via a separate questions endpoint.

​
Request body

​
course_id
string
required
The ID of the course to attach this assessment to.
​
title
string
required
Display title for the assessment. Between 3 and 200 characters.
​
passing_score
number
required
Minimum percentage score to pass, as an integer from 1 to 100.
​
time_limit_minutes
number
Time limit in minutes. Omit or pass null for no time limit.

​
Example

curl -X POST https://your-domain.com/api/v1/assessments \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "course_id": "crs_abc123",
    "title": "End-of-Module Knowledge Check",
    "passing_score": 70,
    "time_limit_minutes": 20
  }'

​
Submit an assessment

POST /api/v1/assessments/:id/submissions Submits a learner’s answers for scoring. Returns the result immediately, including score and per-answer correctness.

​
Request body

​
answers
array
required
Array of answer objects, one per question.

​
Example

curl -X POST https://your-domain.com/api/v1/assessments/asmnt_qrs001/submissions \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "answers": [
      { "question_id": "q_001", "selected_option_id": "opt_a" },
      { "question_id": "q_002", "selected_option_id": "opt_c" },
      { "question_id": "q_003", "selected_option_id": "opt_b" }
    ]
  }'

​
Submission result schema

​
submission_id
string
required
Unique identifier for this submission.
​
assessment_id
string
required
The ID of the assessment that was submitted.
​
user_id
string
required
The ID of the learner who submitted.
​
score
number
required
Percentage score from 0 to 100.
​
passed
boolean
required
true if the score meets or exceeds the assessment’s passing_score.
​
submitted_at
string
required
ISO 8601 timestamp of when the submission was received.
​
answers
array
required
Per-question result breakdown.

​
Get a submission

GET /api/v1/assessments/:id/submissions/:submission_id Retrieves the result of a specific submission by its ID. 
curl https://your-domain.com/api/v1/assessments/asmnt_qrs001/submissions/sub_yz4567 \
  -H "Authorization: Bearer <access_token>"

​
Retake policy

By default, learners may retake an assessment unlimited times. Each submission is stored independently. Course completion is determined by the learner’s most recent passing submission.
Instructors can configure a maximum number of attempts per assessment. When the limit is reached, submitting returns a 403 response: 
{
  "data": null,
  "meta": null,
  "error": {
    "code": "ATTEMPT_LIMIT_REACHED",
    "message": "You have reached the maximum number of attempts for this assessment.",
    "details": []
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us