docs: initial OpenAPI 3.0 spec reverse-engineered from Android/iOS clients

README.md

@@ -1 +1,71 @@
-# sabbath-school-api-docs
+# Sabbath School API documentation
+
+This repository contains an **unofficial, reverse-engineered** OpenAPI 3.0
+specification for the backend API consumed by the Sabbath School mobile and web
+applications.
+
+The maintainers of Adventech do not currently publish an API spec; this file is
+an attempt to give external developers, integrators, and future contributors a
+starting point.
+
+## Source of truth
+
+The spec is generated by reading the typed Retrofit interfaces in the Android
+client:
+
+- `common/auth/src/main/kotlin/app/ss/auth/api/SSAuthApi.kt`
+- `common/auth/src/main/kotlin/app/ss/auth/api/SSTokenApi.kt`
+- `libraries/lessons/api/src/main/kotlin/ss/lessons/api/ResourcesApi.kt`
+- `libraries/lessons/api/src/main/kotlin/ss/lessons/api/SSLessonsApi.kt`
+- `libraries/lessons/api/src/main/kotlin/ss/lessons/api/SSMediaApi.kt`
+- `libraries/lessons/api/src/main/kotlin/ss/lessons/api/SSQuarterliesApi.kt`
+
+And reconciled with the iOS client at
+`Adventech/sabbath-school-ios/dev/Sabbath School/API/API.swift`.
+
+The hosts (`https://sabbath-school.adventech.io`,
+`https://sabbath-school-stage.adventech.io`) are taken from the `SSConstants.kt`
+file in the Android client.
+
+## Caveats
+
+1. **This is not authoritative.** If the maintainers publish an official spec,
+   that supersedes this file.
+2. **Most paths return the SPA fallback** at the time of writing. Only
+   `/api/v{2,3}/auth/*` is publicly callable. Data endpoints are reachable from
+   the mobile clients but not from arbitrary external callers.
+3. **`auth/refresh` is currently broken** (HTTP 500). See
+   https://github.com/Adventech/sabbath-school-ios/issues/204.
+
+## How to use
+
+Validate the spec locally:
+
+```bash
+# Using redocly CLI
+npx @redocly/cli lint openapi.yaml
+
+# Using swagger-cli
+npx swagger-cli validate openapi.yaml
+```
+
+Render with Redoc:
+
+```bash
+npx @redocly/cli preview-docs openapi.yaml
+```
+
+## Contributing
+
+If you spot an endpoint that is not covered, or a schema that has drifted,
+open a PR against `openapi.yaml` with the relevant Retrofit interface quoted
+in the PR description. The maintainers are more likely to accept a doc PR
+than a code PR for non-trivial behaviour, so keep diffs small and tied to a
+specific source file.
+
+## Authorship
+
+Initial draft: 2026-08-01, by an external contributor reverse-engineering the
+public Android and iOS source. No API keys, refresh tokens, or user data
+were stored beyond ephemeral anonymous sign-in responses used to verify
+endpoint shapes.