Lokaler API-Server

Mindwtr enthält einen optionalen lokalen REST-API-Server für Skripte und Integrationen. Auf dem Desktop läuft er innerhalb der App-Binärdatei und verwendet dieselben lokalen Speicherpfade wie die App. Das Repository enthält außerdem ein Bun-Hilfsprogramm für Entwicklung und fortgeschrittenes Skripting.

---

Desktop-Schalter

Desktop-Builds können die lokale REST-API starten, ohne Quellcode auszuführen:

• Öffnen Sie Einstellungen → Erweitert.
• Aktivieren Sie Lokaler API-Server.
• Behalten Sie den Standardport 3456 bei oder wählen Sie einen anderen localhost-Port.
• Kopieren Sie das erzeugte Bearer-Token von derselben Einstellungskarte.

Die App bindet sich ausschließlich an 127.0.0.1 und verlangt bei jeder Anfrage Authorization: Bearer <token>. Binärdateien für Mobilgeräte stellen keine lokale REST-API bereit.

Hilfsprogramm für die Entwicklung

Das Hilfsprogramm des Repositorys steht weiterhin zur Verfügung, wenn Sie die API außerhalb der Desktop-App ausführen oder ausdrücklich bestimmte Dateien verwenden möchten.

---

Schnellstart

Aus der Desktop-App:

Settings -> Advanced -> Enable local API server

Standard-URL:

http://127.0.0.1:3456

Aus dem Stammverzeichnis des Repositorys mit Bun:

bun install
bun run mindwtr:api -- --port 4317 --host 127.0.0.1

Optionen

Option	Standard	Beschreibung
--port <n>	4317	Serverport
--host <host>	127.0.0.1	Bindungsadresse
--data <path>	Plattformstandard	Speicherort von data.json überschreiben
--db <path>	Plattformstandard	Speicherort von mindwtr.db überschreiben

Umgebungsvariablen

Variable	Beschreibung
MINDWTR_DATA	Speicherort von data.json überschreiben (wenn --data fehlt)
MINDWTR_DB_PATH	Speicherort von mindwtr.db überschreiben (wenn --db fehlt)
MINDWTR_API_TOKEN	Nur Bun-Hilfsprogramm: falls gesetzt, Authorization: Bearer <token> verlangen

Standardmäßig ermittelt die API sowohl data.json als auch mindwtr.db anhand der Plattformpfade von Mindwtr (unter Linux bevorzugt im XDG-Datenverzeichnis).

---

Authentifizierung

Anfragen an die lokale Desktop-API benötigen immer das Bearer-Token, das unter Einstellungen → Erweitert angezeigt wird:

Authorization: Bearer <token>

Das Bun-Hilfsprogramm verlangt nur dann ein Token, wenn MINDWTR_API_TOKEN gesetzt ist.

---

Endpunkte

Methode	Endpunkt	Beschreibung
GET	/health	Zustandsprüfung → { ok: true }
GET	/tasks	Aufgaben auflisten
GET	/tasks?status=next	Nach Status filtern
GET	/tasks?query=@work	Aufgaben suchen
GET	/tasks?isFocusedToday=true	Desktop: Nach „Heutiger Fokus“ filtern
GET	/tasks?all=1	Erledigte/archivierte einschließen
GET	/tasks?deleted=1	Vorläufig gelöschte einschließen
POST	/tasks	Aufgabe erstellen
GET	/tasks/:id	Einzelne Aufgabe abrufen
PATCH	/tasks/:id	Aufgabe aktualisieren
DELETE	/tasks/:id	Aufgabe vorläufig löschen
POST	/tasks/:id/complete	Als erledigt markieren
POST	/tasks/:id/archive	Als archiviert markieren
POST	/tasks/:id/restore	Vorläufig gelöschte Aufgabe wiederherstellen
GET	/projects	Projekte auflisten
GET	/areas	Bereiche auflisten
GET	/v1/areas	Kompatibilitätsalias für Bereiche
GET	/search?query=...	Aufgaben und Projekte suchen

Die lokale Desktop-API akzeptiert isFocusedToday=true/1 und isFocusedToday=false/0. Mit true oder 1 liefert sie Aufgaben im Heutigen Fokus. Mit false oder 0 liefert sie nicht markierte Aufgaben, einschließlich älterer Datensätze ohne dieses Feld. Ohne den Parameter filtert sie die Liste nicht nach diesem Feld. Bei anderen Werten antwortet sie mit 400.

query ist hier eine reine Textsuche: Der Wert wird in Kleinbuchstaben umgewandelt und als Teilzeichenfolge gegen Titel, Beschreibung, Status, Tags, Kontexte, Projekt- und Bereichs-IDs sowie Support-Notizen der Aufgabe geprüft. Es ist nicht die Operatorsprache. status:, context:, tag:, due:<=7d, Ausdrücke in Anführungszeichen und -Negation gehören zum Suchfeld der App, zu --query der CLI und zur Aufgabenliste des MCP-Servers; hier gesendet werden sie als wörtliche Zeichen verglichen und liefern meist nichts.

Antwortstrukturen

Aufgabe (Auszug)

{
  "id": "uuid",
  "title": "Task title",
  "status": "inbox",
  "projectId": "uuid",
  "dueDate": "2026-01-25T12:00:00.000Z",
  "tags": ["#work"],
  "contexts": ["@email"],
  "createdAt": "2026-01-25T10:00:00.000Z",
  "updatedAt": "2026-01-25T10:00:00.000Z",
  "deletedAt": null
}

Projekt (Auszug)

{
  "id": "uuid",
  "title": "Project name",
  "status": "active",
  "color": "#94a3b8",
  "createdAt": "2026-01-25T10:00:00.000Z",
  "updatedAt": "2026-01-25T10:00:00.000Z",
  "deletedAt": null
}

Bereich

{
  "id": "uuid",
  "name": "Area name",
  "color": "#94a3b8",
  "icon": "briefcase",
  "order": 0,
  "createdAt": "2026-01-25T10:00:00.000Z",
  "updatedAt": "2026-01-25T10:00:00.000Z"
}

Body zum Erstellen einer Aufgabe

{
  "input": "Call Alice",
  "title": "Alternative title",
  "props": {
    "status": "next",
    "contexts": ["@phone"],
    "tags": ["#errands"]
  }
}

Desktop verwendet title, wenn vorhanden, andernfalls input, und wendet ausdrückliche props an. Das Bun-Hilfsprogramm führt zusätzlich parseQuickAdd für input aus.

---

Beispiele

Nächste Aktionen auflisten:

curl -s 'http://127.0.0.1:3456/tasks?status=next' \
  -H 'Authorization: Bearer <token>' | jq .

Mit ausdrücklichen Eigenschaften erstellen:

curl -s -X POST 'http://127.0.0.1:3456/tasks' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"title":"Call Alice","props":{"status":"next","contexts":["@phone"],"tags":["#errands"]}}' | jq .

Eine Aufgabe erledigen:

curl -s -X POST "http://127.0.0.1:3456/tasks/$TASK_ID/complete" \
  -H 'Authorization: Bearer <token>' | jq .

---

CLI-Werkzeug

Außerdem steht eine einfachere Befehlszeilenschnittstelle zur Verfügung:

# Add a task
bun mindwtr:cli -- add "Call mom @phone #family"

# List active tasks
bun mindwtr:cli -- list

# List with filters
bun mindwtr:cli -- list --status next --query "due:<=7d"

# Read or update a task
bun mindwtr:cli -- get <taskId>
bun mindwtr:cli -- update <taskId> '{"status":"next"}'

# Complete a task
bun mindwtr:cli -- complete <taskId>

# Archive, delete, or restore
bun mindwtr:cli -- archive <taskId>
bun mindwtr:cli -- delete <taskId>
bun mindwtr:cli -- restore <taskId>

# Search
bun mindwtr:cli -- search "@work"

# List projects
bun mindwtr:cli -- projects

CLI-Referenz

Befehl	Beispiel	Hinweise
add	mindwtr:cli -- add "Call mom @phone"	Verwendet die Schnelleingabeauswertung
list	mindwtr:cli -- list --status next	Unterstützt --all, --deleted, --query
get	mindwtr:cli -- get <taskId>	Gibt das vollständige Aufgaben-JSON aus
update	mindwtr:cli -- update <taskId> '{"status":"next"}'	Wendet einen JSON-Patch an
search	mindwtr:cli -- search "@work due:<=7d"	Durchsucht Aufgaben/Projekte
complete	mindwtr:cli -- complete <taskId>	Markiert die Aufgabe als erledigt
archive	mindwtr:cli -- archive <taskId>	Markiert die Aufgabe als archiviert
delete	mindwtr:cli -- delete <taskId>	Löscht die Aufgabe vorläufig
restore	mindwtr:cli -- restore <taskId>	Stellt eine gelöschte Aufgabe wieder her
projects	mindwtr:cli -- projects	Listet aktive Projekte auf

---

Sicherheitshinweise

• Der Server ist für den Betrieb auf 127.0.0.1 (localhost) vorgesehen. Stellen Sie ihn nur dann öffentlich bereit, wenn Sie die Risiken verstehen.
• Der Zugriff auf die Desktop-API erfordert das unter Einstellungen erzeugte Bearer-Token. Halten Sie dieses Token geheim.
• Wenn Sie Remotezugriff auf das Bun-Hilfsprogramm benötigen, setzen Sie MINDWTR_API_TOKEN und platzieren Sie den Server hinter einem authentifizierten Reverse Proxy.

---

Siehe auch

• Entwicklerhandbuch
• Cloud-API