# API

Basis `/api`. Cookie-Sitzung oder lesender Bearer-Token. Schreibende Cookie-Anfragen müssen einen Origin-Header passend zu NEXTAUTH_URL senden. Alle fachlichen Endpunkte prüfen aktuelle Rechte; Rollenbezeichnungen im Request verleihen keine Rechte. Antworten sind privat und nicht cachebar. Fehler: 400 Validierung, 401 Anmeldung, 403 Rechte, 404 nicht vorhanden/nicht sichtbar, 409 Konflikt, 413 Größenlimit, 429 Rate-Limit.

## Aufgaben

- GET `/tasks`: `{items,total,page,pages}`. Query: page, limit (1–100), status (OPEN/ALL/UNERLEDIGT/IN_BEARBEITUNG/ERLEDIGT), q, group, project, tag, priority (1–4), archived (true/false), from/to (YYYY-MM-DD), sort (due/newest).
- POST `/tasks`: wo, was, bisWann (YYYY-MM-DD), owningGroupId; optional assigneeId, priority, tags[], project, parentId, checklist[{text,done}], recurrenceDays, beauftragtAm, firmaBeauftragt.
- GET `/tasks/:id`: Detail inklusive erlaubter Kommentare/Dateien, Unteraufgaben, Abhängigkeiten, letzter Aktivitäten und capabilities.
- PATCH `/tasks/:id`: zwingend version aus zuletzt gelesener Aufgabe; geänderte Felder, optional status/archived. Fehlende Felder bleiben unverändert. Konflikte liefern 409.
- DELETE `/tasks/:id`: JSON `{version}`; nur archivierte, erledigte Aufgaben mit tasks.delete. Anhänge werden zur privaten Cleanup-Queue hinzugefügt.
- GET/POST `/tasks/:id/comments`: Kommentare, GET page, POST `{content}` (max. 10000 Zeichen).
- GET/POST `/tasks/:id/files`: Dateiliste oder Multipart-Feld file, maximal 10 MB. PDF/JPEG/PNG/DOCX/XLSX nach Inhalt.
- GET/DELETE `/tasks/:id/files/:fileId`: geschützter Download bzw. Löschung. Datei muss zur Aufgabe gehören.
- GET `/assignees?group=:id`: minimale Auswahl aktiver Gruppenmitglieder, erfordert tasks.assign in dieser Gruppe.

## Benutzer und RBAC

- GET `/me`: aktueller Principal, grants mit Quelle, verfügbare Gruppen, SMTP-Verfügbarkeit.
- PATCH `/me`: `{currentPassword,password}`; entwertet bestehende Sessions und Tokens.
- GET/POST `/users`: Benutzerliste oder `{name,email,password?}`. Neue Benutzer ohne Rechte; Passwortänderung erforderlich.
- PATCH `/users/:id`: name, email, active, oidcSubject. Keine Rollen- oder Passwortfelder. Verwaltungsrechte separat; privilegierte Konten nur für Berechtigungsverwalter.
- DELETE `/users/:id`: nicht unterstützt; Konten deaktivieren.
- GET `/access`: Gruppen, Rollen, Permissions, Benutzerzuweisungen.
- POST `/access`: action group/role/membership/userRole/groupRole. Payload siehe `src/app/api/access/route.ts` (Zod-Schemas). Rollen-/Mitgliedschaftsvergabe benötigt roles.assign, zusätzlich passende Verwaltungsrechte. Geschützte Rollen und letzter aktiver Administrator sind abgesichert.
- POST `/account`: action requestReset `{email}`, invite `{userId}` oder redeem `{token,password}`. Reset-/Einladungsversand benötigt SMTP; kein Rückschluss auf unbekannte E-Mails in der normalen Antwort. Tokens sind einmalig und laufen nach einer Stunde ab.

## Arbeitsbereich

GET `/workspace?mode=stats|filters|templates|notifications|audit|integrations`. Audit paginiert mit page. Statistiken und Benachrichtigungen berücksichtigen dieselben Aufgabenrechte.

POST `/workspace`, action:

- filter: name, query; deleteFilter: id
- template: name, taskId; deleteTemplate: id
- read: Benachrichtigungs-id
- batch: tasks[{id,version}], status oder archived; Rückgabe results mit Teilerfolgen
- claim: taskId, version; nur unzugewiesene offene Aufgabe mit tasks.claim und aktiver Gruppenmitgliedschaft
- dependency: taskId, dependsOnId, remove?; Kreise, Selbstreferenz und fremde Gruppen werden abgewiesen
- token: name, days (1–90), permissions aus tasks.read/tasks.export/comments.read/files.read; Geheimnis nur einmal angezeigt
- revokeTokens: alle eigenen API-Tokens widerrufen
- calendarToken / revokeCalendar: privater 90-Tage-Kalenderlink / alle eigenen Kalenderlinks widerrufen
- webhook: name, url; disableWebhook: id

## Import und Export

GET `/transfer`: CSV; format=xlsx: Excel; format=ics: Kalender. Export benötigt tasks.export UND tasks.read im jeweiligen Scope. Keine vertraulichen Daten in öffentlichen Dateien. CSV-Zellen mit Formelpräfix werden escaped; XLSX schreibt ausdrücklich Textzellen.

POST `/transfer`: `{csv,commit:false}` oder `{xlsx:"base64",commit:false}` zur Vorschau; commit=true legt gültige Zeilen an. Ergebnis pro Zeile. Spalten: wo, was, bisWann, owningGroupId, assigneeId, priority, project, tags (Komma getrennt). Export enthält zusätzlich id/status, die beim Import keine bestehenden Aufgaben überschreiben. CSV verwendet Semikolon und UTF-8. Größen-/XML-/ZIP-Grenzen schützen den Excel-Parser.

GET `/calendar/:token`: ICS-Abonnement. Der Link ist ein Geheimnis; aktuelle Benutzer- und Aufgabenrechte werden bei jedem Abruf neu geprüft. Lesende Bearer-Tokens können alternativ den regulären Export-Endpunkt nutzen.

## Integrationssicherheit

API-Tokens werden ausschließlich gehasht gespeichert und erben zusätzlich die aktuellen Rechte ihres Besitzers. Sie können keine Schreibaktionen ausführen. Passwortänderung/Deaktivierung widerruft vorhandene Tokens. Webhooks benötigen betreiberseitige Hostfreigabe und enthalten eine HMAC-Signatur; Details in README.Docker.md.