Cloud-API

Mindwtr Cloud stellt eine kleine Bearer-Token-API für Synchronisierung, Aufgabenautomatisierung und Anhangsübertragung bereit. Sie ist für selbst gehostete Bereitstellungen ausgelegt und verwendet denselben Token-Namensraum wie das selbst gehostete Cloud-Backend.

Interaktives Diagramm öffnen

Authentifizierung

Senden Sie bei jeder /v1/*-Anfrage ein Bearer-Token:

Authorization: Bearer <token>

Verwenden Sie in der Produktion MINDWTR_CLOUD_AUTH_TOKENS oder MINDWTR_CLOUD_AUTH_TOKENS_FILE. MINDWTR_CLOUD_ALLOW_ANY_TOKEN=true ist nur für kontrollierte Automatisierung vorgesehen und begrenzt neue Namensräume mit MINDWTR_CLOUD_ANY_TOKEN_MAX_NAMESPACES.

Systemzustand

GET /health

Gibt den Zustand des Servers ohne Authentifizierung zurück.

Snapshot-Synchronisierung

GET /v1/data
PUT /v1/data

GET /v1/data gibt den Snapshot des authentifizierten Namensraums zurück. Wenn der Namensraum nicht vorhanden ist und Schreibvorgänge zulässig sind, erstellt der Server einen leeren Snapshot.

PUT /v1/data validiert die hochgeladenen AppData, führt sie mithilfe des Core-Synchronisierungsalgorithmus mit dem vorhandenen Namensraum zusammen, validiert das zusammengeführte Ergebnis und schreibt es zurück. Dies ist kein erzwungenes Überschreiben. Eine erfolgreiche Antwort gibt { ok: true, stats, clockSkewWarning } zurück, wobei stats dieselbe Form der Zusammenführungsstatistik hat, die von der lokalen Synchronisierungsdiagnose verwendet wird. Der Upload darf bis zu MINDWTR_CLOUD_MAX_DATA_BODY_BYTES groß sein (Standard 50 MB); ein größerer erhält 413 mit { error, limitBytes }.

Aufgaben

GET /v1/tasks
POST /v1/tasks
GET /v1/tasks/:id
PATCH /v1/tasks/:id
DELETE /v1/tasks/:id
POST /v1/tasks/:id/complete
POST /v1/tasks/:id/archive

Abfrageparameter für Listen:

Parameter	Zweck
query	Textsuche ohne Beachtung der Groß-/Kleinschreibung in Aufgabentitel und Metadaten.
status	Ein Aufgabenstatus: inbox, next, waiting, someday, reference, done oder archived.
all=1	Erledigte Aufgaben einbeziehen.
deleted=1	Vorläufig gelöschte Aufgaben einbeziehen.
isFocusedToday	true/1 liefert markierte Aufgaben, einschließlich nächster Aktionen mit zukünftigem Start, die für den Fokus vorgemerkt sind; false/0 liefert die übrigen. Weglassen bedeutet kein Filter.
limit, offset	Seitengröße und Startversatz.

Beim Erstellen werden entweder title oder die Schnelleingabe input sowie optional props akzeptiert. Patch akzeptiert Aufgabenfelder, die von der Cloud-Validierungsschicht unterstützt werden, und erhöht die Metadaten der Synchronisierungsrevision.

Beim Erstellen akzeptiert props diese Aufgabenfelder: status, projectId, sectionId, areaId, description, priority, dueDate, startTime, relativeStartOffset, reviewAt, recurrence, showFutureRecurrence, contexts, tags, checklist, attachments, assignedTo, location, energyLevel, timeEstimate, timeSpentMinutes, taskMode, textDirection, isFocusedToday, pushCount, repeatReminderMinutes, suppressMindwtrReminders und viewSectionIds. title ist ein Feld auf oberster Ebene, kein Prop. Patch akzeptiert dieselben Felder sowie title, order, orderNum, boardOrder und focusOrder. Servergesteuerte Felder wie id, createdAt, updatedAt, completedAt, deletedAt und rev können vom Client nie geschrieben werden. Die Listen stammen aus dem cloudWrite-Flag in packages/core/src/task-sync-schema.ts; diese Datei ist daher die aktuelle Referenz.

assignedTo ist der Name einer einzelnen Person als Zeichenfolge, zum Beispiel "Alex", kein Array von Personen-IDs. Mit null oder "" wird die Zuweisung entfernt. Beim Erstellen und Aktualisieren von Aufgaben über REST werden Arrays, Objekte, Zahlen und boolesche Werte mit HTTP 400 abgelehnt. Die Suche ignoriert bereits gespeicherte Zuweisungen mit ungültigem Datentyp, ohne sie umzuschreiben.

Ab Mindwtr Cloud 1.2.8 liefern GET /v1/tasks/:id und GET /v1/projects/:id einen starken ETag. Um die gelesene Version zu ändern, sende diesen Wert im Header If-Match beim zugehörigen PATCH. Der Server prüft den aktuellen Datensatz innerhalb seiner Schreibsperre. Hat sich der Datensatz geändert, auch nur ein Anhang, antwortet er mit 412 Precondition Failed, ohne zu schreiben. Lies den Datensatz erneut und erstelle die Änderung neu, bevor du es noch einmal versuchst. Ohne If-Match bleibt das bisherige bedingungslose Patch-Verhalten erhalten.

Setze bei Automatisierungen status innerhalb von props und lasse dueDate weg, wenn es keine Frist gibt. attachments muss ein Array von Anhangsobjekten sein, keine URL-Zeichenfolge. Ein Link-Anhang benötigt eine ID, kind: "link", Titel, URI sowie Erstellungs- und Änderungszeit wie im Beispiel. Erzeuge für jeden neuen Anhang eine eindeutige ID und behalte sie beim Bearbeiten desselben Links bei. Eine URL kann auch in props.description stehen, wenn sie nur in den Aufgabennotizen benötigt wird.

{
  "title": "JIRA-123 - Follow up",
  "props": {
    "status": "next",
    "attachments": [
      {
        "id": "890b7cda-e1ec-43de-a0d1-60b5385b7f8d",
        "kind": "link",
        "title": "JIRA-123",
        "uri": "https://jira.example.com/browse/JIRA-123",
        "createdAt": "2026-09-13T12:00:00.000Z",
        "updatedAt": "2026-09-13T12:00:00.000Z"
      }
    ]
  }
}

Erfassung

POST /v1/capture

Die Erfassung erstellt eine Aufgabe im Eingang aus einer Transkription, einer Audioaufnahme oder beidem. Der Inhalt kann als Multipart-Formulardaten, als JSON oder als reiner Text gesendet werden, aber nur Multipart-Formulardaten können Audio übertragen. Die Felder, die Antworten und die Einrichtung des Pebble Index 01 stehen unter Erfassungs-Webhook.

POST /v1/capture-tokens
GET /v1/capture-tokens
DELETE /v1/capture-tokens/:id

• POST /v1/capture-tokens erstellt einen Nur-Erfassungs-Token für das Konto. Der Inhalt ist { "label": "Pebble ring" }, und das Label ist optional. Es antwortet mit 201 und id, token, label und createdAt. Der Token wird einmal gezeigt.
• GET /v1/capture-tokens listet die Nur-Erfassungs-Token des Kontos mit id, label und createdAt auf. Keine Geheimnisse.
• DELETE /v1/capture-tokens/:id widerruft einen.

Alle drei brauchen den vollen Bearer-Token. Ein Nur-Erfassungs-Token wird nur bei POST /v1/capture akzeptiert und auf jeder anderen Route mit 403 abgelehnt.

Projekte, Bereiche und Abschnitte

GET /v1/projects
POST /v1/projects
GET /v1/projects/:id
PATCH /v1/projects/:id
DELETE /v1/projects/:id

GET /v1/areas
POST /v1/areas
GET /v1/areas/:id
PATCH /v1/areas/:id
DELETE /v1/areas/:id

GET /v1/sections
POST /v1/sections
GET /v1/sections/:id
PATCH /v1/sections/:id
DELETE /v1/sections/:id

Alle Listenendpunkte akzeptieren limit, offset und deleted=1. Abschnitte akzeptieren außerdem projectId.

Referenzfelder müssen auf aktive Datensätze verweisen. Die areaId eines Projekts muss einen aktiven Bereich referenzieren. Verwenden Sie areaId: null, um den Bereich eines Projekts zu entfernen; areaId: "" ist ungültig. Die projectId eines Abschnitts muss auf ein aktives Projekt verweisen.

Beim Löschen von Bereichen, Projekten und Abschnitten werden Tombstones und eine serverseitige Reparatur verwendet, damit der Snapshot für die Synchronisierung gültig bleibt.

Suche

GET /v1/search?query=<text>

Die Suche gibt aktive Aufgaben und Projekte in getrennten Arrays zurück. Sie unterstützt die gemeinsamen Parameter limit und offset sowie unabhängige Cursor:

Parameter	Zweck
taskLimit, taskOffset	Seitennavigation durch die Ergebnismenge der Aufgaben.
projectLimit, projectOffset	Seitennavigation durch die Ergebnismenge der Projekte.

Die Antwort enthält taskTotal, projectTotal und die tatsächlich verwendeten Cursorwerte.

Anhänge

GET /v1/attachments/:path
HEAD /v1/attachments/:path
PUT /v1/attachments/:path
DELETE /v1/attachments/:path

POST /v1/attachments/orphans
DELETE /v1/attachments/orphans

Anhangspfade werden innerhalb des authentifizierten Token-Namensraums aufgelöst. Für Uploads gelten die konfigurierte Bytegrenze und die Core-Validierungsregeln für Anhänge.

Der Endpunkt zum Bereinigen verwaister Dateien durchsucht den Namensraum nach Dateien, auf die data.json nicht mehr verweist. Dateien, die in den letzten fünf Minuten geändert wurden, werden übersprungen, damit ein Upload, der zeitgleich mit einem späteren Snapshot-Schreibvorgang erfolgt, nicht entfernt wird.

Kalender-Feed

GET /v1/calendar/feed
POST /v1/calendar/feed
DELETE /v1/calendar/feed

GET /v1/calendar/:token.ics

Die ersten drei Endpunkte benötigen den Bearer-Token und lesen, rotieren bzw. widerrufen den Feed-Token des Namespace. Sie liefern { "feed": { "token", "path", "createdAt" } } oder { "feed": null }, wenn nichts veröffentlicht ist. POST liefert 404 für einen Namespace, der noch nie Daten synchronisiert hat.

GET /v1/calendar/:token.ics benötigt keinen Authorization-Header — der Token in der URL ist das Zugangsmittel — und liefert text/calendar für diesen Namespace. Ein unbekannter Token ergibt 404.

Der Feed enthält ein Ereignis pro geplanter Aufgabe (startTime) und eines pro Frist (dueDate), passend zur Kalenderansicht der App: erledigte, archivierte, Referenz-, gelöschte und Aufgaben aus nicht aktiven Projekten fehlen, und eine Aufgabe, die am selben Tag geplant und fällig ist, erscheint einmal. Ereignisse tragen eine stabile UID und nur den Aufgabentitel — keine Beschreibung, Checkliste, Anhänge, Tags oder Projektdaten.

MCP-Adapter

Die veröffentlichte Hilfsanwendung mindwtr-mcp kann einen selbst gehosteten Cloud-Endpunkt als Backend verwenden. Konfigurieren Sie sie mit --cloud-url und --cloud-token oder den Umgebungsvariablen MINDWTR_MCP_CLOUD_URL / MINDWTR_MCP_CLOUD_TOKEN.

Der Cloud-gestützte MCP-Modus liest /v1/data und stellt Lesewerkzeuge für Aufgaben, Projekte, Abschnitte, Bereiche und Personen bereit. Mit --write leitet er Änderungen an Aufgaben, Projekten, Abschnitten und Bereichen über die oben genannten ressourcenspezifischen REST-Endpunkte; standardmäßig bleibt er schreibgeschützt und verwandelt Mindwtr Cloud selbst nicht in einen gehosteten MCP-Dienst.

cancelledAt

Task und Project unterstützen cancelledAt, einen optionalen ISO-Zeitstempel mit Zeitzone. Er archiviert die Verpflichtung als abgebrochen. Die Aufgabe erhält kein completedAt und erzeugt keine weitere Wiederholung. Beim Projekt bleiben erledigte Schritte erhalten; die übrigen Aktionen werden abgebrochen. Aktualisieren Sie vor der Synchronisierung alle schreibenden Clients. Siehe GTD-Workflow.

cancelledAt: null allein entfernt nur die Abbruchkennzeichnung. Zum Reaktivieren setzen Sie ausdrücklich einen nicht archivierten status.

Community-Integrationen

omarchy-mindwtr von ssalentin ist ein von der Community gepflegtes Plugin für die Omarchy-Leiste. Es bietet ein Aufgabenpanel mit Tastaturnavigation sowie das Erfassen im Eingang und Abschließen von Aufgaben über die Cloud-REST-API.

Vorausgesetzt werden Omarchy mit Quickshell und ein erreichbarer, selbst gehosteter Mindwtr-Cloud-Server mit Bearer-Token. Installation, Konfiguration und Support findest du im Plugin-Repository; zum Austausch gibt es Diskussion #1308.

Verwandte Seiten

• MCP-Server
• Cloud-Bereitstellung
• Synchronisierungsalgorithmus