# 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](TSUMUGU_TECHNICAL_SPEC.md). 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](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, `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}}`.