Files
tsumugu/docs/architecture/API_REFERENZ.md
T
LarsandClaude Sonnet 5.5 5f60e1fe40
Deploy Development / deploy (push) Successful in 39s
Test Suite / pytest-backend (push) Successful in 5m24s
Test Suite / smoke-dev (push) Successful in 0s
Test Suite / frontend-build (push) Successful in 21s
Vereine Ablage, Akte und Vorgang in einem Navigationsbaum mit Fokus und Nachladen.
Der Baum Meine Ablage steht jetzt auch auf den Seiten von Akte und Vorgang und ersetzt die Spalte Struktur. Ein Klick öffnet den Eintrag und klappt seine Struktur auf: Überblick, Kapitel und Unterkapitel, Unterakten, Vorgänge und Teilvorgänge. Der Pfad bleibt offen, die aktuelle Zeile ist hervorgehoben und nach dem Neuladen stimmt der Fokus wieder. Ein Vorgang steht unter jeder Akte, in der er liegt, und unter Vorgänge; ein Klick unter einer Akte öffnet ihn in diesem Aktenkontext. So wechselt man direkt von Vorgang zu Vorgang. Kapitel anlegen und verschieben geht im Baum.

Die Struktur eines Knotens kommt aus neuen schlanken Endpunkten (cases und matters outline), die nur Lesbares liefern, und wird beim Aufklappen einmal nachgeladen. Die Zweispaltenansicht mit dem Lesebereich beginnt erst, wenn neben dem Baum genug Platz bleibt.

Im Browser gegen die lokale Umgebung durchgespielt (Akte, Vorgang unter der Akte, Wechsel zwischen Vorgängen, Kapitel anlegen, Neuladen, Vorgang ohne Akte, Handy, Hell und Dunkel). Die Backend-Suite läuft mit 149 Tests grün, der Frontend-Build und 37 Node-Tests ebenfalls.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-22 12:11:36 +02:00

235 lines
21 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, 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 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`), `account_kind: main` (Mitarbeiter zum Hauptnutzer machen). 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 / E | `name` (Verwalter); `status` und `default_visibility` nur der Eigentümer (E). 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 |
| POST | `/api/v1/rooms/{id}/owner` | S+R, E | Raum an ein aktives Mitglied übertragen (Eigentümer); der neue Eigentümer wird Verwalter |
| GET | `/api/v1/rooms/{id}/exposure` | S+R, Mitglied | eigene Akten und Vorgänge: mit dem Raum geteilt (`room`) oder dort abgelegt, aber nicht geteilt (`private`) |
| POST | `/api/v1/rooms/{id}/my-content/visibility` | S+R, Mitglied | `room`: alle eigenen im Raum abgelegten Akten und Vorgänge mit dem Raum teilen; `private`: alle eigenen Freigaben an diesen Raum beenden |
| GET | `/api/v1/cases/{id}/room-share`, `/api/v1/matters/{id}/room-share` | S+R, Owner | Freigaben des Eintrags an Datenräume (mit Mitgliedern, Rolle, Ausnahme) und die Räume, mit denen er noch teilen kann |
| PUT / DELETE | `/api/v1/cases/{id}/room-share/rooms/{room_id}` (PUT antwortet zusätzlich mit `effect`), `/api/v1/matters/{id}/room-share/rooms/{room_id}` | S+R, Owner | mit dem Raum teilen (`access`: `edit` = Rechte nach Rolle, `read` = höchstens Lesen) oder die Freigabe beenden; nur in Räumen, in denen der Owner Mitglied oder Verwalter ist |
| PUT | `/api/v1/cases/{id}/room-share/people/{subject_id}`, `/api/v1/matters/{id}/room-share/people/{subject_id}` | S+R, Owner | eine Person von der Raumfreigabe ausnehmen (`excluded`) |
| POST | `/api/v1/admin/rooms/{id}/owner` | S+R, B | Betreiber setzt einen Eigentümer ein, nur wenn der bisherige nicht mehr handeln kann (Konto deaktiviert oder nicht mehr Mitglied) |
| GET | `/api/v1/rooms/overview` | S+R | Räume der Person als Kacheln: Rolle, Eigentümer, Zahl der Mitglieder und der lesbaren Akten und Vorgänge; Mitgliedernamen nur für Verwalter |
| GET | `/api/v1/rooms/{id}/contents` | S+R, Mitglied | Akten und Vorgänge, die mit dem Raum geteilt und für die Person lesbar sind, mit Zählern |
| POST | `/api/v1/rooms/{id}/shares` | S+R, Mitglied | mehrere eigene Einträge auf einmal mit dem Raum teilen (alle oder keiner); Antwort nennt die Wirkung je Mitglied |
| GET | `/api/v1/cases/{id}/outline`, `/api/v1/matters/{id}/outline` | S+R | Struktur für den Navigationsbaum: Kapitel, Unterakten und Vorgänge bzw. Teilvorgänge, nur aus Lesbarem; für Vorgänge optional `context_kind=case&context_id=` |
| GET | `/api/v1/team` | S+R, Hauptnutzer | Personen in den eigenen Räumen mit Rolle je Raum; `mine` = selbst eingeladen |
| PATCH | `/api/v1/team/{id}` | S+R, Hauptnutzer | `status` eines selbst eingeladenen Mitarbeiters; fremde und unbekannte ID: 403 |
| POST | `/api/v1/team/{id}/password-reset` | S+R, Hauptnutzer | Einmal-Passwort für einen selbst eingeladenen Mitarbeiter |
| DELETE | `/api/v1/team/{id}/memberships` | S+R, Hauptnutzer | Person aus allen eigenen Räumen entfernen |
| GET | `/api/v1/admin/team` | S+R, B | Hauptnutzer mit Mitarbeitern, Räumen und Rollen; `format=csv` für den Export |
| 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}}`.