Todo API – Dokumentation

Diese Dokumentation richtet sich an Nutzer, die die Todo-API in eigenen Anwendungen, Scripts oder Apps einbinden möchten. Jeder Nutzer hat einen persönlichen API-Key (Token), der nach dem Login verwendet wird.

1. Übersicht

Die Todo-API ermöglicht Anmeldung, Verwaltung von Aufgaben, Unteraufgaben, Gruppen und (für Admins) Nutzerverwaltung. Alle Endpoints außer Health und öffentliche Stats erfordern Authentifizierung:

• Web (Browser): Session-Cookie nach Login; Requests mit credentials: 'include'.
• Externe Clients (Apps, Scripts, andere Dienste): API-Key im Header Authorization: Bearer <token>.

2. Authentifizierung

Session (Web)

Login/Register setzt ein Session-Cookie. Alle Requests mit credentials: 'include' senden.

API-Key / Bearer Token (Apps, Scripts, externe Nutzung)

Jeder Nutzer hat einen API-Key (Token). Login liefert token im Response. Für alle weiteren Requests: Header Authorization: Bearer <token>. Token gültig 7 Tage.

3. Auth-Endpoints

Method	Pfad	Beschreibung
POST	/auth/register	Registrieren
POST	/auth/login	Anmelden
POST	/auth/logout	Abmelden
GET	/auth/me	Aktueller User
PATCH	/auth/password	Passwort ändern
PATCH	/auth/email	E-Mail ändern
PATCH	/auth/name	Name ändern (max. alle 14 Tage)
GET	/auth/login-history	Login-Historie

POST /auth/register

// Body
{ "name": "Max", "email": "max@example.de", "password": "geheim123" }
// Response 201
{ "user": { "id": 1, "email": "max@example.de", "name": "Max", "role": "user" } }

POST /auth/login

// Body
{ "email": "max@example.de", "password": "geheim123" }
// Response 200
{ "user": { "id": 1, "email": "...", "name": "...", "role": "user" }, "token": "eyJ..." }
// token = dein API-Key für Authorization: Bearer <token>

GET /auth/me

Liefert den aktuell angemeldeten User. Auth erforderlich.

4. Todos

Method	Pfad	Beschreibung
GET	/todos?group_id=1	Todos laden (optional: Gruppe)
POST	/todos	Todo erstellen
PATCH	/todos/:id	Todo aktualisieren
DELETE	/todos/:id	Todo löschen

GET /todos – Ohne group_id: Persönliche Todos. Mit group_id: Gruppen-Todos (User muss Mitglied sein).

POST /todos

{
  "text": "Aufgabe",
  "description": "Optional",
  "due_date": "2025-12-31",
  "group_id": 1,
  "subtasks": [{ "text": "Teil 1" }]
}

PATCH /todos/:id

{ "done": true, "due_date": "2025-12-31", "text": "Neuer Titel", "description": "Neu" }

5. Unteraufgaben

Method	Pfad	Beschreibung
POST	/todos/:todoId/subtasks	Unteraufgabe hinzufügen
PATCH	/todos/:todoId/subtasks/:id	Unteraufgabe umschalten
DELETE	/todos/:todoId/subtasks/:id	Unteraufgabe löschen

Body für POST: { "text": "Unteraufgabe" }

6. Gruppen

Method	Pfad	Beschreibung
GET	/groups	Meine Gruppen
POST	/groups	Gruppe erstellen
PATCH	/groups/:id	Gruppe bearbeiten (nur Besitzer)
DELETE	/groups/:id	Gruppe löschen (nur Besitzer)
GET	/groups/:id/members	Mitglieder
POST	/groups/:id/members	Mitglied per E-Mail hinzufügen
PATCH	/groups/:id/members/:userId	Berechtigungen
DELETE	/groups/:id/members/:userId	Mitglied entfernen
POST	/groups/:id/leave	Gruppe verlassen

POST /groups Body: { "name": "Team", "description": "Optional" }

7. Admin-API

Nur für Nutzer mit role: "admin".

Method	Pfad	Beschreibung
GET	/admin/stats	Statistiken
GET	/admin/users	Alle Nutzer
GET	/admin/groups	Alle Gruppen
PATCH	/admin/users/:id/role	Rolle ändern
PATCH	/admin/users/:id/ban	Sperren/Entsperren
GET	/admin/users/:id/groups	Nutzer-Gruppen bearbeiten
PATCH	/admin/users/:id/groups	Nutzer-Gruppen speichern
GET	/admin/help-requests	Hilfe-Anfragen
PATCH	/admin/help-requests/:id	Status setzen
GET	/admin/help-knowledge	KI-Wissensdatenbank
POST	/admin/help-knowledge	Eintrag hinzufügen
DELETE	/admin/help-knowledge/:id	Eintrag löschen
GET	/admin/settings	Einstellungen
PATCH	/admin/settings	Einstellungen speichern

8. Hilfe (KI)

Method	Pfad	Beschreibung
POST	/help/chat	KI-Anfrage stellen
POST	/help/forward	An Support weiterleiten

9. Fehlerformat

Alle Fehler: { "error": "Nachricht" }

Status	Bedeutung
400	Ungültige Anfrage
401	Nicht angemeldet
403	Keine Berechtigung
404	Nicht gefunden
409	Konflikt (z.B. E-Mail existiert)
500	Serverfehler

Health: GET /api/health (ohne Auth) → { "ok": true, "version": "1.0.0" }

// Body
{ "name": "Max", "email": "max@example.com", "password": "secret123" }
// Response 201
{ "user": { "id": 1, "email": "max@example.com", "name": "Max", "role": "user" } }

// Body
{ "email": "max@example.com", "password": "secret123" }
// Response 200
{ "user": { "id": 1, "email": "...", "name": "...", "role": "user" }, "token": "eyJ..." }
// token = your API key for Authorization: Bearer <token>

{
  "text": "Task",
  "description": "Optional",
  "due_date": "2025-12-31",
  "group_id": 1,
  "subtasks": [{ "text": "Step 1" }]
}

{ "done": true, "due_date": "2025-12-31", "text": "New title", "description": "New" }