Files
tsumugu/docs/architecture/API_REFERENZ.md
T
LarsandClaude Sonnet 5.5 037c0724a8
Deploy Development / deploy (push) Successful in 42s
Test Suite / pytest-backend (push) Successful in 3m28s
Test Suite / smoke-dev (push) Successful in 0s
Test Suite / frontend-build (push) Successful in 20s
Ergänze die Benutzerverwaltung, damit der Betreiber Konten, Rollen und Zugänge verwalten kann.
Der Betreiber legt Konten mit Einmal-Passwort an, deaktiviert und aktiviert sie, setzt Passwörter zurück, beendet Sitzungen und vergibt die Betreiberrolle; der letzte Betreiber und das eigene Konto sind geschützt. Nutzer ändern ihr Passwort und sehen ihre Geräte. Räume kennen neben Mitglied und Verwalter die Rolle Leser, die nichts anlegt und keine Bearbeiten- oder Freigeben-Grants erhält. Verwalter pflegen Mitglieder, Rollen und Einladungen mit Rolle; der Betreiber sieht Räume ohne Inhalte und liest das Verwaltungsprotokoll. Die Login-Begrenzung steht in der Datenbank, unbekannte Konten laufen durch einen Zeitausgleich.

Die lokale Suite läuft mit 116 Tests grün, der Frontend-Build und 16 Node-Tests ebenfalls. Die Oberfläche wurde noch nicht im Browser bedient.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-20 12:49:23 +02:00

18 KiB
Raw Blame History

Tsumugu – API-Referenz (Ist-Stand)

Stand: 18.10.2026, ergänzt am 19.10.2026 um Quelleninstanzen, Fähigkeiten und Zuordnung. Erstellt im Code-Review aus backend/app/main.py, api/routes.py, api/sources.py, api/export.py und api/correspondence.py.

Diese Datei beschreibt die tatsächlich registrierten Endpunkte. Die Sollfassung steht in der technischen Spezifikation, Abschnitt 6.2. OpenAPI ist in allen Umgebungen abgeschaltet (docs_url=None, openapi_url=None). Diese Datei ist deshalb die einzige Übersicht. Sie wird bei jeder Routenänderung mitgepflegt.

Gemeinsame Regeln

Thema Regel im Code
Sitzung Cookie __Host-jinkendo-session (Produktion, HTTPS) bzw. jinkendo-session (Development über HTTP). Gültigkeit SESSION_TTL_HOURS, Default 336 h
Schreibschutz Alle Methoden außer GET/HEAD/OPTIONS unter /api/ verlangen einen Origin aus ALLOWED_ORIGINS (Middleware) und den Header X-CSRF-Token der Session
Datenraum Fachrouten verlangen X-Scope-Kind (personal oder organization) und X-Scope-Id. Beide müssen mit dem in der Session bestätigten Raum übereinstimmen, die Mitgliedschaft wird je Request geprüft
Handlungskontext Lesend als Query context_kind und context_id (case/matter + UUID), schreibend als context: {kind, id} im JSON. Ohne Kontext gelten nur Owner und direkte Grants
Eingaben JSON ohne unbekannte Felder (extra="forbid"); Upload als Multipart
Fehler application/problem+json mit type, title, status, detail, instance, code. 401 keine Session, 403 fehlendes Recht bei sichtbarem Objekt, 404 unsichtbar oder nicht vorhanden, 409 Versionskonflikt, 422 ungültige Eingabe, 429 Login-Begrenzung, 503 Speicher nicht verfügbar
Versionen Ändernde Aufrufe tragen expected_version des geänderten Ankers (Akte, Vorgang, Element, Aufgabe, Frist). Kapitel- und Ordnungsänderungen erhöhen die Version des Behälters
Listen Antwort {items, next_cursor}. next_cursor ist außer in der Chronologie immer null

Legende Spalte „Auth“: – öffentlich, S gültige Session, S+R Session und Datenraum-Header, B Betreiber (is_superadmin), M Verwalter des Raums. Alle Tabellen ohne Spalte „Auth“ verlangen S+R; die Objektrechte prüft danach die Rechteauswertung (RECHTEMODELL_IST.md).

Betrieb

Methode Pfad Auth Zweck
GET /api/health – {status, app}; 503 bei DB-Fehler
GET /health/live – Prozess lebt
GET /health/ready – DB antwortet

Anmeldung, Session, Konten

Methode Pfad Auth Zweck
POST /api/v1/auth/login – E-Mail, Passwort → Session-Sicht und Cookie. 8 Fehlversuche je Bucket (Hash aus IP und E-Mail) in 10 min, gezählt in auth_login_attempts
POST /api/v1/auth/logout S Session widerrufen, Cookie löschen, 204
GET /api/v1/auth/session S Konto, bestätigter Datenraum, Räume, CSRF-Token, Epoche
POST /api/v1/auth/session/scope S Datenraum wechseln (kind, id); erhöht die Epoche
GET /api/v1/auth/bootstrap – {available: true}, solange kein Betreiber existiert, sonst 404
POST /api/v1/auth/bootstrap – erstes Konto als Betreiber anlegen, nur ohne vorhandenen Betreiber
GET /api/v1/auth/demo – Beispielkonten; nur Development mit Datenbank *_test und SEED_DEMO=true, sonst 404
GET /api/v1/accounts S+R, B Betreiberkonten (origin='operator') mit Status, Rolle, letzter Anmeldung; Filter status=active|disabled
GET /api/v1/accounts/{id} S+R, B Detail mit Raummitgliedschaften und Zahl aktiver Sitzungen
POST /api/v1/accounts S+R, B Konto anlegen, persönlicher Raum, must_change_password. Ohne password erzeugt der Server ein Einmal-Passwort und liefert es einmal als temporary_password. is_operator optional
PATCH /api/v1/accounts/{id} S+R, B display_name, is_operator, status (active/disabled). Letzter Betreiber und eigenes Konto sind geschützt
POST /api/v1/accounts/{id}/password-reset S+R, B neues Einmal-Passwort, beendet alle Sitzungen; nicht für das eigene Konto
POST /api/v1/accounts/{id}/sessions/revoke S+R, B alle Sitzungen des Kontos beenden
POST /api/v1/auth/password S eigenes Passwort ändern (current_password, new_password); beendet die anderen Sitzungen; 204. Erlaubt auch bei must_change_password
GET /api/v1/auth/sessions S eigene aktive Sitzungen (Gerätehinweis, zuletzt aktiv)
DELETE /api/v1/auth/sessions/{id} S eigene andere Sitzung beenden; die aktuelle über Abmelden
POST /api/v1/auth/sessions/revoke-others S überall sonst abmelden
GET /api/v1/principals?email= S+R aktives Konto per E-Mail auflösen (ID, Anzeigename)
POST /api/v1/invitations S+R, M Einladung in einen gemeinsamen Raum mit role (member/manager/reader); Antwort enthält das Token einmalig
POST /api/v1/invitations/{id}/accept – Token, Anzeigename, Passwort → Konto, Mitgliedschaft mit der Rolle der Einladung, Session. Widerrufene, benutzte oder abgelaufene Einladung: 404

Datenräume

Methode Pfad Auth Zweck
GET /api/v1/rooms S+R wählbare Räume; include_archived=true ergänzt die archivierten Räume der Person
POST /api/v1/rooms S+R gemeinsamen Raum anlegen, Anlegende Person wird Verwalter
PATCH /api/v1/rooms/{id} S+R, M name, status (active/archived). Archivieren setzt Sitzungen im Raum auf den persönlichen Raum zurück
GET /api/v1/rooms/{id}/members S+R, M Mitglieder mit Rolle und Kontostatus
POST /api/v1/rooms/{id}/members S+R, M bestehendes Konto als member, manager oder reader aufnehmen oder dessen Rolle setzen
PATCH /api/v1/rooms/{id}/members/{subject_id} S+R, M Rolle ändern; letzter Verwalter bleibt. Rückstufung auf reader entzieht Bearbeiten- und Freigeben-Grants auf Objekte des Raums
DELETE /api/v1/rooms/{id}/members/{subject_id} S+R, M Mitgliedschaft beenden; letzter Verwalter bleibt
GET /api/v1/rooms/{id}/invitations S+R, M offene Einladungen ohne Token
DELETE /api/v1/rooms/{id}/invitations/{invitation_id} S+R, M Einladung widerrufen
GET /api/v1/admin/rooms S+R, B alle gemeinsamen Räume mit Zustand, Mitgliederzahl, Verwaltern; keine Inhalte
POST /api/v1/admin/rooms/{id}/managers S+R, B Verwalter einsetzen, nur wenn der Raum keinen aktiven Verwalter hat
GET /api/v1/admin/events S+R, B Verwaltungsprotokoll (cursor, limit) für Konto, Sitzung, Raum, Mitgliedschaft, Einladung

Akten

Methode Pfad Zweck
GET /api/v1/cases lesbare Akten und Unterakten
POST /api/v1/cases Akte anlegen (title, optional parent_case_id, rights_mode, home_scope_id)
GET /api/v1/cases/{id} Akte mit Trail, Kapiteln, Unterakten, Vorgangsbaum, direkten Einbindungen, contained (Inhalte zugeordneter Vorgänge), Aufgaben, Fristen, Grants (für Freigebende)
PATCH /api/v1/cases/{id} Titel, Status open/closed
POST /api/v1/cases/{id}/delete Akte löschen (deleted_at); nur ohne Unterakten und Vorgangszuordnungen. Verlangt edit (siehe Review R-01)
POST /api/v1/cases/{id}/grants Grant per E-Mail (can_read, can_edit, can_share)
POST /api/v1/cases/{id}/chapters Kapitel anlegen, optional parent_chapter_id, document_on
POST /api/v1/cases/{id}/chapters/order Geschwisterreihenfolge
PATCH /api/v1/cases/{id}/content-order Ordnungsart date/position, Richtung
POST /api/v1/cases/{id}/bindings/order eigene Reihenfolge der sichtbaren Einbindungen
POST /api/v1/cases/{id}/bindings/chapters mehrere Einbindungen in ein Kapitel
GET /api/v1/cases/{id}/course fachlicher Verlauf
GET /api/v1/cases/{id}/chronology?cursor= Änderungsprotokoll, 40 Einträge je Seite

Vorgänge

Methode Pfad Zweck
GET /api/v1/matters lesbare Vorgänge mit lesbaren Kontexten
POST /api/v1/matters Vorgang oder Teilvorgang (parent_matter_id, context)
GET /api/v1/matters/{id} Vorgang mit Trail, Zuordnungen (placements, case_links), Teilvorgängen, Querverweisen, Einbindungen, Aufgaben, Fristen
PATCH /api/v1/matters/{id} Titel, Status
POST /api/v1/matters/{id}/delete Vorgang löschen; nur ohne Teilvorgänge. Verlangt edit (Review R-01)
POST /api/v1/matters/{id}/move Akte wechseln (case_id), Elternvorgang setzen oder lösen
POST /api/v1/matters/{id}/case-links Akte zuordnen; Freigaberecht am Vorgang und Bearbeitungsrecht an der Akte
DELETE /api/v1/matter-case-links/{id} Zuordnung lösen
POST /api/v1/matters/{id}/cross-links Querverweis (target_matter_id, target_context)
DELETE /api/v1/matter-cross-links/{id} Querverweis lösen
POST /api/v1/matters/{id}/grants Grant am Vorgang
POST /api/v1/matters/{id}/chapters Kapitel (Kontext als Query)
POST /api/v1/matters/{id}/chapters/order Geschwisterreihenfolge
PATCH /api/v1/matters/{id}/content-order Ordnungsart
POST /api/v1/matters/{id}/bindings/order eigene Reihenfolge
POST /api/v1/matters/{id}/bindings/chapters mehrere Einbindungen in ein Kapitel
GET /api/v1/matters/{id}/course fachlicher Verlauf
GET /api/v1/matters/{id}/chronology?cursor= Änderungsprotokoll

Kapitel

Methode Pfad Zweck
PATCH /api/v1/chapters/{id} Kapiteldatum
PATCH /api/v1/chapters/{id}/title umbenennen
POST /api/v1/chapters/{id}/parent umhängen, parent_chapter_id: null = oberste Ebene
POST /api/v1/chapters/{id}/delete auflösen; Inhalte und Kinder rücken eine Ebene nach oben

Inhalte und Einbindungen

Methode Pfad Zweck
POST /api/v1/notes Notiz mit Einbindung (context, optional placement, chapter_id, dates, communication_direction)
PATCH /api/v1/notes/{id} gemeinsamen Text ändern; Antwort mit visible_bindings und notice
POST /api/v1/files Datei hochladen (Multipart: title, context_kind, context_id, upload, optional Platzierung, Kapitel, Daten, Richtung); PDF, PNG, JPEG, WebP bis 20 MiB
GET /api/v1/files/{id}/content Datei als attachment, no-store
POST /api/v1/external-refs externe Referenz (paperless, imap, url) mit detail
POST /api/v1/sources/link wie oben, nur paperless/imap (doppelter Weg, siehe Connectoren-Befund)
GET /api/v1/elements eigene, nicht eingebundene Elemente (max. 100)
POST /api/v1/elements/{id}/delete überall löschen; nur Element-Owner
PATCH /api/v1/elements/{id}/title Titel
PATCH /api/v1/elements/{id}/summary Kurzbeschreibung (≤ 400 Zeichen)
PATCH /api/v1/elements/{id}/dates Dokument-, Versand-, Zugangsdatum
POST /api/v1/elements/{id}/references Bezug auf eine andere Unterlage (zyklusfrei)
DELETE /api/v1/elements/{id}/references/{target} Bezug lösen
POST /api/v1/bindings Element in weiteren Kontext einbinden (share an der Quelle, edit am Ziel)
DELETE /api/v1/bindings/{id} Einbindung lösen
PATCH /api/v1/bindings/{id}/chapter Kapitel einer Einbindung
PATCH /api/v1/bindings/{id}/communication Richtung in/out/local/null
POST /api/v1/bindings/{id}/annotations kontextbezogene Anmerkung
PUT /api/v1/exceptions Kontextausnahme am Element, Vorgang, Aufgabe oder Frist setzen bzw. löschen; nur Owner
DELETE /api/v1/grants/{id} Grant entziehen

Aufgaben, Fristen, Übersichten, Suche

Methode Pfad Zweck
POST /api/v1/tasks Aufgabe, optional mit Vorgang und Kontext
PATCH /api/v1/tasks/{id} Titel, Arbeitstermin, Status open/done
POST /api/v1/tasks/{id}/assignee zuweisen (E-Mail) oder lösen; legt begrenztes Grant an. Keine Oberfläche
POST /api/v1/tasks/{id}/deadline-links Frist verknüpfen
PUT /api/v1/tasks/{id}/elements verknüpfte Inhalte ersetzen (max. 40)
POST /api/v1/tasks/{id}/dependencies Abhängigkeit von anderer Aufgabe (zyklusfrei)
DELETE /api/v1/tasks/{id}/dependencies/{other} Abhängigkeit lösen
POST /api/v1/deadlines Frist
PATCH /api/v1/deadlines/{id} Titel, Datum
POST /api/v1/deadlines/{id}/fulfill als erfüllt kennzeichnen
GET /api/v1/views/open-tasks offene sichtbare Aufgaben (siehe Review R-11)
GET /api/v1/views/open-deadlines offene sichtbare Fristen (siehe Review R-11)
GET /api/v1/views/recent-matters acht zuletzt geänderte sichtbare Vorgänge
GET /api/v1/placement-targets bearbeitbare Akten und Vorgänge als Ziele
GET /api/v1/search?q= Akten, Vorgänge, Elemente (Titel und Notiztext), max. 50

Quellen

Methode Pfad Zweck
GET /api/v1/connectors eigene Zugänge ohne Secret, mit Fähigkeiten der registrierten Quelle, has_secret und letztem Prüfstand (probe)
GET /api/v1/connectors/{id} Detail eines eigenen Zugangs: nicht geheime Einstellungen, has_secret, Fähigkeiten, Schutzprofil, Prüfstand und Zahl der eigenen Verknüpfungen. Nie das Secret. Fremde Instanz: 404
POST /api/v1/connectors neue Instanz einer registrierten Quelle; Body {kind, name, config}. config wird gegen das Feldmanifest des Moduls geprüft (modules[].config_fields aus /api/v1/sources/capabilities); unbekannte Art oder unbekanntes Feld wird abgewiesen; ersetzt keinen vorhandenen Zugang. Die flachen Felder der ersten Lieferung (base_url, token, host, …) gelten nur als Kompatibilität und werden in config übersetzt
PATCH /api/v1/connectors/{id} Name, Einstellungen und Zugangsdaten derselben Instanz. Ein leeres Geheimnisfeld behält das gespeicherte Geheimnis; der letzte Prüfstand wird zurückgesetzt
DELETE /api/v1/connectors/{id} Zugang löschen; bestehende Referenzen bleiben und werden nicht umgehängt
POST /api/v1/connectors/{id}/probe gespeicherten Zugang prüfen; Ergebnis (auch ein Fehler) wird als Prüfstand festgehalten. Es gibt keine Prüfung mit ungespeicherten Entwürfen
GET /api/v1/sources/capabilities erklärte Such-, Lese- und Editorfähigkeiten; nicht Vorhandenes bleibt falsch
GET /api/v1/sources/{kind}/search Suche der registrierten Quelle im erklärten Umfang; unbekannte Art und nicht erklärte Filter antworten 422
GET /api/v1/sources/{kind}/navigate?connector_id= Fachnavigation, wenn die Quelle sie erklärt
GET /api/v1/sources/{kind}/preview Vorschau vor dem Übernehmen, wenn die Quelle sie erklärt
GET /api/v1/sources/paperless/documents?q=&connector_id= Kompatibilitätshülle der Paperless-Suche; delegiert an dieselbe Suche
GET /api/v1/sources/imap/mailboxes?connector_id= IMAP-Fächer
GET /api/v1/sources/imap/messages?connector_id=&mailbox=&q=&before= Nachrichtenliste, 30 je Seite, Fortsetzung über before
GET /api/v1/sources/imap/message?connector_id=&mailbox=&uid= Vorschau vor dem Übernehmen
GET /api/v1/external-refs/{id}/content Original der gebundenen Instanz über das registrierte Modul (inline)
GET /api/v1/external-refs/{id}/mail vollständige E-Mail als JSON, Identität per Message-ID geprüft
GET /api/v1/external-refs/{id}/mail/original EML
GET /api/v1/external-refs/{id}/mail/attachments/{index} Anlage (inline, siehe Review R-03)
POST /api/v1/external-refs/{id}/assignment Owner ordnet eine mehrdeutige oder ungebundene Referenz bewusst einer eigenen Instanz zu

Quelleninhalte einer eigenen Referenz laufen über die gebundene Instanz. Eine freigegebene Referenz mit use_owner_sources nutzt den gebundenen Zugang des Owners. Zugangsdaten und die übrigen Treffer dieses Zugangs werden nicht ausgeliefert. Eine Suche ohne connector_id wählt bei mehreren eigenen Instanzen nicht den zuletzt angelegten Zugang (Review R-10).

Übergabepaket

Methode Pfad Zweck
GET /api/v1/matters/{id}/export-tree Auswahlbaum mit exportable und Grund
POST /api/v1/matters/{id}/export/review Prüfung: ready, issues, notices, entries mit Paketpfaden
POST /api/v1/matters/{id}/export ZIP nur bei ready; Audit export_created. Knoten attachment, dispatch-item und evidence gehören zur Auswahl

Anlagen und Versand

Alle schreibenden Aufrufe prüfen den Handlungskontext, expected_version und den Behälter (placement, sonst der Kontext). Fremde oder unlesbare IDs antworten mit 404. Ohne Bearbeitungsrecht mit 403.

Methode Pfad Zweck
POST /api/v1/elements/{id}/attachments Anlagen zuordnen, optional nur als Anlagenansicht
POST /api/v1/elements/{id}/attachments/order Reihenfolge
POST /api/v1/elements/{id}/attachments/{attachment_id}/detach nur diese Zuordnung lösen
PATCH /api/v1/bindings/{id}/fold Vorkommen als Anlage, Nachweis oder wieder eigenständig
POST /api/v1/elements/{id}/dispatches Versand dokumentieren und Fassung sichern oder als Lücke kennzeichnen
POST /api/v1/dispatches/{id}/evidence Nachweis ergänzen
POST /api/v1/dispatches/{id}/evidence/{element_id}/detach nur diesen Beleg vom Versand lösen
POST /api/v1/dispatches/{id}/correct Weg, Datum oder Gegenüber berichtigen
GET /api/v1/dispatches/{id} Manifest, Nachweise, Berichtigungen
GET /api/v1/dispatches/{id}/items/{item_id}/content gesicherte Bytes; eine Lücke liefert 404 und nicht die aktuelle Datei

Eingabe für beide POST-Aufrufe: {context, selected: [Knoten-IDs], assignments: {Knoten-ID: connector_id}}.