lernlaterne-users-api v0.1.0

Auto-generated from the route registry. Last regenerated: 2026-06-08T16:14:29.345Z.

Health — /health
{"ok":true}
/auth
POST/auth/login
Example
curl -sS -X POST 'http://beta-user.lernlaterne.de/auth/login' -H 'Content-Type: application/json' -d '{"email":"you@example.com","password":"your-password"}'
curl -sS -X POST 'http://beta-user.lernlaterne.de/auth/login' -H 'Content-Type: application/json' -d '{"username":"teacher","password":"your-password"}'
curl -sS -X POST 'http://beta-user.lernlaterne.de/auth/login' -H 'Content-Type: application/json' -d '{"organizationSlug":"demo-org","username":"lena","password":"your-password"}'
Description
Create session. Identifier modes (exactly one): email + password; global username + password; organizationSlug + username + password (students).
Params
email (body, string)
username (body, string)
organizationSlug (body, string)
*password (body, string)
POST/auth/logout
Example
curl -sS -X POST 'http://beta-user.lernlaterne.de/auth/logout' -H 'Content-Type: application/json' -d '{}'
Description
Invalidate the current session (optional Bearer).
Params
—
POST/auth/logout-all
Example
curl -sS -X POST 'http://beta-user.lernlaterne.de/auth/logout-all' -H 'Authorization: Bearer <token>' -H 'Content-Type: application/json' -d '{}'
Description
Delete every session for the authenticated user.
Params
—
GET/v1/auth/verify-email
Example
http://beta-user.lernlaterne.de/v1/auth/verify-email?token=verification-token
Description
Verify email from link (token query). Optional redirect via REGISTRATION_VERIFY_REDIRECT_URL.
Params
*token (query, string)
/v1/admin
GET/v1/admin/snapshot
Example
curl -sS -X GET 'http://beta-user.lernlaterne.de/v1/admin/snapshot?q=&limit=50' -H 'Authorization: Bearer <token>'
Description
Paginated dashboard snapshot for admins.
Params
q (query, string)
limit (query, number (users cap))
POST/v1/admin/invitations/account
Example
curl -sS -X POST 'http://beta-user.lernlaterne.de/v1/admin/invitations/account' -H 'Authorization: Bearer <token>' -H 'Content-Type: application/json' -d '{"targetRole":"personal","targetPlan":"solo","intervalMonths":1,"sendEmail":false}'
Description
Mint account invitation (solo/edu/free). Returns token and signup URL; optional sendEmail.
Params
*targetRole (body, 'personal'|'teacher')
*targetPlan (body, 'free'|'solo'|'edu')
presetEmail (body, string)
intervalMonths (body, 1|3|12|null)
sendEmail (body, boolean)
/v1/internal
POST/v1/internal/checkout/fulfillment
Example
—
Description
Stripe checkout fulfillment stub — mint account invite (X-Internal-Secret). Idempotent per checkout session id.
Params
*stripeCheckoutSessionId (body, string)
*customerEmail (body, string)
*targetRole (body, 'personal'|'teacher')
*targetPlan (body, 'free'|'solo'|'edu')
intervalMonths (body, 1|3|12|null)
/v1/invitations
GET/v1/invitations/:token
Example
http://beta-user.lernlaterne.de/v1/invitations/invite-token-placeholder
Description
Public preview before completion (student/group or account: targetRole, targetPlan, presetEmail).
Params
*token (path, string)
POST/v1/invitations/:token/complete
Example
curl -sS -X POST 'http://beta-user.lernlaterne.de/v1/invitations/invite-token-placeholder/complete' -H 'Content-Type: application/json' -d '{"password":"SecurePass123"}'
Description
Finish invitation. Students: password + optional displayName. Account: email, username, password; teacher invites need org fields.
Params
*token (path, string)
email (body, string)
*password (body, string)
displayName (body, string)
username (body, string)
organizationDisplayName (body, string)
organizationSlug (body, string)
/v1/me
GET/v1/me/session
Example
curl -sS -X GET 'http://beta-user.lernlaterne.de/v1/me/session' -H 'Authorization: Bearer <token>'
Description
Minimal account summary (id, role, displayName).
Params
—
GET/v1/me/bootstrap
Example
curl -sS -X GET 'http://beta-user.lernlaterne.de/v1/me/bootstrap' -H 'Authorization: Bearer <token>'
Description
Full learner bootstrap payload.
Params
—
GET/v1/me/account
Example
curl -sS -X GET 'http://beta-user.lernlaterne.de/v1/me/account' -H 'Authorization: Bearer <token>'
Description
Account profile, subscription snapshot (personal/teacher/admin), Stripe wiring hints, and billing notes. Students see profile only.
Params
—
PATCH/v1/me/account/subscription
Example
curl -sS -X PATCH 'http://beta-user.lernlaterne.de/v1/me/account/subscription' -H 'Authorization: Bearer <token>' -H 'Content-Type: application/json' -d '{"plan":"edu","intervalMonths":12}'
Description
Simulate plan / billing interval (SQLite only). Allowed outside production, or when USERS_ACCOUNT_SELF_SERVE_BILLING=1. Personal and teacher only.
Params
*plan (body, 'free'|'solo'|'edu' (legacy: personal→solo))
*intervalMonths (body, 1|3|12|null)
PATCH/v1/me/settings
Example
curl -sS -X PATCH 'http://beta-user.lernlaterne.de/v1/me/settings' -H 'Authorization: Bearer <token>' -H 'Content-Type: application/json' -d '{"audioVolume":80}'
Description
Patch learner UI settings (language prefs, audio, etc.).
Params
learnLang (body, string)
speakLang (body, string)
hoverTranslate (body, boolean)
audioSentenceHighlight (body, boolean)
audioVolume (body, number 0–100)
audioSpeed (body, number 50–150)
videoSceneTransitions (body, boolean)
GET/v1/me/content
Example
curl -sS -X GET 'http://beta-user.lernlaterne.de/v1/me/content' -H 'Authorization: Bearer <token>'
Description
Full learner content state (favorites, reading progress, exercise results). For dashboard and analytics — not included in bootstrap.
Params
—
PATCH/v1/me/content
Example
curl -sS -X PATCH 'http://beta-user.lernlaterne.de/v1/me/content' -H 'Authorization: Bearer <token>' -H 'Content-Type: application/json' -d '{"favorites":["dia001"]}'
Description
Patch learner-owned content state (favorites, reading upserts, structured exercises blobs).
Params
favorites (body, string[])
reading (body, { upsert: …[] })
exercises (body, nested record)
/v1/me/vocabulary
GET/v1/me/vocabulary/lists
Example
curl -sS -X GET 'http://beta-user.lernlaterne.de/v1/me/vocabulary/lists' -H 'Authorization: Bearer <token>'
Description
Summaries of vocabulary lists visible to the caller.
Params
—
POST/v1/me/vocabulary/lists
Example
curl -sS -X POST 'http://beta-user.lernlaterne.de/v1/me/vocabulary/lists' -H 'Authorization: Bearer <token>' -H 'Content-Type: application/json' -d '{"title":"Week 1","entries":[{"headword":"Haus"}]}'
Description
Create list — supply exactly one of `text` lines or structured `entries`. Each entry is resolved via the Lexicon before save (cached `headword` + `partOfSpeech` plus `lemmaId` / `proposalId`).
Params
*title (body, string)
text (body, string)
entries (body, { headword | lemma | lemmaId | token, partOfSpeech? }[] (exactly one key per row besides optional POS))
GET/v1/me/vocabulary/lists/:listId
Example
curl -sS -X GET 'http://beta-user.lernlaterne.de/v1/me/vocabulary/lists/list-id-placeholder' -H 'Authorization: Bearer <token>'
Description
Single list with entries (share metadata for teacher owners).
Params
*listId (path, string)
PATCH/v1/me/vocabulary/lists/:listId
Example
curl -sS -X PATCH 'http://beta-user.lernlaterne.de/v1/me/vocabulary/lists/list-id-placeholder' -H 'Authorization: Bearer <token>' -H 'Content-Type: application/json' -d '{"title":"Renamed"}'
Description
Rename list and/or replace entries.
Params
*listId (path, string)
title (body, string)
text (body, string)
entries (body, { headword | lemma | lemmaId | token, partOfSpeech? }[])
DELETE/v1/me/vocabulary/lists/:listId
Example
curl -sS -X DELETE 'http://beta-user.lernlaterne.de/v1/me/vocabulary/lists/list-id-placeholder' -H 'Authorization: Bearer <token>'
Description
Delete list and contained entries.
Params
*listId (path, string)
POST/v1/me/vocabulary/lists/:listId/entries
Example
curl -sS -X POST 'http://beta-user.lernlaterne.de/v1/me/vocabulary/lists/list-id-placeholder/entries' -H 'Authorization: Bearer <token>' -H 'Content-Type: application/json' -d '{"entries":[{"headword":"Schule","partOfSpeech":"N"}]}'
Description
Append vocabulary rows (resolved headword + optional POS; or `lemmaId`).
Params
*listId (path, string)
*entries (body, { headword | lemma | lemmaId | token, partOfSpeech? }[])
PATCH/v1/me/vocabulary/lists/:listId/entries/:entryId
Example
curl -sS -X PATCH 'http://beta-user.lernlaterne.de/v1/me/vocabulary/lists/list-id-placeholder/entries/entry-id-placeholder' -H 'Authorization: Bearer <token>' -H 'Content-Type: application/json' -d '{"headword":"laufen"}'
Description
Patch one vocabulary row.
Params
*listId (path, string)
*entryId (path, string)
headword (body, string)
lemma (body, string (alias of headword))
lemmaId (body, string)
token (body, string)
partOfSpeech (body, string)
DELETE/v1/me/vocabulary/lists/:listId/entries/:entryId
Example
curl -sS -X DELETE 'http://beta-user.lernlaterne.de/v1/me/vocabulary/lists/list-id-placeholder/entries/entry-id-placeholder' -H 'Authorization: Bearer <token>'
Description
Remove one vocabulary row.
Params
*listId (path, string)
*entryId (path, string)
/v1/register
POST/v1/register/free
Example
curl -sS -X POST 'http://beta-user.lernlaterne.de/v1/register/free' -H 'Content-Type: application/json' -d '{"email":"you@example.com","username":"you_global","password":"SecurePass123"}'
Description
Create a free personal account (role personal, plan free). Email verification required before login.
Params
*email (body, string)
*username (body, string)
*password (body, string)
displayName (body, string)
GET/v1/register/verify-email
Example
http://beta-user.lernlaterne.de/v1/auth/verify-email?token=verification-token
Description
Alias for email verification (same handler as /v1/auth/verify-email).
Params
*token (query, string)
POST/v1/register/resend-verification
Example
curl -sS -X POST 'http://beta-user.lernlaterne.de/v1/register/resend-verification' -H 'Content-Type: application/json' -d '{"email":"you@example.com"}'
Description
Resend verification email for an unverified billable account.
Params
*email (body, string)
POST/v1/register/finish-setup
Example
—
Description
After Stripe checkout + email verification: set password (and organization for edu teachers).
Params
*email (body, string)
*password (body, string)
organizationDisplayName (body, string)
organizationSlug (body, string)
/v1/teacher
POST/v1/teacher/students/manual
Example
curl -sS -X POST 'http://beta-user.lernlaterne.de/v1/teacher/students/manual' -H 'Authorization: Bearer <token>' -H 'Content-Type: application/json' -d '{"displayName":"New Student","password":"SecurePass123"}'
Description
Provision an org-scoped student with generated username.
Params
*displayName (body, string)
*password (body, string)
POST/v1/teacher/groups
Example
curl -sS -X POST 'http://beta-user.lernlaterne.de/v1/teacher/groups' -H 'Authorization: Bearer <token>' -H 'Content-Type: application/json' -d '{"displayName":"Class A"}'
Description
Create a class/group bucket.
Params
*displayName (body, string)
contactEmail (body, string (email))
POST/v1/teacher/invitations/group
Example
curl -sS -X POST 'http://beta-user.lernlaterne.de/v1/teacher/invitations/group' -H 'Authorization: Bearer <token>' -H 'Content-Type: application/json' -d '{"groupId":"group-id-placeholder"}'
Description
Mint reusable invitation token limited to a group.
Params
*groupId (body, string)
maxUses (body, number)
expiresAt (body, number (epoch ms))
POST/v1/teacher/invitations/student
Example
curl -sS -X POST 'http://beta-user.lernlaterne.de/v1/teacher/invitations/student' -H 'Authorization: Bearer <token>' -H 'Content-Type: application/json' -d '{}'
Description
Mint student invitation (optionally bound to a group).
Params
presetDisplayName (body, string)
groupId (body, string)
maxUses (body, number)
expiresAt (body, number (epoch ms))
PATCH/v1/teacher/students/:studentId
Example
curl -sS -X PATCH 'http://beta-user.lernlaterne.de/v1/teacher/students/student-id-placeholder' -H 'Authorization: Bearer <token>' -H 'Content-Type: application/json' -d '{"displayName":"Renamed"}'
Description
Update student metadata (remarks, exam mode, etc.).
Params
*studentId (path, string)
displayName (body, string)
remarks (body, string|null)
examMode (body, boolean)
DELETE/v1/teacher/students/:studentId
Example
curl -sS -X DELETE 'http://beta-user.lernlaterne.de/v1/teacher/students/student-id-placeholder' -H 'Authorization: Bearer <token>'
Description
Delete student user and dependent rows.
Params
*studentId (path, string)
PATCH/v1/teacher/vocabulary/lists/:listId/share
Example
curl -sS -X PATCH 'http://beta-user.lernlaterne.de/v1/teacher/vocabulary/lists/list-id-placeholder/share' -H 'Authorization: Bearer <token>' -H 'Content-Type: application/json' -d '{"shareAllStudents":true}'
Description
Toggle sharing for a vocabulary list owned by the teacher.
Params
*listId (path, string)
*shareAllStudents (body, boolean)
groupIds (body, string[])
Health
GET/health
Example
http://beta-user.lernlaterne.de/health
Description
Liveness probe.
Params
—
Lexicon (public, separate host)
GET(lexicon) /v1/{locale}/lemmas …
Example
curl -sS -X GET 'https://lexicon.lernlaterne.de/v1/de/lemmas?prefix=Ha&pageSize=10&speakLang=en'
curl -sS -X GET 'https://lexicon.lernlaterne.de/v1/de/surfaces?prefix=ha&maxSurfaces=5&maxLemmasPerSurface=5&speakLang=en'
curl -sS -X GET 'https://lexicon.lernlaterne.de/v1/de/surfaces/H%C3%A4user&speakLang=en'
curl -sS -X POST 'https://lexicon.lernlaterne.de/v1/de/lemmas/propose?speakLang=en' -H 'Content-Type: application/json' -d '{"tokens":["Haus","gehen"],"source":"user_upload"}'
Description
Lemma prefix list, surface autosuggest, exact surface→lemmas, lemma detail, and bulk propose are implemented by the **Lexicon** service (`LEXICON_API_BASE_URL`, e.g. `https://lexicon.lernlaterne.de`). This API only stores **your** vocabulary lists. See Lexicon `/help` and `/openapi.yaml`. Typical routes: `GET …/v1/de/lemmas?prefix=&pageSize=`, `GET …/v1/de/surfaces?prefix=`, `GET …/v1/de/surfaces/{surface}`, `POST …/v1/de/lemmas/propose`.
Params
LEXICON_API_BASE_URL (query, env on clients / tooling)
Meta
GET/help
Example
http://beta-user.lernlaterne.de/help
Description
This developer catalog (HTML).
Params
—