API Reference

API Reference

Die vollständige interaktive API-Dokumentation ist verfügbar unter: https://<deine-domain>/api/v1/docs (Swagger UI) bzw. /api/v1/redoc (ReDoc)

Authentifizierung

Alle Endpunkte (außer /auth/register und /auth/login) erfordern entweder ein JWT im Header oder einen permanenten Service-API-Key:

Authorization: Bearer <access_token>

oder

X-API-Key: <permanenter-key>

Login

POST /api/v1/auth/login
Content-Type: application/json

{
  "username": "user@example.com",
  "password": "password"
}

Response:

{
  "access_token": "eyJ...",
  "refresh_token": "eyJ...",
  "token_type": "bearer"
}

Auth-Endpunkte

Methode	Endpoint	Beschreibung
POST	/api/v1/auth/register	Neuen User anlegen
POST	/api/v1/auth/login	Login (Access + Refresh Token)
POST	/api/v1/auth/refresh	Neuen Access-Token per Refresh-Token holen ("Angemeldet bleiben")
POST	/api/v1/auth/logout	Logout
GET	/api/v1/auth/me	Aktuellen User abrufen
PATCH	/api/v1/auth/me	Profil & Einstellungen aktualisieren
POST	/api/v1/auth/api-key	Permanenten Service-API-Key generieren (für externe Dienste, z. B. Morning Briefing)
GET	/api/v1/auth/api-key	Aktuellen API-Key anzeigen

---

Dokumente

Upload und Dokument-Erstellung passieren in einem Schritt (multipart/form-data), nicht über einen separaten /files/upload-Endpunkt.

Methode	Endpoint	Beschreibung
POST	/api/v1/documents/	Dokument hochladen (file, type, optional title) — stößt automatisch OCR + KI-Analyse als Celery-Task an
GET	/api/v1/documents/	Alle Dokumente
GET	/api/v1/documents/{id}	Einzelnes Dokument
PATCH	/api/v1/documents/{id}	Dokument aktualisieren
DELETE	/api/v1/documents/{id}	Dokument löschen

Tasks

Methode	Endpoint	Beschreibung
GET	/api/v1/tasks/	Alle Tasks
POST	/api/v1/tasks/	Task erstellen
GET	/api/v1/tasks/{id}	Einzelner Task
PATCH	/api/v1/tasks/{id}	Task aktualisieren
DELETE	/api/v1/tasks/{id}	Task löschen

Kalender & Integrationen

Methode	Endpoint	Beschreibung
GET	/api/v1/calendar/events/?start_date=...&end_date=...	Events im Zeitraum
POST	/api/v1/calendar/events/	Event erstellen
GET/PATCH/DELETE	/api/v1/calendar/events/{id}	Event lesen/ändern/löschen
POST	/api/v1/calendar/events/{id}/resolve-conflict	Sync-Konflikt auflösen
GET/POST	/api/v1/calendar/integrations/	Integrationen (Google Calendar, CalDAV, ...) auflisten/anlegen
PATCH/DELETE	/api/v1/calendar/integrations/{id}	Integration ändern/löschen
POST	/api/v1/calendar/integrations/{id}/test	Verbindung testen
POST	/api/v1/calendar/integrations/{id}/sync	Manuellen Sync anstoßen
POST	/api/v1/calendar/tasks/sync-all	Alle Tasks mit Kalender synchronisieren
POST	/api/v1/calendar/tasks/cleanup-completed	Erledigte Task-Events aufräumen
GET	/api/v1/calendar/oauth/google/authorize	Google OAuth-Flow starten
GET	/api/v1/calendar/oauth/google/callback	Google OAuth Callback

Paperless-ngx

Methode	Endpoint	Beschreibung
GET	/api/v1/paperless/status	Verbindungs-/Sync-Status
POST	/api/v1/paperless/sync	Sync manuell anstoßen
POST	/api/v1/paperless/writeback/{document_id}	Analyseergebnis (Tags, Custom Fields) zurückschreiben
GET	/api/v1/paperless/thumbnail/{paperless_id}	Thumbnail abrufen

Push Notifications

Methode	Endpoint	Beschreibung
POST	/api/v1/notifications/fcm-token	FCM-Gerätetoken registrieren
DELETE	/api/v1/notifications/fcm-token	FCM-Token entfernen (z. B. bei Logout)

Dateien

Läuft nicht unter /api/v1, sondern direkt unter /files (siehe main.py).

Methode	Endpoint	Beschreibung
GET	/files/{file_path}	Datei abrufen (Original, Thumbnail etc.)

System

Methode	Endpoint	Beschreibung
GET	/health	Health Check (JSON)
GET	/health/ui	Health Dashboard (Auto-Refresh alle 30s)

---

← Setup Guide | → Deployment