SSP+ API Routes
Complete reference for every HTTP route exposed by the SchoolSoft+ Next.js application. All routes live under /api/ and are handled by Next.js Route Handlers (App Router). Requests and responses use JSON unless otherwise noted.
Introduction
SchoolSoft+ acts as a proxy between your browser and SchoolSoft. When you log in, SSP+ forwards your credentials to SchoolSoft, extracts the resulting session cookies, and stores them as httpOnly cookies on the SSP+ domain. Your password is never stored.
Subsequent requests to SSP+ routes reconstruct the SchoolSoft cookies from the stored SSP+ cookies and forward them to SchoolSoft's API, then return the response (transformed or enriched) back to the client.
Auth Model
Most routes call getSessionCookies(req) to extract SSP+ cookies, then call authUser(cookies, school) to validate the session against SchoolSoft's /rest-api/session endpoint before serving the request.
#SSP+ cookies
Cookies set by SSP+ on login
Error Format
All error responses follow a consistent JSON shape:
Common HTTP status codes
POST /api/login
Authenticates against SchoolSoft using the provided credentials. On success, sets httpOnly SSP+ session cookies and upserts a Firestore profile document.
POST /api/logout
GET /api/session
GET /api/schedule
Proxies SchoolSoft's /rest-api/student/calendar/lessons/week/{week} endpoint. De-duplicates lessons by startDate+endDate and sorts ascending.
GET /api/lunch
GET /api/news
Fetches and HTML-scrapes SchoolSoft's student start page. Extracts news article IDs and titles from the #news_con_content table using Cheerio.
GET /api/subjects
Fetches all subject rooms and enriches each with entities (assignments + planning items), unread counts, and teachers - via three parallel requests per subject.
GET /api/assignments/week & GET /api/assignment/[id]
Conversations
Conversations are stored in Firestore (conversations_v1). Both direct messages (DMs) and group chats are supported. Group chats can optionally be end-to-end encrypted.
#Messages
Friends
PATCH /api/presence
Updates the current user's presence status in Firestore (presence_v1). The client calls this on an interval. Presence is interpreted by the frontend as:
- Online - last heartbeat < 3 minutes ago
- In SchoolSoft+ - last heartbeat 3–15 minutes ago
- Offline - last heartbeat > 15 minutes ago
Group Invites
Profile
Profiles are stored in Firestore (profiles_v1). The PUT endpoint also re-fetches /rest-api/session to keep first/last name, email, and school name in sync with SchoolSoft, and propagates display name and profile picture changes to all existing conversations.
Notes
Notes are stored in Firestore (notes_v2) and support rich text (Tiptap JSON). Notes can be published to a public share link.
Countdowns
Countdowns are stored in Firestore (countdowns_v1) and rendered as a dashboard widget.
GET /api/people/class
Scrapes the SchoolSoft class list HTML page and returns structured student data. Includes name and optional contact info where available.
GET /api/people/staff
GET /api/users/search
Searches all SchoolSoft+ users by display name or username (Firestore query, min 2 chars). Excludes the current user from results.
GET /api/stats
Returns anonymous aggregate usage statistics from the stats Firestore collection. No authentication required.