Skip to main content

STEMBlock.ai Frontend - API Endpoints Summary

Base URL: process.env.NEXT_PUBLIC_API_URL (default: http://localhost:3001)

All requests include Authorization: Bearer \{token\} header (added automatically by Axios interceptor)

Authentication Endpoints​

POST /auth/login​

Used By: Login page

Request: { email: string, password: string }
Response: { user: User, accessToken: string, student?: Student }

POST /auth/register​

Used By: Registration page

Request: RegisterRequest {
  email: string
  password: string
  firstName: string
  lastName: string
  role: UserRole
  age?: number
  gradeLevel?: string
}
Response: { user: User, accessToken: string, student?: Student }

GET /auth/profile​

Used By: Auth context (optional profile fetch)

Response: { user: User, accessToken: string, student?: Student }

GET /auth/google​

Used By: Login page (Google OAuth)

  • Redirects to Google OAuth provider
  • Returns 503 if not available

Assignment Endpoints​

GET /assignments​

Used By: Student dashboard, Coach dashboard Query Params:

  • classId (optional) - Filter by class
Response: Assignment[]

GET /assignments/{id}​

Used By: Assignment detail page

Response: Assignment

POST /assignments​

Used By: Coach - Create assignment

Request: {
  title: string
  description: string
  type?: AssignmentType
  dueDate?: string | null
  maxScore: number
  classId: string
}
Response: Assignment

PUT /assignments/{id}​

Used By: Coach - Update assignment

Request: {
  title?: string
  description?: string
  type?: AssignmentType
  dueDate?: string | null
  maxScore?: number
}
Response: Assignment

DELETE /assignments/{id}​

Used By: Coach - Delete assignment

Response: void

Submission Endpoints​

GET /submissions​

Used By: Student dashboard, Coach dashboard Description: Get all submissions for current user

Response: Submission[]

GET /submissions/my​

Used By: Student dashboard Description: Get current student's submissions

Response: Submission[]

GET /submissions/{id}​

Used By: Submission detail/review page

Response: Submission

POST /submissions​

Used By: Student - Create submission

Request: { assignmentId: string }
Response: Submission

POST /submissions/{id}/upload​

Used By: Student - Upload file to submission

Request: FormData {
  file: File
  fileType: FileType (PHOTO | CODE | NOTEBOOK | ESSAY | OTHER)
}
Response: SubmissionFile

PATCH /submissions/{id}/submit​

Used By: Student - Mark submission as submitted

Response: Submission

DELETE /submissions/{id}​

Used By: Student - Delete submission

Response: void

Evaluation Endpoints​

GET /evaluations/{id}​

Used By: Student/Parent evaluation view

Response: Evaluation

GET /evaluations/submission/{submissionId}​

Used By: Get evaluation by submission ID

Response: Evaluation

Class Endpoints​

GET /classes​

Used By: Coach dashboard Description: Get all classes for current coach

Response: Class[]

GET /classes/{id}​

Used By: Class detail page

Response: Class (with students and assignments)

POST /classes​

Used By: Coach - Create class

Request: {
  name: string
  description?: string
}
Response: Class

POST /classes/{id}/students/{studentId}​

Used By: Coach/Admin - Add student to class

Response: void

DELETE /classes/{id}/students/{studentId}​

Used By: Coach/Admin - Remove student from class

Response: void

Parent Endpoints​

GET /parents/me/children​

Used By: Parent dashboard Description: Get all children and their submissions

Response: {
  id: string
  children: {
    student: {
      id: string
      user: User
      gradeLevel: string
      submissions: Submission[]
      classes: { class: Class }[]
    }
  }[]
}

GET /parents/me/children/{studentId}​

Used By: Child report page Description: Get detailed student data

Response: StudentReport (student with all submissions)

GET /parents/me/children/{studentId}/insights​

Used By: Parent dashboard sidebar Description: Get AI-generated insights

Response: {
  whatsGoingWell: string[]
  areasToFocusOn: string[]
  waysToSupport: string[]
}

Admin Endpoints​

GET /admin/stats​

Used By: Admin dashboard Description: Get system statistics

Response: {
  totalUsers: number
  totalStudents: number
  totalParents: number
  totalCoaches: number
  totalClasses: number
  totalAssignments: number
  totalSubmissions: number
}

GET /admin/classes​

Used By: Admin classes page Description: Get all classes in system

Response: Class[]

GET /admin/coaches​

Used By: Admin class creation Description: Get all coaches

Response: Coach[]

GET /admin/students​

Used By: Admin class management Description: Get all students

Response: Student[]

POST /admin/classes​

Used By: Admin - Create class

Request: {
  name: string
  description?: string
  coachId: string
}
Response: Class

POST /admin/classes/{classId}/students/{studentId}​

Used By: Admin - Add student to class

Response: void

DELETE /admin/classes/{classId}/students/{studentId}​

Used By: Admin - Remove student from class

Response: void

Google Classroom Integration Endpoints​

GET /google-classroom/auth​

Used By: Coach class settings Description: Get Google OAuth auth URL

Response: { authUrl: string }

POST /google-classroom/sync/{classId}​

Used By: Coach class settings Description: Sync assignments from Google Classroom

Response: void

POST /google-classroom/disable/{classId}​

Used By: Coach class settings Description: Unlink class from Google Classroom

Response: void

Feedback Endpoints​

POST /api/v1/feedback​

Used By: Parent/Student feedback form Access: PARENT, STUDENT Description: Submit new feedback to coaches/admins

Request: {
  subject: string
  content: string
  type: 'SUGGESTION' | 'QUESTION' | 'CONCERN' | 'PRAISE'
  recipientId?: string
}
Response: { data: Feedback, meta: { message, timestamp } }

GET /api/v1/feedback/my​

Used By: Parent/Student feedback history Access: All authenticated users Description: Get own submitted feedback

Query: { page?: number, limit?: number }
Response: { data: Feedback[], meta: { pagination } }

GET /api/v1/feedback/inbox​

Used By: Coach/Admin feedback inbox Access: COACH, ADMIN, ORG_ADMIN Description: Get feedback received

Query: { page?: number, limit?: number, status?: FeedbackStatus }
Response: { data: Feedback[], meta: { pagination } }

GET /api/v1/feedback/{id}​

Used By: Feedback detail view Access: Owner or recipient Description: Get single feedback by ID

Response: { data: Feedback }

POST /api/v1/feedback/{id}/respond​

Used By: Coach/Admin respond to feedback Access: COACH, ADMIN, ORG_ADMIN Description: Add response to feedback

Request: { response: string }
Response: { data: Feedback }

PATCH /api/v1/feedback/{id}/status​

Used By: Coach/Admin update feedback status Access: COACH, ADMIN, ORG_ADMIN Description: Update feedback status

Request: { status: 'PENDING' | 'REVIEWED' | 'RESOLVED' }
Response: { data: Feedback }

Gamification Endpoints​

GET /gamification/stats​

Used By: Student dashboard Access: STUDENT Description: Get complete gamification stats (XP, level, streak, achievements)

Response: GamificationStats {
  xp: number
  level: number
  streak: StreakData
  achievements: Achievement[]
  recentActivity: Activity[]
}

GET /gamification/streak​

Used By: Student dashboard streak display Access: STUDENT Description: Get current streak data

Response: StreakData {
  currentStreak: number
  longestStreak: number
  lastActivityDate: string
  streakDays: string[]
}

GET /gamification/xp​

Used By: Student dashboard XP/level display Access: STUDENT Description: Get XP and level data

Response: XPData {
  totalXP: number
  currentLevel: number
  xpToNextLevel: number
  xpProgress: number
}

GET /gamification/achievements​

Used By: Student achievements page Access: STUDENT Description: Get all achievements

Response: Achievement[] {
  id: string
  name: string
  description: string
  icon: string
  earned: boolean
  earnedAt?: string
}

POST /gamification/activity​

Used By: Manual activity recording (testing) Access: STUDENT Description: Record student activity

Response: { success: boolean, milestone?: MilestoneInfo }

Analytics Endpoints​

GET /analytics/classes/{classId}/heatmap​

Used By: Coach class analytics Access: COACH, ADMIN Description: Get heat map data for class performance visualization

Response: HeatMapResponse {
  data: HeatMapCell[][]
  xLabels: string[] // Assignment names
  yLabels: string[] // Student names
}

GET /analytics/coach/heatmap​

Used By: Coach dashboard overview Access: COACH, ADMIN Description: Get overview heat map for all classes

Response: HeatMapResponse {
  data: HeatMapCell[][]
  xLabels: string[] // Metrics: 'Avg Score', 'Completion', 'Submissions'
  yLabels: string[] // Class names
}

GET /analytics/coach/class-stats​

Used By: Coach dashboard Access: COACH, ADMIN Description: Get class statistics summary

Response: ClassStats[] {
  classId: string
  className: string
  studentCount: number
  assignmentCount: number
  averageScore: number
  completionRate: number
}

Error Handling​

All endpoints follow this error response pattern:

// On error:
{
  statusCode: number
  message: string
  error?: string
}

Common Status Codes:

  • 401: Unauthorized (invalid/expired token)
  • 403: Forbidden (insufficient permissions)
  • 404: Not found
  • 400: Bad request (validation error)
  • 500: Server error

Error Handling in Code:

try {
  const response = await api.get('/endpoint')
} catch (err: any) {
  const message = err.response?.data?.message || 'Default error'
  setError(message)
}

API Interceptors​

Request Interceptor (lib/api.ts):

  • Adds Authorization: Bearer \{token\} header if token exists

Response Interceptor (lib/api.ts):

  • On 401: Clears localStorage and redirects to /login

Data Types Used in Requests/Responses​

User​

{
  id: string
  email: string
  firstName: string
  lastName: string
  role: 'STUDENT' | 'COACH' | 'PARENT' | 'ADMIN'
  createdAt: string
  updatedAt: string
}

Student​

{
  id: string
  userId: string
  age: number
  gradeLevel: string
  user: User
  createdAt: string
}

Coach​

{
  id: string
  userId: string
  user: User
  createdAt: string
}

Class​

{
  id: string
  coachId: string
  name: string
  description?: string
  googleClassroomId?: string
  googleClassroomName?: string
  googleClassroomSyncEnabled: boolean
  lastGoogleSyncAt?: string
  createdAt: string
  updatedAt: string
  coach?: Coach
  students?: ClassStudent[]
  assignments?: Assignment[]
  _count?: { students: number, assignments: number }
}

Assignment​

{
  id: string
  title: string
  description: string
  type?: 'ROBOT_DESIGN' | 'CODE' | 'DOCUMENTATION' | 'ESSAY' | 'MIXED'
  dueDate?: string | null
  maxScore: number
  createdAt: string
  updatedAt: string
  class?: { id: string, name: string, coach?: Coach }
  _count?: { submissions: number }
}

Submission​

{
  id: string
  assignmentId: string
  studentId: string
  status: 'DRAFT' | 'SUBMITTED' | 'EVALUATED' | 'PUBLISHED'
  submittedAt?: string | null
  createdAt: string
  updatedAt: string
  assignment?: Assignment
  student?: Student
  files?: SubmissionFile[]
  evaluation?: Evaluation
}

SubmissionFile​

{
  id: string
  submissionId: string
  fileName: string
  fileType: 'PHOTO' | 'CODE' | 'NOTEBOOK' | 'ESSAY' | 'OTHER'
  fileUrl: string
  fileSize?: number | null
  createdAt?: string
  uploadedAt?: string
}

Evaluation​

{
  id: string
  submissionId: string
  overallScore: number
  aiConfidence: number
  robotDesignScore?: number | null
  codeQualityScore?: number | null
  documentationScore?: number | null
  technicalWritingScore?: number | null
  aiFeedback: {
    robotDesign?: { score: number, strengths: string[], improvements: string[] }
    codeQuality?: { score: number, strengths: string[], improvements: string[] }
    documentation?: { score: number, strengths: string[], improvements: string[] }
    technicalWriting?: { score: number, strengths: string[], improvements: string[] }
    summary: string
    nextSteps: string[]
  }
  status: 'AI_GENERATED' | 'COACH_REVIEWED' | 'PUBLISHED'
  createdAt: string
  updatedAt: string
  submission?: Submission
}

Feedback​

{
  id: string
  submitterId: string
  submitterRole: 'PARENT' | 'STUDENT'
  recipientId: string
  recipientRole: 'COACH' | 'ADMIN'
  type: 'SUGGESTION' | 'QUESTION' | 'CONCERN' | 'PRAISE'
  subject: string
  content: string
  status: 'PENDING' | 'REVIEWED' | 'RESOLVED'
  response?: string
  respondedAt?: string
  createdAt: string
  updatedAt: string
  submitter?: User
  recipient?: User
}

API Call Patterns​

In Student Dashboard​

const [assignments, setAssignments] = useState<Assignment[]>([])
const [submissions, setSubmissions] = useState<Submission[]>([])

useEffect(() => {
  const response = await api.get('/assignments')
  setAssignments(response.data)
}, [])

In Coach Class Detail​

const classId = params.id as string

useEffect(() => {
  const classResponse = await api.get(`/classes/${classId}`)
  setClassData(classResponse.data)
  
  const assignmentsResponse = await api.get(`/assignments?classId=${classId}`)
  setAssignments(assignmentsResponse.data)
}, [classId])

Creating Resource (Assignment)​

await api.post('/assignments', {
  title: 'Assignment Title',
  description: 'Description',
  type: 'CODE',
  maxScore: 100,
  classId
})

Updating Resource​

await api.put(`/assignments/${assignmentId}`, {
  title: 'Updated Title',
  // only include fields to update
})

Deleting Resource​

await api.delete(`/assignments/${assignmentId}`)

Testing API Endpoints​

Base URL for local development: http://localhost:3001

Example curl requests:

# Login
curl -X POST http://localhost:3001/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"student@example.com","password":"password"}'

# Get assignments
curl -X GET http://localhost:3001/assignments \
  -H "Authorization: Bearer YOUR_TOKEN"

# Create assignment
curl -X POST http://localhost:3001/assignments \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"My Assignment","description":"...","maxScore":100,"classId":"class-id"}'