Prüfstufen hier, darin, Umfeld stehen als Kontoeinstellung bereit. Der Server antwortet bei einem sicheren Treffer mit 409 und bindet auf Wunsch das vorhandene Element zusätzlich ein. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
25 KiB
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. 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 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 |
| 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 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}}.