Die Raumfreigabe allein gab die Zugänge des Owners nicht weiter. Ein Leser im Raum sah die Akte, aber kein Original. Neu ist room_source_access: Wer im Raum teilen darf, schaltet für ein Mitglied „Originale über meine Zugänge“ ein. Das gilt für alle eigenen, mit dem Raum geteilten Einträge. Ausnahmen, Ende der Raumfreigabe und Verlassen des Raums schließen den Abruf. Beschluss R-01 ist entsprechend ergänzt. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
26 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, 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}}.