MindSift/Doku/api/rest.md

# 🔌 REST-API Referenz

Die MindSift REST-API ermöglicht den vollständigen Zugriff auf Gedanken, Aufgaben, Workspace-Notizen, Listen, Benutzerkonten und Smarthome-Automationen.

---

## 🔐 1. Authentifizierung

MindSift unterstützt zwei Authentifizierungsmethoden:

1. **JSON Web Token (JWT Bearer):**  
   Wird beim Login oder Setup erzeugt und im HTTP-Header mitgesendet:  
   `Authorization: Bearer <jwt-token>`
2. **Persönliche API-Schlüssel (Smarthome / Automatisierung):**  
   Werden unter *Einstellungen ➔ Private Webhooks* erzeugt (Präfix `mindsift_sec_...`):  
   - Per HTTP-Header: `X-API-Key: mindsift_sec_xxxxxxxxxxxx`
   - Per Authorization-Header: `Authorization: Bearer mindsift_sec_xxxxxxxxxxxx`
   - Per Query-Parameter: `?token=mindsift_sec_xxxxxxxxxxxx`

---

## 🚦 2. Status- & Fehler-Codes

- `200 OK`: Erfolgreiche Abfrage oder Aktualisierung.
- `201 Created`: Ressource erfolgreich angelegt.
- `400 Bad Request`: Ungültiges JSON oder fehlende Pflichtfelder.
- `401 Unauthorized`: Token ungültig, abgelaufen oder fehlend.
- `403 Forbidden`: Unzureichende Berechtigungen (z.B. nur Server-Admin oder nur Lesezugriff).
- `404 Not Found`: Ressource existiert nicht oder gehört einem anderen Benutzer.
- `409 Conflict`: Ressource gesperrt (z.B. Dokument wird bereits von anderem Benutzer bearbeitet).

Fehlerrückgaben erfolgen im einheitlichen Format:
```json
{
  "error": "Fehlermeldung im Klartext"
}
```

---

## 📋 3. Endpunkte nach Modulen

### 3.1 Authentifizierung & System-Status

| Methode | Pfad | Auth | Beschreibung |
| :--- | :--- | :--- | :--- |
| `GET` | `/api/v1/health` | Öffentlich | Liveness-Check (`{"status":"ok"}`) |
| `GET` | `/api/v1/auth/status` | Öffentlich | Prüft ob Ersteinrichtung nötig ist (`needsSetup: true/false`) |
| `POST` | `/api/v1/auth/setup` | Öffentlich | Führt First-Boot Setup durch (legt ersten Admin an) |
| `POST` | `/api/v1/auth/register` | Öffentlich | Registrierung über Einladungscode (`inviteCode`) |
| `POST` | `/api/v1/auth/login` | Öffentlich | Login via E-Mail oder Benutzername + Passwort |
| `GET` | `/api/v1/auth/me` | JWT | Gibt das aktuelle Benutzerprofil zurück |
| `PATCH` | `/api/v1/auth/settings` | JWT | Aktualisiert Profil, Passwort, Theme oder Alarm-Kanäle |
| `POST` | `/api/v1/auth/alarms/test` | JWT | Sendet Test-Alarm an E-Mail, Discord oder Custom Webhook |

#### Beispiel: `POST /api/v1/auth/login`
```json
// Request
{
  "login": "sandro",
  "password": "geheimesPasswort123"
}

// Response (200 OK)
{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "usr_abc123",
    "email": "sandro@example.com",
    "username": "sandro",
    "displayName": "Sandro",
    "role": "admin",
    "alarmChannels": ["discord", "webhook"]
  }
}
```

---

### 3.2 Triage & Instant Capture

| Methode | Pfad | Auth | Beschreibung |
| :--- | :--- | :--- | :--- |
| `POST` | `/api/v1/inbox` | JWT / API-Key | Erfasst einen neuen Quick Dump oder leitet direkt weiter |
| `GET` | `/api/v1/triage/deck` | JWT | Liefert den Stapel aller noch nicht triagierten Gedanken (`status: 'inbox'`) |
| `PATCH` | `/api/v1/triage/{id}` | JWT | Führt Triage-Aktion aus (`keep`, `discard`, `restore`) |

#### Beispiel: `POST /api/v1/inbox`
Ermöglicht flexible Direkt-Zuordnungen:
```json
// Request (Quick Dump in Triage-Deck)
{
  "content": "Kellerfeuchtigkeit über 68% gestiegen #smarthome #alarm",
  "priority": "urgent"
}

// Request (Direkt als Aufgabe anlegen)
{
  "content": "Server Backup prüfen #devops",
  "priority": "high",
  "target": "task",
  "dueDate": "2026-10-30"
}
```
*Hinweis:* Wenn `/api/v1/inbox` über einen API-Key aufgerufen wird und kein `source` definiert ist, wird die Quelle automatisch als `"webhook"` markiert!

---

### 3.3 Aufgaben & Kanban-System

| Methode | Pfad | Auth | Beschreibung |
| :--- | :--- | :--- | :--- |
| `GET` | `/api/v1/tasks` | JWT | Liefert alle Aufgaben des Benutzers (inkl. geteilter Aufgaben) |
| `POST` | `/api/v1/tasks/reorder` | JWT | Speichert Kanban-Status und Reihenfolge (`sort_order`) |
| `GET` | `/api/v1/task-lists` | JWT | Liefert alle Aufgabenlisten (eigene & geteilte) |
| `POST` | `/api/v1/task-lists` | JWT | Erstellt eine neue Aufgabenliste (mit Farbe & Spalten) |
| `PUT` | `/api/v1/task-lists/{id}` | JWT | Ändert Titel, Farbe, Icon oder Kanban-Spalten |
| `DELETE` | `/api/v1/task-lists/{id}` | JWT | Löscht Aufgabenliste |
| `POST` | `/api/v1/task-lists/{id}/shares` | JWT | Teilt Liste mit Team oder Benutzer |

---

### 3.4 Workspace & Dokumente

| Methode | Pfad | Auth | Beschreibung |
| :--- | :--- | :--- | :--- |
| `GET` | `/api/v1/documents` | JWT | Liefert Liste aller Dokumente des Benutzers (Metadaten) |
| `POST` | `/api/v1/documents` | JWT | Erstellt neues Notiz-Dokument (mit Blocks oder Markdown) |
| `GET` | `/api/v1/documents/{id}` | JWT | Lädt komplettes Dokument inklusive aller Blöcke |
| `PUT` | `/api/v1/documents/{id}` | JWT | Aktualisiert Dokumenttitel, Icon oder Ordnerpfad |
| `PATCH` | `/api/v1/documents/{id}/blocks` | JWT | Granulares Patching von Dokument-Blöcken (Database-First) |
| `DELETE` | `/api/v1/documents/{id}` | JWT | Löscht Dokument (Datenbank & physische Datei) |
| `POST` | `/api/v1/documents/{id}/shares` | JWT | Notiz mit anderem Benutzer teilen (`read` / `write`) |
| `GET` | `/api/v1/documents/{id}/lock` | JWT | Fragt Bearbeitungs-Sperrstatus ab |
| `POST` | `/api/v1/documents/{id}/lock` | JWT | Sperrt Dokument für Bearbeitung (30s Lease) |
| `DELETE` | `/api/v1/documents/{id}/lock` | JWT | Gibt Bearbeitungssperre wieder frei |

---

### 3.5 Workspace Ordner & Geteilte Ordner

| Methode | Pfad | Auth | Beschreibung |
| :--- | :--- | :--- | :--- |
| `GET` | `/api/v1/folders` | JWT | Liefert alle Ordnerpfade des Benutzers |
| `POST` | `/api/v1/folders` | JWT | Legt neuen (auch leeren) Ordner an |
| `POST` | `/api/v1/folders/move` | JWT | Benennt Ordner um oder verschiebt ihn hierarchisch |
| `DELETE` | `/api/v1/folders` | JWT | Löscht Ordner und verschiebt Notizen |
| `GET` | `/api/v1/workspace/folders/shared` | JWT | Liefert für den Benutzer freigegebene geteilte Ordner |
| `POST` | `/api/v1/workspace/folders/shared` | JWT | Erstellt neuen geteilten Ordner |
| `PUT` | `/api/v1/workspace/folders/shared/{id}/mount` | JWT | Ändert den lokalen Einhängepfad beim Empfänger |
| `POST` | `/api/v1/workspace/folders/shared/{id}/shares` | JWT | Gibt Ordner für Teams oder Benutzer frei |

---

### 3.6 Geteilte Listen (Listen & Einkauf)

| Methode | Pfad | Auth | Beschreibung |
| :--- | :--- | :--- | :--- |
| `GET` | `/api/v1/lists` | JWT | Liefert alle geteilten Listen |
| `POST` | `/api/v1/lists` | JWT | Erstellt neue geteilte Liste |
| `GET` | `/api/v1/lists/{id}` | JWT | Lädt Liste inklusive aller Einträge |
| `POST` | `/api/v1/lists/{id}/items` | JWT | Fügt Eintrag hinzu |
| `PATCH` | `/api/v1/lists/{id}/items/{itemId}` | JWT | Hakt Eintrag ab (`isCompleted: true/false`) |
| `POST` | `/api/v1/lists/{id}/items/reorder` | JWT | Speichert sortierte Einträge |
| `POST` | `/api/v1/lists/{id}/clear-completed`| JWT | Löscht alle abgehakten Einträge |
| `POST` | `/api/v1/lists/{id}/shares` | JWT | Teilt Liste mit Team oder Benutzer |

---

### 3.7 Smarthome Ingestion & Externe Webhooks

| Methode | Pfad | Auth | Beschreibung |
| :--- | :--- | :--- | :--- |
| `POST` | `/api/v1/webhooks/ingest` | Token / Key | Empfängt externe Webhook-Payloads von Home Assistant / n8n |

#### Beispiel: `POST /api/v1/webhooks/ingest?token=mindsift_sec_...`
Unterstützt flexible Payloads (JSON oder Plain Text):
```json
{
  "title": "Waschmaschine Keller fertig",
  "priority": "high",
  "tags": ["smarthome", "keller"]
}
```
*Live-Aktualisierung:* Sendet automatisch ein `TASK_CREATED` WebSocket-Event an alle Clients des Benutzers, sodass die neue Karte sofort ohne Neuladen im Triage-Deck erscheint!