Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.sunschool.xyz/llms.txt

Use this file to discover all available pages before exploring further.

​
Get Learner Settings

Authentication Required: Any authenticated user
GET /api/learner-settings/:learnerId
curl -X GET https://api.sunschool.xyz/api/learner-settings/3 \
  -H "Authorization: Bearer {token}"
​
learnerId
number
required
Learner user ID

​
Response

Response Example
{
  "doubleOrLossEnabled": false
}
​
doubleOrLossEnabled
boolean
Whether double-or-loss mode is enabled for this learner

​
Update Double-or-Loss Setting

Authentication Required: PARENT or ADMIN role
PUT /api/learner-settings/:learnerId/double-or-loss
curl -X PUT https://api.sunschool.xyz/api/learner-settings/3/double-or-loss \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true
  }'
​
learnerId
number
required
Learner user ID
​
enabled
boolean
required
Enable or disable double-or-loss mode
Double-or-loss mode allows learners to risk their points for higher rewards on quiz questions.

​
Response

{
  "learnerId": 3,
  "doubleOrLossEnabled": true
}

​
Activities (Legacy Rewards)

Authentication Required: Any authenticated user
GET /api/activities
curl -X GET https://api.sunschool.xyz/api/activities \
  -H "Authorization: Bearer {token}"
Returns the list of active activities (legacy rewards catalog).

​
Response

Response Example
[
  {
    "id": "activity_1",
    "name": "Reading Time",
    "description": "30 minutes of reading",
    "category": "Educational",
    "isActive": true
  }
]

​
Allocate Tokens to Activities

Authentication Required: Any authenticated user
POST /api/awards/allocate
curl -X POST https://api.sunschool.xyz/api/awards/allocate \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "allocations": [
      {"activityId": "activity_1", "tokens": 5},
      {"activityId": "activity_2", "tokens": 3}
    ]
  }'
​
allocations
array
required
Array of allocation objects with activityId and tokens

​
Response

{
  "awards": [
    {
      "id": "award_1",
      "activityId": "activity_1",
      "tokens": 5,
      "status": "PENDING"
    }
  ]
}

​
Error Codes

  • 400 - allocations must be an array
  • 400 - Not enough tokens (INSUFFICIENT_TOKENS)
  • 500 - Server error

​
Cash In Award

Authentication Required: Any authenticated user
POST /api/awards/:awardId/cash-in
curl -X POST https://api.sunschool.xyz/api/awards/award_1/cash-in \
  -H "Authorization: Bearer {token}"
​
awardId
string
required
Award ID to cash in

​
Response

{
  "status": "OK"
}

​
Toggle Award Sharing

Authentication Required: Any authenticated user
POST /api/awards/:awardId/share
curl -X POST https://api.sunschool.xyz/api/awards/award_1/share \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "active": true,
    "title": "My Achievement",
    "description": "I earned this award!"
  }'
​
awardId
string
required
Award ID to share
​
active
boolean
required
Enable or disable sharing
​
title
string
Share title
​
description
string
Share description

​
Response

{
  "shareUrl": "https://app.sunschool.xyz/users/alice-123456/award/abc123hash"
}

​
Get Public Award Share

No Authentication Required - Public endpoint
GET /users/:username/award/:hash
curl -X GET https://api.sunschool.xyz/users/alice-123456/award/abc123hash
​
username
string
required
Username of the award owner
​
hash
string
required
Unique share hash

​
Response

Response Example
{
  "username": "alice-123456",
  "title": "My Achievement",
  "description": "I earned this award!",
  "awardId": "award_1",
  "activityName": "Reading Time",
  "tokens": 5,
  "sharedAt": "2024-01-15T10:30:00.000Z"
}

​
Error Codes

  • 404 - Not found (share doesn’t exist or is not active)