taskmanager/API_DOCUMENTATION.md

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.