Skip to main content

​
Get Learners

Authentication Required: PARENT or ADMIN role
GET /api/learners
curl -X GET https://api.sunschool.xyz/api/learners \
  -H "Authorization: Bearer {token}"
​
parentId
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
[
  {
    "id": 3,
    "username": "alice-learner-123456",
    "email": "alice@example.com",
    "name": "Alice",
    "role": "LEARNER",
    "parentId": 1
  }
]

​
Error Codes

  • 400 - Invalid request
  • 500 - Internal server error

​
Create Learner

Authentication Required: PARENT or ADMIN role
POST /api/learners
curl -X POST https://api.sunschool.xyz/api/learners \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Alice",
    "email": "alice@example.com",
    "gradeLevel": 5,
    "role": "LEARNER"
  }'
​
name
string
required
Learner’s name
​
email
string
Optional email address (must be valid format if provided)
​
gradeLevel
number
Grade level (K-12, where K=0). Defaults to 5 if not provided
​
role
string
User role. Defaults to “LEARNER”
​
parentId
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

​
id
number
Learner user ID
​
username
string
Auto-generated username
​
name
string
Learner’s name
​
email
string
Email address
​
role
string
User role (LEARNER)
​
parentId
number
Parent user ID
Response Example
{
  "id": 3,
  "username": "alice-123456",
  "name": "Alice",
  "email": "alice@example.com",
  "role": "LEARNER",
  "parentId": 1
}
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
curl -X DELETE https://api.sunschool.xyz/api/learners/3 \
  -H "Authorization: Bearer {token}"
​
id
string
required
Learner user ID to delete
Parents can only delete their own learners. This action is irreversible.

​
Response

Success Response
{
  "success": true,
  "message": "Learner deleted successfully"
}

​
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
curl -X GET https://api.sunschool.xyz/api/learner-profile/3 \
  -H "Authorization: Bearer {token}"
​
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

​
id
string
Profile UUID
​
userId
string
Learner user ID
​
gradeLevel
number
Grade level (0-12, where 0 is Kindergarten)
​
graph
object
Knowledge graph with nodes and edges
​
subjects
array
Array of subject strings
​
subjectPerformance
object
Performance metrics by subject
​
recommendedSubjects
array
Recommended subjects for the learner
​
strugglingAreas
array
Areas where the learner needs improvement
Response Example
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "userId": "3",
  "gradeLevel": 5,
  "graph": {
    "nodes": [],
    "edges": []
  },
  "subjects": ["Math", "Reading", "Science"],
  "subjectPerformance": {},
  "recommendedSubjects": [],
  "strugglingAreas": [],
  "createdAt": "2024-01-15T10:30:00.000Z"
}

​
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
curl -X PUT https://api.sunschool.xyz/api/learner-profile/3 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "gradeLevel": 6,
    "subjects": ["Math", "Science", "History"]
  }'
​
userId
string
required
Learner user ID
​
gradeLevel
number | string
Grade level (K-12, where K or 0 is Kindergarten)
​
subjects
array
Array of subject names
​
recommendedSubjects
array
Recommended subjects
​
strugglingAreas
array
Areas needing improvement
​
graph
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