REST API Reference

SkillBridge exposes a FastAPI backend across 16 routers. Full OpenAPI docs are auto-generated at /docs. Every endpoint (except auth and the public demo logins) requires a JWT bearer token and is scoped to the authenticated user's tenant and role.

A selection of the most important endpoints below.

---

Auth

Endpoint	Method	Description
/auth/login	POST	Email + password → JWT
/auth/login/form	POST	Form-based login (Swagger Authorize button)
/auth/demo/{role}	POST	One-click demo login for student / instructor / parent
/auth/me	GET	Current authenticated user

---

Academy & users (admin)

Endpoint	Method	Description
/academy	GET, PATCH	Tenant settings for the current academy
/users	GET, POST	List and create users within the academy
/users/{id}	GET, PATCH, DELETE	Manage a user (soft delete)

---

Courses, enrollments, assignments

Endpoint	Method	Description
/courses	GET, POST	Courses in the academy; instructor-scoped on read
/courses/{id}	GET, PATCH, DELETE	Manage a course
/enrollments	GET, POST	Enroll students in courses
/assignments	GET, POST	Assignments, with rubric and tutor mode
/assignments/{id}	GET, PATCH, DELETE	Manage an assignment

---

Submissions & grading

Endpoint	Method	Description
/submissions	GET, POST	Student submissions to assignments
/submissions/{id}	GET, PATCH	View / grade a submission
/submissions/{id}/files	POST	Attach files to a submission

---

Quizzes (AI generation + grading)

Endpoint	Method	Description
/quizzes	GET, POST	List and create quizzes
/quizzes/generate	POST	AI-generate a quiz draft from topic / standard / file
/quizzes/{id}/submit	POST	Student submits answers
/quizzes/submissions/{id}	GET, PATCH	Instructor reviews AI pre-grading, approves / overrides

---

Tutor

Endpoint	Method	Description
/tutor/sessions	GET, POST	Tutor sessions bound to an assignment
/tutor/sessions/{id}/message	POST	Send a message to the Socratic tutor (text + optional images)
/tutor/insights/{student_id}	GET	Per-student weak-spot insights for instructors

---

Exams & practice

Endpoint	Method	Description
/exams	GET	Available practice exams
/exams/{id}/questions	GET	Questions, including QC and multiple-select types
/practice	GET, POST	Adaptive practice sessions

---

Study plans, parents, gamification

Endpoint	Method	Description
/study_plans/{student_id}	GET, POST	Personalized weekly study plan
/parents/summary	GET	AI-generated progress summary for the linked child
/gamification/leaderboard	GET	XP and badge leaderboard

---

Health

Endpoint	Method	Description
/health	GET	Liveness check

---

Design notes

Thin routers, fat services. Routers parse, authorize, and delegate. All logic is in the service layer. See architecture.md.

Role-gated by dependency. require_role(...) runs before handler code. No endpoint can skip the role check.

Tenant-scoped by identity. Every query derives its tenant from the authenticated user, never from a request parameter.

OpenAPI for free. FastAPI generates the full spec from Pydantic schemas; /docs is the live interactive reference.