Telemetry API reference

The mobile backend posts each completed session with a hashed API key. Points, streak, weekly and monthly summaries are recalculated synchronously and returned in the response.

🔌Endpoints

Request

POST /api/public/ingest-session
Authorization: Bearer <API_KEY>
Content-Type: application/json

{
  "student_id": "uuid",
  "session_date": "2026-07-10",
  "session_start_time": "19:30:00",
  "session_end_time": "22:15:00",
  "planned_hours": 3.0,
  "actual_hours": 2.75,
  "schedule_adherence": 87.5,
  "focus_score": 72.0,
  "bypass_count": 0,
  "nfc_triggered": true,
  "subjects": [
    { "subject_name": "Physics", "hours_studied": 1.0, "proficiency": 2 },
    { "subject_name": "Chemistry", "hours_studied": 0.75, "proficiency": 4 },
    { "subject_name": "Mathematics", "hours_studied": 1.0, "proficiency": 3 }
  ]
}

Response 200

{
  "success": true,
  "daily_points": 78,
  "streak_days": 15,
  "weekly_total": 423,
  "weekly_tier": "gold",
  "monthly_total": 1521,
  "monthly_tier": "gold",
  "new_tier_unlocked": false
}

Summary endpoint

GET /api/public/student-summary?student_id=uuid
Authorization: Bearer <API_KEY>

→ streak, HFI, weekly + monthly summary,
  last 7 daily point totals

Errors: 401 for a missing/invalid/inactive key, 400 with { "error": "..." } for an invalid payload.

📅Daily activity ingestion

Posts one whole study day: day-level planned vs actual hours, adherence, focus and bypasses, plus every session block with subject, chapter, planned/actual start & end times, hours and proficiency. Re-posting the same study_date replaces that day. The response returns the full points breakdown and the weekly / monthly reward tier.

Request

POST /api/public/ingest-daily-activity
Authorization: Bearer <API_KEY>
Content-Type: application/json

{
  "student_id": "uuid",
  "study_date": "2026-07-30",
  "planned_hours": 4.0,
  "actual_hours": 3.3,
  "schedule_adherence": 92,
  "focus_score": 84,
  "bypass_count": 0,
  "nfc_triggered": true,
  "sessions": [
    {
      "subject_name": "Physics",
      "chapter_name": "Rotational Motion",
      "planned_start_time": "18:00",
      "planned_end_time": "19:30",
      "actual_start_time": "18:05",
      "actual_end_time": "19:35",
      "hours_studied": 1.5,
      "proficiency": 2
    },
    {
      "subject_name": "Maths",
      "chapter_name": "Integrals",
      "planned_start_time": "20:00",
      "planned_end_time": "22:00",
      "actual_start_time": "20:10",
      "actual_end_time": "22:00",
      "hours_studied": 1.8,
      "proficiency": 3
    }
  ]
}

Response 200

{
  "success": true,
  "sessions_recorded": 2,
  "actual_hours": 3.3,
  "streak_days": 11,
  "points_breakdown": {
    "pts_focus": 42, "pts_adherence": 13.8,
    "pts_streak": 1.67, "pts_subject": 15,
    "pts_timing": 5, "total_points": 77.47
  },
  "daily_points": 77,
  "weekly_total": 287, "weekly_tier": "bronze",
  "monthly_total": 922, "monthly_tier": "bronze",
  "new_tier_unlocked": false
}