UNOFFICIAL

SchoolSoft API Reference

SchoolSoft does not publish an official public API. This documentation is entirely reverse-engineered by observing network traffic from the SchoolSoft web application. It is the foundation on which SchoolSoft+ is built.

This API is unofficial and undocumented. Endpoints may change without notice. SchoolSoft+ does not store your credentials - they are forwarded directly to SchoolSoft over HTTPS on every request and never persisted.

Introduction

SchoolSoft's backend is a Java-based web application running at https://sms.schoolsoft.se. It exposes two types of data surfaces:

REST API - JSON endpoints under /rest-api/ that return structured data (schedule, lunch, subjects, session info).
HTML pages - Legacy JSP pages (e.g. the news feed, staff directory) that SchoolSoft+ scrapes with Cheerio. Responses are ISO-8859-1 encoded and must be decoded to UTF-8.

Base URL

Every request targets a school-specific subdirectory. The school slug appears in the URL path and is stored client-side in the ssp_school cookie after login.

text

https://sms.schoolsoft.se/{school}/rest-api/...
https://sms.schoolsoft.se/{school}/jsp/...

# Example (school slug = "engelska")
https://sms.schoolsoft.se/engelska/rest-api/session

SchoolSoft+ builds a per-school Axios client for every request:

typescript

function createSchoolsoftClient(school: string) {
  return axios.create({
    baseURL: `https://sms.schoolsoft.se/${school}`,
    headers: {
      "User-Agent": "Schoolsoft+/1.0 (https://ssp.elias4044.com; +)",
      Referer: `https://sms.schoolsoft.se/${school}/`,
      Origin: "https://sms.schoolsoft.se",
    },
  });
}

Encoding & Format

REST endpoints return UTF-8 JSON. HTML JSP pages return ISO-8859-1 (Latin-1) encoded HTML. Always request these as arraybuffer and decode with iconv-lite:

typescript

import iconv from "iconv-lite";

const response = await api.get("/jsp/student/right_student_startpage.jsp", {
  headers: { Cookie: cookieString },
  responseType: "arraybuffer",
});

const html = iconv.decode(response.data as Buffer, "ISO-8859-1");

Authentication - Login Flow

SchoolSoft uses form-based authentication. Submitting credentials to the Login JSP endpoint returns a HTTP 302 redirect on success (or HTTP 200 with an error page on failure). The session cookies are extracted from the Set-Cookie response headers.

SchoolSoft+ sets these session cookies as httpOnly cookies on the SSP+ domain prefixed with ssp_ (e.g. ssp_jsessionid). They are reconstructed into the original format before forwarding to SchoolSoft.

Session Cookies

Every subsequent request to SchoolSoft must include all three cookies in the Cookie request header, in this exact format:

http

Cookie: JSESSIONID=F92FC4EC3A1B...; hash=d85914fa8b...; usertype=1

Cookie breakdown

Name	Type	Required	Description
`JSESSIONID`	`string`	Yes	Java EE session token. Required on every request.
`hash`	`string`	Yes	Secondary auth token paired with the session. Include if present.
`usertype`	`string`	No	"1" = student, "2" = teacher, "3" = guardian

Session Endpoint

Schedule

Returns all lesson events for a given ISO week number. The endpoint returns an array (or sometimes an object whose values are the lessons). SchoolSoft+ de-duplicates by startDate+endDate key and sorts ascending.

Lunch Menu

News (HTML Scraping)

SchoolSoft does not expose news as a REST endpoint. Instead, news items are embedded in the student start-page HTML. SchoolSoft+ fetches this page and scrapes it with Cheerio.

Subjects

Subject Entities & Teachers

For each subject, SchoolSoft+ fetches three additional endpoints in parallel to enrich the data:

Assignments

Error Handling

SchoolSoft returns non-standard status codes in some cases. SchoolSoft+ normalises these before returning them to the client. Common scenarios:

Status codes observed from SchoolSoft

Name	Type	Required	Description
`302`	`redirect`	No	Successful login. Cookies are in Set-Cookie headers.
`200`	`html`	No	Login failed - body is an error HTML page.
`401`	`json/html`	No	Session expired. Re-authentication required.
`404`	`html`	No	Resource not found or wrong school slug.
`500`	`html`	No	Internal SchoolSoft error (rare, typically transient).

Rate Limits & Notes

SchoolSoft does not document rate limits. Aggressive polling will likely result in a temporary IP or session ban. SchoolSoft+ caches responses where possible and avoids redundant requests.

The school slug is case-sensitive and must exactly match what SchoolSoft expects.
REST endpoints require the Accept: application/json header to receive JSON; without it, some endpoints return HTML.
The JSESSIONID expires after a period of inactivity - SchoolSoft+ re-validates on every API call.
All times returned by SchoolSoft are in the Europe/Stockholm time zone (CET/CEST).