# Tsumugu – API-Referenz (Ist-Stand) **Stand:** 18.10.2026, ergänzt am 19.10.2026 um Quelleninstanzen, Fähigkeiten und Zuordnung und am 23.10.2026 um Download-Regeln, HTML-Mail mit Bildern, Übersicht und Suche. 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 / PUT | `/api/v1/auth/download-defaults` | S+R, Hauptnutzer | Voreinstellung je Rolle und `direct` (direkt freigegebene Personen); neue Räume übernehmen die drei Rollenwerte. Audit `download_defaults_changed` | | GET / PUT | `/api/v1/auth/preferences/{key}` | S+R | Einstellung des Kontos mit Erbung. GET liefert `value` (wirksam), `source` (`locked`/`own`/`team`/`default`), `own`, `inherited`, `locked`, `allowed`, `can_lock`, `team_mode`. PUT setzt den eigenen Wert (`value`, `null` = erben) und beim Hauptnutzer die Verbindlichkeit für das Team (`team_mode` `free`/`locked`). Ein Mitarbeiter erhält bei verbindlicher Vorgabe 403. Schlüssel: `duplicate_check` (`off`/`here`/`inside`/`around`, Standard `here`). Audit `preference_changed` | | 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 / PUT | `/api/v1/rooms/{id}/download-policy` | S+R, Mitglied / E | je Rolle (`manager`, `member`, `reader`), ob das Original gespeichert oder geöffnet werden darf; `can_change` nennt, ob die Person ändern darf. Fremde und unbekannte Räume: 404. Audit `room_download_policy_changed` | | GET | `/api/v1/rooms/{id}/members` | S+R, M | Mitglieder mit Rolle und Kontostatus, `is_self` und `my_sources` (eigene Quellenfreigabe an die Person) | | PUT | `/api/v1/rooms/{id}/source-access/{subject_id}` | S+R, Mitglied oder Verwalter | `enabled`: dem Mitglied die verknüpften Originale der eigenen, mit dem Raum geteilten Einträge über die eigenen Zugänge freigeben oder entziehen (protokolliert) | | 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` mit Dateiname (UTF-8, `filename*`), `no-store`. Mit `save=true` zusätzlich das Download-Recht, sonst 403 | | POST | `/api/v1/external-refs` | externe Referenz (`paperless`, `imap`, `url`) mit `detail`. `duplicate` (`ask` Standard, `insert`): bei `ask` antwortet ein bereits vorhandenes Dokument mit 409 `already_present`, wenn nur sichere Treffer auf der Prüfstufe des Kontos zählen (Einstellung `duplicate_check`). `bind_element_id` bindet stattdessen das vorhandene Element zusätzlich in den Zielcontainer (eine Referenz, eine weitere Einbindung; Audit `external_ref_bound`). Nur ein sicherer, lesbarer Treffer im Umfeld des Ziels, mit Weitergaberecht (sonst 403 bzw. 404) | | POST | `/api/v1/external-refs/existing` | nur lesend: `context`, optional `placement`, `items` (`source`, `external_id`, `connector_id`) → je Dokument die Treffer (`element_id`, `title`, `where` `here`/`inside`/`around`, `certain`, `chapter`, `container`, `can_bind`) auf der Prüfstufe des Kontos. Nur Lesbares, ein Treffer außerhalb der Rechte gilt als nicht vorhanden | | 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, höchstens 200. Gelesen wird in Blöcken mit Rechteprüfung je Zeile (R-11 behoben) | | GET | `/api/v1/views/open-deadlines` | offene sichtbare Fristen, wie oben | | 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. Außer `q`, `connector_id`, `mailbox`, `before` und `uidvalidity` ist jeder Abfrageparameter ein Filter, den das Modul in `search_params` deklariert; unbekannte Art, nicht deklarierte oder nicht erklärte Filter und unbekannte Parameter 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=` | Paperless-Suche, 20 Treffer je Seite, `cursor` ist die Seitennummer. `mode`: `title_content` (Standard, Titel und Inhalt ohne Index), `title`, `content`, `index` (Volltextindex von Paperless). Filter: `title`, `correspondent`, `document_type`, `storage_path` (jeweils Nummer oder `none` für „ohne“), `tag` (Nummern, durch Komma) mit `tag_mode` `all` (Standard), `any` oder `none`, `document_from`/`document_to` (Dokumentdatum), `added_from`/`added_to` (Hinzugefügt), `asn`, `custom` (JSON-Liste `[{field, op, value}]`, höchstens 5, alle zugleich; `field` ist die Nummer aus `facets.custom_fields`, `op` je Feldtyp `exact`, `icontains`, `istartswith`, `iendswith`, `gt`, `gte`, `lt`, `lte`, `range` oder `exists`; Dokumentverweis-Felder sind nicht filterbar; wird als `custom_field_query` an Paperless gegeben), `sort` (`created`, `added`, `title`, jeweils mit `-`; `-score` nur bei `mode=index` mit Suchtext). Ein ungültiger Wert antwortet `422`. Je Treffer: `title`, `document_on`, `added_on`, `correspondent`, `document_type`, `storage_path`, `tags` (Namen), `pages`, `asn`, `snippet` (Textauszug, reiner Text) und `open_url`; dazu `total`, `next_page`, `previous_page` | | GET | `/api/v1/sources/{kind}/facets?connector_id=` | Auswahllisten der Instanz (Paperless: Korrespondenten, Dokumenttypen, Speicherpfade, Tags, Zusatzfelder mit Typ und Auswahlwerten). Namen und Listen werden je Instanz und Schlüssel eine Minute lang vorgehalten | | GET | `/api/v1/sources/paperless/documents/{id}/preview?connector_id=` | Datei zum Ansehen vor dem Übernehmen | | GET | `/api/v1/sources/{kind}/thumbnail?connector_id=&item=` | Vorschaubild eines Treffers, nur wenn das Modul `search.result_preview` erklärt und ein `thumbnail` bereitstellt, sonst `422`. Läuft über den Server der eigenen Instanz, `private, no-store`, nur Rastergrafiken (PNG, JPEG, WebP, GIF); fremde Instanz `404`, eine Antwort ohne Bild `422` | | 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`, mit Dateiname). Mit `save=true` zusätzlich das Download-Recht | | GET | `/api/v1/external-refs/{id}/mail` | vollständige E-Mail als JSON, Identität per Message-ID geprüft; `html` ist bereinigt, `remote_images` zählt Bilder fremder Server | | GET | `/api/v1/external-refs/{id}/mail/html-with-images` | dieselbe bereinigte Mail, die Bilder fremder Server lädt der Server auf Anforderung und liefert sie eingebettet (`loaded`, `failed`) | | GET | `/api/v1/external-refs/{id}/mail/original` | EML unter dem Betreff als Name; verlangt das Download-Recht (403 sonst) | | GET | `/api/v1/external-refs/{id}/mail/attachments/{index}` | Anlage (`inline`, siehe Review R-03); mit `save=true` das Download-Recht | | 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` oder mit einer Quellenfreigabe im Raum (`room_source_access`) 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` und mit Download-Recht am Vorgang (403 sonst); 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}}`.