# TaskFlow API Reference

**Base URL:** `https://task.nothaft.cloud`  
**Stand:** 2026-02-03

---

## Authentifizierung

Zwei Methoden:

### 1. Session Cookie (Browser)
Standard Login über `/api/login` mit Username/Password.

### 2. API Key (Externe Tools / Bots)
Für automatisierte Zugriffe. Key wird über die GUI oder API generiert.

**Übergabe:**
```
X-API-Key: tf_abc123...
# oder
Authorization: Bearer tf_abc123...
# oder
?apiKey=tf_abc123...
```

### API Key generieren
```bash
# Generieren (eingeloggt via Session)
POST /api/user/api-key
→ { "apiKey": "tf_...", "message": "Save this key..." }

# Status prüfen
GET /api/user/api-key
→ { "hasKey": true, "maskedKey": "tf_abc12...xyz9" }

# Widerrufen
DELETE /api/user/api-key
```

---

## REST Endpoints

### Health
```
GET /api/health
→ { "status": "ok", "timestamp": "..." }
```

### Tasks

```bash
# Alle Tasks
GET /api/tasks
→ [{ id, title, status, priority, dueDate, ... }]

# Einzelner Task
GET /api/tasks/:id

# Task erstellen
POST /api/tasks
{ "title": "...", "priority": "high", "dueDate": "2026-02-05", "labelId": "..." }

# Task updaten
PATCH /api/tasks/:id
{ "status": "done", "priority": "low" }

# Task löschen
DELETE /api/tasks/:id
```

### Labels

```bash
GET /api/labels
POST /api/labels { "name": "Work", "color": "#ff5733" }
PATCH /api/labels/:id
DELETE /api/labels/:id
```

### User

```bash
GET /api/user                    # Eigenes Profil + Stats
GET /api/user/api-key            # API Key Status
POST /api/user/api-key           # API Key generieren
DELETE /api/user/api-key         # API Key widerrufen
PATCH /api/user/profile          # E-Mail ändern
PATCH /api/user/password         # Passwort ändern
PATCH /api/user/schedule         # Arbeitszeiten
PATCH /api/user/privacy          # Privatsphäre-Einstellungen
```

### Gamification

```bash
GET /api/user/history            # XP-Verlauf
GET /api/user/inventory          # Erworbene Rewards
GET /api/leaderboard             # Bestenliste
GET /api/rewards                 # Verfügbare Rewards
POST /api/rewards/purchase       # Reward kaufen
```

### Analytics

```bash
GET /api/analytics/weekly
GET /api/analytics/monthly
GET /api/analytics/yearly
GET /api/analytics/time-distribution?period=week
```

### AI Chat

```bash
GET /api/ai/status               # AI konfiguriert?
GET /api/ai/conversations        # Alle Gespräche
POST /api/ai/conversations       # Neues Gespräch
POST /api/ai/chat                # Nachricht senden
```

---

## MCP (Model Context Protocol)

Für AI-Tool-Integration (Claude, etc.)

```
GET  /api/mcp/sse               # SSE Stream (mit API Key)
POST /api/mcp/messages           # JSON-RPC Nachrichten
```

### Verfügbare MCP Tools

| Tool | Beschreibung |
|---|---|
| `list_tasks` | Tasks auflisten (Filter: status, priority, labelId) |
| `get_task` | Einzelnen Task laden |
| `search_tasks` | Tasks durchsuchen |
| `create_task` | Task erstellen |
| `update_task` | Task aktualisieren |
| `complete_task` | Task als erledigt markieren |
| `delete_task` | Task löschen |
| `list_labels` | Labels auflisten |
| `create_label` | Label erstellen |
| `get_user_stats` | User-Statistiken |
| `get_dashboard` | Dashboard-Übersicht |
| `bulk_create_tasks` | Mehrere Tasks auf einmal erstellen |
| `bulk_update_tasks` | Mehrere Tasks auf einmal updaten |

### Beispiel: Task per API Key erstellen

```bash
curl -X POST https://task.nothaft.cloud/api/tasks \
  -H "Content-Type: application/json" \
  -H "X-API-Key: tf_your_key_here" \
  -d '{"title": "Report schreiben", "priority": "high", "dueDate": "2026-02-10"}'
```

---

## NotiBot Integration

NotiBot nutzt die REST API mit API Key um Tasks für Paul zu verwalten.

### Konfiguration
- API Key in NotiBot Memory gespeichert
- Zugriff via `web_fetch` auf `https://task.nothaft.cloud/api/*`
- Audit-Logs zeigen `source: "API"` für Bot-Aktionen

### Was NotiBot kann
- Tasks erstellen, updaten, abschließen, löschen
- Labels verwalten
- Dashboard/Stats abrufen
- Bulk-Operationen
- Erinnerungen basierend auf Due-Dates

---

*Letzte Aktualisierung: 2026-02-03*