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 Versuche je IP+E-Mail in 10 min (Prozessspeicher) |
| 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 |
aktive Betreiberkonten (origin='operator') |
| POST |
/api/v1/accounts |
S+R, B |
Konto mit Passwort anlegen, erhält persönlichen Raum |
| 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; Antwort enthält das Token einmalig. Keine Oberfläche |
| POST |
/api/v1/invitations/{id}/accept |
– |
Token, Anzeigename, Passwort → Konto, Mitgliedschaft, Session |
Datenräume
| Methode |
Pfad |
Auth |
Zweck |
| GET |
/api/v1/rooms |
S+R |
wählbare Räume |
| POST |
/api/v1/rooms |
S+R |
gemeinsamen Raum anlegen, Anlegende Person wird Verwalter |
| GET |
/api/v1/rooms/{id}/members |
S+R, M |
Mitglieder |
| POST |
/api/v1/rooms/{id}/members |
S+R, M |
bestehendes Konto als member oder manager aufnehmen |
| DELETE |
/api/v1/rooms/{id}/members/{subject_id} |
S+R, M |
Mitgliedschaft beenden; letzter Verwalter bleibt. Keine Oberfläche |
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 |
| POST |
/api/v1/connectors |
neue Instanz einer registrierten Quelle; unbekannte Art wird abgewiesen; ersetzt keinen vorhandenen Zugang |
| PATCH |
/api/v1/connectors/{id} |
Name, Einstellungen und Zugangsdaten derselben Instanz |
| DELETE |
/api/v1/connectors/{id} |
Zugang löschen; bestehende Referenzen bleiben und werden nicht umgehängt |
| POST |
/api/v1/connectors/{id}/probe |
Zugang prüfen |
| 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}}.