Get Learners
Authentication Required: PARENT or ADMIN role
GET /api/learners
string
Filter learners by parent ID (ADMIN only)
Behavior by Role
- ADMIN: Returns all learners, or learners for a specific parent if
parentIdis provided - PARENT: Returns learners belonging to the authenticated parent
Response
Response Example
Error Codes
- 400 - Invalid request
- 500 - Internal server error
Create Learner
Authentication Required: PARENT or ADMIN role
POST /api/learners
string
required
Learner’s name
string
Optional email address (must be valid format if provided)
number
Grade level (K-12, where K=0). Defaults to 5 if not provided
string
User role. Defaults to “LEARNER”
string
Parent ID (ADMIN only). If not provided, uses the authenticated user’s ID
Response
number
Learner user ID
string
Auto-generated username
string
Learner’s name
string
Email address
string
User role (LEARNER)
number
Parent user ID
Response Example
Creating a learner also automatically creates a learner profile with default grade level and subjects, plus 3 starter reward goals.
Error Codes
- 400 - Missing required field: name
- 400 - Invalid email format
- 400 - Learner accounts must have a parent
- 409 - Email already in use
- 409 - Username already taken
- 500 - Failed to create learner account
Delete Learner
Authentication Required: PARENT or ADMIN role
DELETE /api/learners/:id
string
required
Learner user ID to delete
Response
Success Response
Error Codes
- 400 - Can only delete learner accounts
- 403 - Not authorized to delete this learner
- 404 - Learner not found
- 500 - Failed to delete learner
Get Learner Profile
Authentication Required: Any authenticated user with access to the learner
GET /api/learner-profile/:userId
number
required
Learner user ID
Authorization
- ADMIN: Can view any profile
- PARENT: Can view their children’s profiles
- LEARNER: Can view their own profile
If a profile doesn’t exist, one will be automatically created with default values.
Response
string
Profile UUID
string
Learner user ID
number
Grade level (0-12, where 0 is Kindergarten)
object
Knowledge graph with nodes and edges
array
Array of subject strings
object
Performance metrics by subject
array
Recommended subjects for the learner
array
Areas where the learner needs improvement
Response Example
Error Codes
- 400 - Invalid user ID format
- 403 - Forbidden
- 404 - User not found
- 500 - Failed to get or create learner profile
Update Learner Profile
Authentication Required: PARENT or ADMIN role
PUT /api/learner-profile/:userId
string
required
Learner user ID
number | string
Grade level (K-12, where K or 0 is Kindergarten)
array
Array of subject names
array
Recommended subjects
array
Areas needing improvement
object
Knowledge graph data
At least one field must be provided to update. Parents can only update their own children’s profiles.
Response
Returns the updated profile object (same structure as GET response).Error Codes
- 400 - Invalid user ID format
- 400 - No valid update data provided
- 400 - Grade level must be between K and 12
- 403 - Not authorized to update this profile
- 500 - Failed to update learner profile