Skip to main content
Assessments contain diagnostic questions used to evaluate student knowledge before personalized learning path generation.

​
List Assessments

curl "http://localhost:8000/api/assessments?userId=00000000-0000-0000-0000-000000000000&targetNodeId=abc123"
GET /api/assessments List assessments with optional filters.

​
Query Parameters

​
userId
string
Filter by user UUID
​
targetNodeId
string
Filter by target node UUID

​
Response

​
[]
array
​
id
string
Assessment UUID
​
userId
string
User UUID
​
targetNodeId
string
Target node UUID
​
type
string
diagnostic, quiz, or recall
​
title
string | null
Assessment title
​
createdAt
string
ISO 8601 timestamp
​
completedAt
string | null
ISO 8601 timestamp when all questions were answered

​
Get Assessment

GET /api/assessments/:id Retrieve a single assessment.

​
Create Assessment

curl -X POST http://localhost:8000/api/assessments \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "00000000-0000-0000-0000-000000000000",
    "targetNodeId": "abc123",
    "type": "diagnostic",
    "title": "React Hooks Diagnostic"
  }'
POST /api/assessments

​
Body Parameters

​
userId
string
required
User UUID
​
targetNodeId
string
required
Target node UUID
​
type
string
Assessment type (default: diagnostic)
​
title
string
Assessment title

​
Update Assessment

PATCH /api/assessments/:id Update assessment metadata (e.g., mark as complete).

​
Body Parameters

​
completedAt
string
ISO 8601 timestamp
​
title
string
New title

​
Questions

​
List Questions

GET /api/assessments/:id/questions Retrieve all questions for an assessment.
​
[]
array
​
id
string
Question UUID
​
assessmentId
string
Assessment UUID
​
nodeId
string | null
Associated node UUID
​
format
string
mcq or open_ended
​
prompt
string
Question text
​
options
string | null
JSON array of options (for MCQ)
​
correctAnswer
string | null
Correct answer (for MCQ)
​
gradingRubric
string | null
JSON grading rubric (for open-ended)
​
difficulty
number
Difficulty level (1-5)
​
createdAt
string
ISO 8601 timestamp

​
Create Question

curl -X POST http://localhost:8000/api/assessments/abc123/questions \
  -H "Content-Type: application/json" \
  -d '{
    "format": "mcq",
    "prompt": "What does useState return?",
    "options": ["An array", "An object", "A function", "A string"],
    "correctAnswer": "An array",
    "difficulty": 2
  }'
POST /api/assessments/:id/questions

​
Body Parameters

​
format
string
required
mcq or open_ended
​
prompt
string
required
Question text
​
nodeId
string
Associated node UUID
​
options
array
Array of answer options (for MCQ)
​
correctAnswer
string
Correct answer (for MCQ)
​
gradingRubric
object
Grading rubric (for open-ended)
​
difficulty
number
Difficulty level 1-5 (default: 1)

​
Answers

​
Submit Answer

curl -X POST http://localhost:8000/api/assessments/abc123/answers \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "00000000-0000-0000-0000-000000000000",
    "questionId": "q123",
    "selectedOption": "An array",
    "isCorrect": true,
    "score": 1
  }'
POST /api/assessments/:assessmentId/answers Submit an answer to a question. Auto-completes the assessment when all questions are answered.

​
Body Parameters

​
userId
string
required
User UUID
​
questionId
string
required
Question UUID
​
answerText
string
Free-text answer (for open-ended)
​
selectedOption
string
Selected option (for MCQ)
​
isCorrect
boolean
Whether the answer is correct
​
score
number
Score (0-1 or 0-100, normalized to 0-1)
​
feedback
string
Feedback text

​
Get Answers

GET /api/assessments/:assessmentId/answers?userId=USER_ID Retrieve all answers for an assessment and user.
​
[]
array
​
id
string
Answer UUID
​
userId
string
User UUID
​
assessmentId
string
Assessment UUID
​
questionId
string
Question UUID
​
answerText
string | null
Free-text answer
​
selectedOption
string | null
Selected option (MCQ)
​
isCorrect
boolean | null
Correctness
​
score
number | null
Score (0-1)
​
feedback
string | null
Feedback text
​
createdAt
string
ISO 8601 timestamp

Build docs developers (and LLMs) love

Get started for freeTalk to us