Files
tsumugu/docs/architecture/API_REFERENZ.md
T
LarsandCursor 3c190c87b4
Deploy Development / deploy (push) Successful in 28s
Test Suite / pytest-backend (push) Successful in 1m37s
Test Suite / smoke-dev (push) Successful in 0s
Test Suite / frontend-build (push) Successful in 9s
Halte Anlagen und Versand als eigene Verwendung fest, damit die uebermittelte Fassung und ihre Nachweise spaeter nicht still mit der Arbeitsfassung verschmelzen.
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-18 09:57:59 +02:00

196 lines
13 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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](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 |
| 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}/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}}`.