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:

text

Settings -> Advanced -> Enable local API server

Standard-URL:

text

http://127.0.0.1:3456

Aus dem Stammverzeichnis des Repositorys mit Bun:

bash

bun install
MINDWTR_API_TOKEN=replace-with-a-strong-token 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
`--dangerously-disable-auth`	aus	Ganz ohne Token starten — unsicher und selbst auf Loopback nicht browsersicher

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`	Erforderlich. Bearer-Token, das das Hilfsprogramm bei jeder Anfrage verlangt; ohne Token startet es nicht, außer `--dangerously-disable-auth` wird übergeben
`MINDWTR_API_CORS_ORIGIN`	Optional. Genau ein http(s)-Origin, das die API aufrufen darf; ohne Wert werden keine CORS-Header gesendet

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>

Auch das Bun-Hilfsprogramm verlangt ein Token: Es beendet sich sofort, wenn MINDWTR_API_TOKEN nicht gesetzt ist — es sei denn, Sie übergeben ausdrücklich --dangerously-disable-auth (nur für isolierte Kompatibilitätstests gedacht).

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: Markierte Aufgaben einschließlich vorgemerkter Starts 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
`POST`	`/projects`	Desktop: Projekt erstellen
`GET`	`/projects/:id`	Desktop: Einzelnes Projekt abrufen
`PATCH`	`/projects/:id`	Desktop: Projekt aktualisieren
`DELETE`	`/projects/:id`	Desktop: Projekt vorläufig löschen
`POST`	`/projects/:id/restore`	Desktop: Projekt wiederherstellen
`GET`	`/areas`	Bereiche auflisten
`GET`	`/areas/:id`	Desktop: einzelnen Bereich lesen
`PATCH`	`/areas/:id`	Desktop: Bereich bearbeiten
`GET`	`/v1/areas`	Kompatibilitätsalias für Bereiche
`GET`	`/sections`	Hilfsprogramm: Abschnitte auflisten, optional `?projectId=`
`POST`	`/sections`	Hilfsprogramm: Abschnitt erstellen
`GET`	`/sections/:id`	Hilfsprogramm: Einzelnen Abschnitt abrufen
`PATCH`	`/sections/:id`	Hilfsprogramm: Abschnitt aktualisieren
`DELETE`	`/sections/:id`	Hilfsprogramm: Abschnitt löschen
`GET`	`/search?query=...`	Aufgaben und Projekte suchen

Die Desktop-Local-API liefert 409 (recurrence_requires_app), wenn beim Abschließen einer Aufgabe mit festem Zeitplan, Startdatum und ohne Fälligkeitsdatum verpasste Wiederholungen übersprungen werden müssten. Die Aufgabe bleibt unverändert; schließe sie in der App ab. Aufgaben nur mit Startdatum werden weiterhin unterstützt, wenn ihre nächste Wiederholung noch aktuell ist oder in der Zukunft liegt.

Zeilen mit Desktop gibt es nur in der lokalen API der Desktop-App. Zeilen mit Hilfsprogramm gibt es nur im Bun-Hilfsprogramm, das sie auch unter dem Präfix /v1/ beantwortet (/v1/sections).

Die lokale Desktop-API akzeptiert isFocusedToday=true/1 und isFocusedToday=false/0. Mit true oder 1 liefert sie markierte Aufgaben, einschließlich nächster Aktionen mit zukünftigem Start, die für den Fokus vorgemerkt sind. 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)

json

{
  "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)

json

{
  "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

json

{
  "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

json

{
  "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.

Projekte über die Desktop-API schreiben

Die integrierte Desktop-API unterstützt das Erstellen, Abrufen, Aktualisieren, vorläufige Löschen und Wiederherstellen von Projekten. Zum Erstellen ist title erforderlich; areaId, color, status, isSequential und order sind optional. Aktualisierungen akzeptieren dieselben bearbeitbaren Felder. Erstellen, Abrufen, Aktualisieren und Wiederherstellen liefern das gespeicherte Projekt als { "project": { ... } }; Löschen liefert { "ok": true }.

Sende Erstellungsoptionen in props, zum Beispiel { "title": "Plan the move", "props": { "isSequential": true } }; PATCH-Felder stehen direkt im Anfragekörper. sequentialScope akzeptiert project oder section. Der Projektstatus status akzeptiert active, someday, waiting oder archived. Mit areaId: null entfernst du den Bereich. Archivieren und Reaktivieren folgen den Regeln der App für untergeordnete Aufgaben und Abschnitte. Bei PATCH liefern fehlende Projekte 404, gelöschte oder endgültig entfernte Projekte 409.

GET /projects/:id liefert auch ein gespeichertes vorläufig gelöschtes Projekt, damit ein Skript es vor der Wiederherstellung prüfen kann. DELETE /projects/:id löscht das Projekt und seine aktiven Abschnitte vorläufig und trennt aktive Aufgaben vom Projekt, statt sie zu löschen oder ihren Status zu ändern. POST /projects/:id/restore stellt das Projekt und untergeordnete Einträge wieder her, die durch dieselbe ältere Kaskade gelöscht wurden, verknüpft aber keine durch einen aktuellen Löschvorgang getrennten Aufgaben neu. Wiederholtes Löschen oder Wiederherstellen ist sicher und ändert den aktuellen Zustand nicht. Lebenszyklusänderungen an einem endgültig entfernten Projekt liefern 409.

Ein sequenzielles Projekt erstellen:

bash

curl -s -X POST "http://127.0.0.1:3456/projects" \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"title":"Plan the move","props":{"isSequential":true}}' | jq .

Ein vorhandenes Projekt auf parallel umstellen:

bash

curl -s -X PATCH "http://127.0.0.1:3456/projects/$PROJECT_ID" \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"isSequential":false}' | jq .

Bereiche auf dem Desktop bearbeiten

GET /areas/:id und PATCH /areas/:id geben { "area": { ... } } zurück. Unbekannte oder gelöschte Bereiche führen bei beiden zu 404. Diese Endpunkte gehören zur integrierten Desktop-API, nicht zum Bun-Helfer.

PATCH akzeptiert ein nicht leeres Objekt mit ausschließlich name, color, icon und order. name muss eine nicht leere Zeichenfolge sein; äußere Leerzeichen werden entfernt. color und icon akzeptieren Zeichenfolgen oder null zum Entfernen des Felds. order muss eine endliche Zahl sein; negative Werte und Bruchzahlen sind erlaubt. Unbekannte Felder, ungültige Typen, leere Namen und ein leeres Patch-Objekt ergeben 400.

Entspricht der Name nach dem Entfernen äußerer Leerzeichen und ohne Beachtung der Groß-/Kleinschreibung einem anderen aktiven Bereich, folgt 409 ohne Änderungen. Die API führt Bereiche niemals automatisch zusammen. Umbenennungen und Farbänderungen erhalten das Verhalten der App für Metadaten zugehöriger Projekte und werden gemeinsam gespeichert. Das Entfernen der Bereichsfarbe setzt auch die Farbe zugehöriger Projekte auf den Standardwert (#94a3b8) zurück. order ändert die numerische Position dieses Bereichs; es ist keine gemeinsame Neuordnung mehrerer Bereiche. Erstellung und Löschung von Bereichen sind nicht enthalten.

bash

curl -s -X PATCH "http://127.0.0.1:3456/areas/$AREA_ID" \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Work","color":"#94a3b8","order":2}' | jq .

Aufgaben über die Desktop-API einordnen

Mit PATCH /tasks/:id und status kannst du eine aktive Aufgabe zwischen inbox, next, waiting, someday und reference verschieben. Für Abschließen, Archivieren und Wiederherstellen bleiben die eigenen Aktionen /complete, /archive und /restore zuständig. Endstatuswerte werden von PATCH nicht akzeptiert.

PATCH kann abgeschlossene oder archivierte Aufgaben nicht erneut öffnen (409); öffne sie zuerst in der App erneut. Stelle eine gelöschte Aufgabe vor dem Einordnen mit /restore wieder her. Endgültig entfernte Aufgaben können nicht eingeordnet werden.

Das Verschieben einer Aufgabe in inbox, next, waiting oder someday innerhalb eines archivierten Projekts liefert 409. Reaktiviere zuerst das Projekt mit PATCH /projects/:id und {"status":"active"}, oder verschiebe die Aufgabe im selben Aufgaben-PATCH aus diesem Projekt.

Eine Eingang-Aufgabe zu den nächsten Aktionen verschieben:

bash

curl -s -X PATCH "http://127.0.0.1:3456/tasks/$TASK_ID" \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"status":"next"}' | jq .

Beispiele

Nächste Aktionen auflisten:

bash

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

Mit ausdrücklichen Eigenschaften erstellen:

bash

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:

bash

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:

bash

# 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.

Lokaler API-Server ​

Desktop-Schalter ​

Hilfsprogramm für die Entwicklung ​

Schnellstart ​

Optionen ​

Umgebungsvariablen ​

Authentifizierung ​

Endpunkte ​

Antwortstrukturen ​

Body zum Erstellen einer Aufgabe ​

Projekte über die Desktop-API schreiben ​

Bereiche auf dem Desktop bearbeiten ​

Aufgaben über die Desktop-API einordnen ​

Beispiele ​

CLI-Werkzeug ​

CLI-Referenz ​

Sicherheitshinweise ​

Siehe auch ​

Lokaler API-Server

Desktop-Schalter

Hilfsprogramm für die Entwicklung

Schnellstart

Optionen

Umgebungsvariablen

Authentifizierung

Endpunkte

Antwortstrukturen

Body zum Erstellen einer Aufgabe

Projekte über die Desktop-API schreiben

Bereiche auf dem Desktop bearbeiten

Aufgaben über die Desktop-API einordnen

Beispiele

CLI-Werkzeug

CLI-Referenz

Sicherheitshinweise

Siehe auch