Repository navigation
06 API Reference
Huzefaaa2 edited this page Jan 29, 2026
·
1 revision
POST /api/auth/login
Content-Type: application/json
{
"login_id": "student@magicbus.com",
"password": "password123"
}
Response (200):
{
"token": "eyJhbGciOiJIUzI1NiIs...",
"user_id": 1,
"role": "student",
"student_id": "MB-APAC-2026-ABC01"
}
Error (401):
{
"error": "Invalid credentials"
}
POST /api/auth/register
Content-Type: application/json
{
"email": "student@magicbus.com",
"password": "password123",
"full_name": "John Doe",
"institution": "XYZ University"
}
Response (201):
{
"user_id": 1,
"student_id": "MB-APAC-2026-ABC01",
"message": "Registration successful"
}
GET /api/users/{user_id}
Authorization: Bearer <token>
Response (200):
{
"user_id": 1,
"login_id": "student@magicbus.com",
"full_name": "John Doe",
"student_id": "MB-APAC-2026-ABC01",
"email": "student@magicbus.com",
"role": "student",
"institution": "XYZ University",
"education_level": "Undergraduate",
"created_at": "2026-01-15T10:00:00Z"
}
PUT /api/users/{user_id}
Authorization: Bearer <token>
Content-Type: application/json
{
"full_name": "John Doe Updated",
"phone": "+1-555-0123",
"skills": "Python, JavaScript, SQL"
}
Response (200):
{
"message": "Profile updated successfully"
}
GET /api/users?role=student&limit=50&offset=0
Authorization: Bearer <admin_token>
Response (200):
{
"total": 50,
"limit": 50,
"offset": 0,
"users": [...]
}
GET /api/modules/assignments/{user_id}
Authorization: Bearer <token>
Response (200):
{
"assignments": [
{
"module_assignment_id": 1,
"module_id": "py101",
"title": "Python Basics",
"description": "Introduction to Python",
"duration": 4,
"difficulty_level": "Beginner",
"status": "active",
"progress": 45,
"started_date": "2026-01-15",
"skills": "Python, Programming Fundamentals"
}
]
}
PUT /api/modules/progress/{module_assignment_id}
Authorization: Bearer <token>
Content-Type: application/json
{
"progress": 75,
"status": "in_progress"
}
Response (200):
{
"message": "Progress updated",
"progress": 75,
"updated_at": "2026-01-29T10:00:00Z"
}
POST /api/modules/complete/{module_assignment_id}
Authorization: Bearer <token>
Response (200):
{
"message": "Module completed successfully",
"points_earned": 100,
"badges_earned": ["Learner", "Completed Module"]
}
GET /api/surveys/templates?type=youth_feedback
Authorization: Bearer <token>
Response (200):
{
"templates": [
{
"template_id": 1,
"template_type": "youth_feedback",
"template_name": "Post-Placement Feedback",
"version": 1,
"questions": [...]
}
]
}
POST /api/surveys/submit
Authorization: Bearer <token>
Content-Type: application/json
{
"survey_id": 1,
"responses": {
"q1_overall_performance": 4,
"q2_technical_skills": 4,
"q3_strengths": "Great problem solver",
"q4_improvements": "Improve presentation skills"
}
}
Response (200):
{
"message": "Survey submitted successfully",
"submission_id": "survey_123"
}
GET /api/analytics/user/{user_id}
Authorization: Bearer <token>
Response (200):
{
"user_id": 1,
"total_modules": 5,
"completed_modules": 3,
"avg_completion_pct": 65,
"current_streak": 5,
"total_points": 450,
"badges": ["Learner", "Completed Module", "Week Warrior"],
"sector_fit": {
"sector": "Design & UI/UX",
"fit_score": 75,
"status": "Green"
}
}
GET /api/analytics/dashboard
Authorization: Bearer <admin_token>
Response (200):
{
"total_users": 50,
"active_users_today": 28,
"modules_assigned": 100,
"modules_completed": 60,
"avg_completion_rate": 65,
"at_risk_users": 5,
"top_modules": [...]
}
SELECT
user_id,
sector_interests,
interest_confidence,
skill_readiness_score,
sector_fit_score,
readiness_status
FROM gold.student_sector_fit
WHERE sector_fit_score >= 70
ORDER BY sector_fit_score DESC;SELECT
user_id,
student_id,
modules_assigned,
modules_completed,
avg_completion_pct,
dropout_risk_level,
risk_score,
risk_reason
FROM gold.student_dropout_risk
WHERE dropout_risk_level IN ('HIGH', 'MEDIUM')
ORDER BY risk_score DESC;SELECT
module_id,
COUNT(DISTINCT user_id) as learners,
SUM(CASE WHEN status = 'completed' THEN 1 ELSE 0 END) as completed,
ROUND(100.0 * SUM(CASE WHEN status = 'completed' THEN 1 ELSE 0 END) /
COUNT(DISTINCT user_id), 1) as completion_rate,
AVG(progress) as avg_progress,
MIN(avg_completion_pct) as min_progress,
MAX(avg_completion_pct) as max_progress
FROM gold.module_performance
GROUP BY module_id
ORDER BY completion_rate DESC;from app.integrations.databricks_connector import DatabricksConnector
# Initialize connection
db_connector = DatabricksConnector()
# Query sector fit
sector_data = db_connector.query("""
SELECT * FROM gold.student_sector_fit
WHERE user_id = ?
""", (user_id,))
# Query dropout risk
risk_data = db_connector.query("""
SELECT * FROM gold.student_dropout_risk
WHERE dropout_risk_level = 'HIGH'
""")
# Get module effectiveness
effectiveness = db_connector.query("""
SELECT * FROM gold.module_effectiveness
ORDER BY completion_rate DESC LIMIT 10
""")from app.data.blob_storage import BlobStorageManager
storage_manager = BlobStorageManager()
# Upload document
blob_url = storage_manager.upload_file(
file_path='path/to/document.pdf',
container='documents',
blob_name='student_certificates/student_1.pdf'
)# Download file
content = storage_manager.download_file(
container='documents',
blob_name='student_certificates/student_1.pdf'
)# List all files in container
files = storage_manager.list_files(container='documents')
for file in files:
print(f"File: {file.name}, Size: {file.size} bytes"){
"error": "error_code",
"message": "Human-readable error message",
"timestamp": "2026-01-29T10:00:00Z",
"request_id": "req_12345"
}| Code | HTTP Status | Meaning |
|---|---|---|
| INVALID_CREDENTIALS | 401 | Login failed |
| UNAUTHORIZED | 403 | Insufficient permissions |
| NOT_FOUND | 404 | Resource doesn't exist |
| CONFLICT | 409 | Resource already exists |
| VALIDATION_ERROR | 422 | Invalid input data |
| INTERNAL_ERROR | 500 | Server error |
| SERVICE_UNAVAILABLE | 503 | Service temporarily down |
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 995
X-RateLimit-Reset: 1643452800
| Endpoint Type | Limit | Window |
|---|---|---|
| Read (GET) | 1000 | 1 hour |
| Write (POST/PUT) | 100 | 1 hour |
| Admin (DELETE) | 50 | 1 hour |
| Survey | 10 | 1 day |
{
"event": "user.registered",
"timestamp": "2026-01-29T10:00:00Z",
"data": {
"user_id": 1,
"email": "student@magicbus.com",
"student_id": "MB-APAC-2026-ABC01"
}
}{
"event": "module.completed",
"timestamp": "2026-01-29T10:00:00Z",
"data": {
"user_id": 1,
"module_id": "py101",
"points_earned": 100
}
}{
"event": "survey.submitted",
"timestamp": "2026-01-29T10:00:00Z",
"data": {
"survey_id": 1,
"survey_type": "youth_feedback",
"user_id": 1
}
}Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ...
- Default: 24 hours
- Refresh token: 30 days
- Admin token: 8 hours
# Future OAuth2 integration
oauth_config = {
'client_id': 'xxx',
'client_secret': 'xxx',
'scope': 'user profile surveys'
}import requests
import json
BASE_URL = "http://localhost:8501/api"
TOKEN = "your_bearer_token"
# Headers
headers = {
"Authorization": f"Bearer {TOKEN}",
"Content-Type": "application/json"
}
# Get user profile
response = requests.get(
f"{BASE_URL}/users/1",
headers=headers
)
user_data = response.json()
print(f"User: {user_data['full_name']}")
# Update progress
progress_update = {
"progress": 75,
"status": "in_progress"
}
response = requests.put(
f"{BASE_URL}/modules/progress/1",
headers=headers,
json=progress_update
)
print(response.json())const BASE_URL = "http://localhost:8501/api";
const token = "your_bearer_token";
const headers = {
"Authorization": `Bearer ${token}`,
"Content-Type": "application/json"
};
// Get user analytics
async function getUserAnalytics(userId: number) {
const response = await fetch(
`${BASE_URL}/analytics/user/${userId}`,
{ headers }
);
const data = await response.json();
return data;
}
// Submit survey
async function submitSurvey(surveyId: number, responses: object) {
const response = await fetch(
`${BASE_URL}/surveys/submit`,
{
method: "POST",
headers,
body: JSON.stringify({
survey_id: surveyId,
responses
})
}
);
return await response.json();
}Last Updated: January 29, 2026 API Version: 1.0.0