Files
tsumugu/docs/architecture/API_REFERENZ.md
T
LarsandCursor c774fb7206
Deploy Development / deploy (push) Successful in 26s
Test Suite / pytest-backend (push) Successful in 1m35s
Test Suite / smoke-dev (push) Successful in 0s
Test Suite / frontend-build (push) Successful in 8s
Lege Anlagen und Versandbelege direkt am Schriftstueck ab, damit die Zuordnung aus dem Vorgang gezogen werden kann und mehrere Belege an einem Versand bleiben.
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-18 10:35:32 +02:00

13 KiB
Raw Blame History

Tsumugu – API-Referenz (Ist-Stand)

Stand: 18.10.2026. 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
POST /api/v1/connectors Paperless (überschreibt den vorhandenen) oder IMAP anlegen
DELETE /api/v1/connectors/{id} Zugang löschen
POST /api/v1/connectors/{id}/probe Zugang prüfen
GET /api/v1/sources/paperless/documents?q= Paperless-Suche (letzter eigener Zugang)
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
GET /api/v1/sources/imap/message?connector_id=&mailbox=&uid= Vorschau vor dem Übernehmen
GET /api/v1/external-refs/{id}/content Paperless-Datei zum Ansehen (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)

Quelleninhalte werden mit den Zugängen der anfragenden Person geladen (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}}.