Skip to main content

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 parentId is 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
Username is automatically generated from the name and timestamp. Email is optional for learners. If omitted, a temporary email will be generated.

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
Parents can only delete their own learners. This action is irreversible.

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
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
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