API Cloud

Mindwtr Cloud expose une petite API utilisant des jetons Bearer pour la synchronisation, l’automatisation des tâches et le transfert de pièces jointes. Elle est conçue pour les déploiements auto-hébergés et utilise le même espace de noms de jetons que le backend cloud auto-hébergé.

Les deux portes d'accès aux données Mindwtr : un assistant IA appelle le serveur MCP, qui exécute le paquet core partagé ; les applications envoient un jeton bearer au serveur cloud auto-hébergé, qui sert le document de synchronisation, les points d'accès aux enregistrements, les pièces jointes et un flux de calendrier. Seul le contrôle de santé ne demande aucun jeton.

Ouvrir le diagramme interactif

Authentification

Envoyez un jeton Bearer avec chaque requête /v1/* :

http

Authorization: Bearer <token>

Utilisez MINDWTR_CLOUD_AUTH_TOKENS ou MINDWTR_CLOUD_AUTH_TOKENS_FILE en production. MINDWTR_CLOUD_ALLOW_ANY_TOKEN=true est réservé aux automatisations contrôlées et limite le nombre de nouveaux espaces de noms avec MINDWTR_CLOUD_ANY_TOKEN_MAX_NAMESPACES.

État du service

text

GET /health

Renvoie l’état du serveur sans authentification.

Synchronisation des instantanés

text

GET /v1/data
PUT /v1/data

GET /v1/data renvoie l’instantané de l’espace de noms authentifié. Si l’espace de noms n’existe pas et que les écritures sont autorisées, le serveur crée un instantané vide.

PUT /v1/data valide l’AppData téléversé, le fusionne avec l’espace de noms existant à l’aide de l’algorithme de synchronisation du cœur, valide le résultat fusionné, puis le réécrit. Il ne s’agit pas d’un écrasement forcé. Une réponse réussie renvoie { ok: true, stats, clockSkewWarning }, où stats possède la même structure de statistiques de fusion que celle utilisée par les diagnostics de synchronisation locale. L’envoi peut atteindre MINDWTR_CLOUD_MAX_DATA_BODY_BYTES (50 Mo par défaut) ; un envoi plus grand reçoit 413 avec { error, limitBytes }.

Tâches

text

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

Paramètres de requête de la liste :

Paramètre	Rôle
`query`	Recherche de texte insensible à la casse dans le titre et les métadonnées des tâches.
`status`	Un statut de tâche : `inbox`, `next`, `waiting`, `someday`, `reference`, `done` ou `archived`.
`all=1`	Inclut les tâches terminées.
`deleted=1`	Inclut les tâches supprimées de manière réversible.
`isFocusedToday`	`true`/`1` renvoie les tâches étoilées, y compris les actions suivantes à début futur en attente de Focus ; `false`/`0` renvoie les autres. Omettez-le pour ne pas filtrer.
`limit`, `offset`	Taille de la page et décalage de départ.

La création accepte soit title, soit l’input d’ajout rapide, ainsi que des props facultatives. La modification accepte les champs de tâche pris en charge par la couche de validation du cloud et incrémente les métadonnées de révision de synchronisation.

À la création, props accepte ces champs de tâche : 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 et viewSectionIds. title est un champ de premier niveau, pas une prop. La modification accepte les mêmes champs plus title, order, orderNum, boardOrder et focusOrder. Les champs gérés par le serveur, comme id, createdAt, updatedAt, completedAt, deletedAt et rev, ne sont jamais modifiables par le client. Les listes proviennent de l’indicateur cloudWrite dans packages/core/src/task-sync-schema.ts ; ce fichier est donc la référence actuelle.

assignedTo contient le nom d’une seule personne sous forme de chaîne, par exemple "Alex", et non un tableau d’identifiants de personnes. Utilisez null ou "" pour supprimer l’affectation. La création et la modification de tâches via REST rejettent les tableaux, objets, nombres et booléens avec HTTP 400. La recherche ignore les affectations déjà stockées dont le type est incorrect, sans les réécrire.

Mindwtr Cloud 1.2.8 et les versions suivantes renvoient un ETag fort pour GET /v1/tasks/:id et GET /v1/projects/:id. Pour modifier la version que vous avez lue, transmettez cette valeur dans If-Match avec le PATCH correspondant. Le serveur vérifie le contenu actuel sous son verrou d’écriture et renvoie 412 Precondition Failed sans écrire si le contenu a changé, y compris si seule une pièce jointe a changé. Relisez le contenu et reconstruisez votre modification avant de réessayer. Sans If-Match, le comportement précédent de modification sans condition reste inchangé.

Pour les automatisations, placez status dans props et omettez dueDate si aucune échéance n’est définie. attachments doit être un tableau d’objets de pièce jointe, pas une chaîne contenant une URL. Pour joindre un lien, fournissez un ID, kind: "link", un titre, une URI et les dates de création et de modification, comme dans l’exemple. Générez un ID unique pour chaque nouvelle pièce jointe et conservez-le lors de la modification de ce lien. Vous pouvez aussi placer l’URL dans props.description si elle doit seulement figurer dans les notes de la tâche.

json

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

Capture

text

POST /v1/capture

La capture crée une tâche dans la boîte de réception à partir d'une transcription, d'un enregistrement audio ou des deux. Le corps peut être envoyé en données de formulaire multipart, en JSON ou en texte brut, mais seules les données de formulaire multipart peuvent transporter de l'audio. Consultez Webhook de capture pour les champs, les réponses et la configuration du Pebble Index 01.

text

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

POST /v1/capture-tokens crée un jeton de capture seule pour le compte. Le corps est { "label": "Pebble ring" }, et l'étiquette est facultative. Il renvoie 201 avec id, token, label et createdAt. Le jeton est affiché une seule fois.
GET /v1/capture-tokens liste les jetons de capture seule du compte avec id, label et createdAt. Aucun secret.
DELETE /v1/capture-tokens/:id en révoque un.

Les trois exigent le jeton bearer complet. Un jeton de capture seule n'est accepté que sur POST /v1/capture et est rejeté avec 403 sur toute autre route.

Projets, domaines et sections

text

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

Tous les points de terminaison de liste acceptent limit, offset et deleted=1. Les sections acceptent également projectId.

Les champs de référence doivent pointer vers des enregistrements actifs. L’areaId d’un projet doit référencer un domaine actif. Utilisez areaId: null pour retirer le domaine d’un projet ; areaId: "" n’est pas valide. Le projectId d’une section doit référencer un projet actif.

La suppression de domaines, de projets et de sections utilise des pierres tombales et une réparation côté serveur afin de maintenir la validité de l’instantané pour la synchronisation.

Recherche

text

GET /v1/search?query=<text>

La recherche renvoie les tâches et les projets actifs dans des tableaux distincts. Elle prend en charge les paramètres partagés limit et offset, ainsi que des curseurs indépendants :

Paramètre	Rôle
`taskLimit`, `taskOffset`	Paginer l’ensemble des résultats de tâches.
`projectLimit`, `projectOffset`	Paginer l’ensemble des résultats de projets.

La réponse comprend taskTotal, projectTotal et les valeurs effectives des curseurs.

Pièces jointes

text

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

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

Les chemins des pièces jointes sont résolus dans l’espace de noms du jeton authentifié. Les téléversements respectent la limite d’octets configurée et les règles de validation des pièces jointes du cœur.

Le point de terminaison de nettoyage des fichiers orphelins analyse l’espace de noms afin de trouver les fichiers qui ne sont plus référencés par data.json. Il ignore les fichiers modifiés au cours des cinq dernières minutes afin qu’un téléversement en concurrence avec une écriture ultérieure de l’instantané ne soit pas supprimé.

Flux de calendrier

text

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

GET /v1/calendar/:token.ics

Les trois premiers exigent le jeton bearer et permettent de lire, régénérer et révoquer le jeton de flux de l'espace de noms. Ils renvoient { "feed": { "token", "path", "createdAt" } }, ou { "feed": null } si rien n'est publié. POST renvoie 404 pour un espace de noms qui n'a jamais synchronisé de données.

GET /v1/calendar/:token.ics ne prend pas d'en-tête Authorization — le jeton dans l'URL est l'identifiant — et renvoie text/calendar pour cet espace de noms. Un jeton inconnu renvoie 404.

Le flux contient un événement par tâche planifiée (startTime) et un par échéance (dueDate), conformément à la vue Calendrier de l'application : les tâches terminées, archivées, de référence, supprimées et celles des projets non actifs sont exclues, et une tâche planifiée et due le même jour n'apparaît qu'une fois. Les événements portent un UID stable et le seul titre de la tâche — ni description, ni check-list, ni pièces jointes, ni étiquettes, ni données de projet.

Adaptateur MCP

L’utilitaire publié mindwtr-mcp peut utiliser un point de terminaison Cloud auto-hébergé comme backend. Configurez-le avec --cloud-url et --cloud-token, ou avec les variables d’environnement MINDWTR_MCP_CLOUD_URL / MINDWTR_MCP_CLOUD_TOKEN.

Le mode MCP adossé au Cloud lit /v1/data et expose des outils de lecture pour les tâches, les projets, les sections, les domaines et les personnes. Avec --write, il achemine les modifications de tâches, de projets, de sections et de domaines par les points de terminaison REST propres à chaque ressource ci-dessus ; il reste en lecture seule par défaut et ne transforme pas Mindwtr Cloud lui-même en service MCP hébergé.

`cancelledAt`

Task et Project acceptent cancelledAt, un horodatage ISO facultatif avec fuseau horaire. Il archive l'engagement comme annulé. La tâche n'a pas de completedAt et ne génère pas d'occurrence suivante. Pour un projet, les étapes terminées sont conservées et les actions restantes sont annulées. Mettez à jour tous les clients qui écrivent les données avant la synchronisation. Voir le flux GTD.

cancelledAt: null seul efface le marqueur sans réactiver l'élément. Pour le réactiver, définissez explicitement un status non archivé.

Intégrations communautaires

omarchy-mindwtr, créé par ssalentin, est un plugin communautaire pour la barre Omarchy. Il propose un panneau de tâches avec navigation au clavier, capture dans la boîte de réception et validation des tâches terminées via l’API REST Cloud.

Il nécessite Omarchy avec Quickshell et un serveur Mindwtr Cloud auto-hébergé accessible avec un jeton Bearer. Consultez le dépôt du plugin pour l’installation, la configuration et l’assistance, ou participez à la discussion #1308.

API Cloud ​

Authentification ​

État du service ​

Synchronisation des instantanés ​

Tâches ​

Capture ​

Projets, domaines et sections ​

Recherche ​

Pièces jointes ​

Flux de calendrier ​

Adaptateur MCP ​

cancelledAt ​

Intégrations communautaires ​

Pages connexes ​

API Cloud

Authentification

État du service

Synchronisation des instantanés

Tâches

Capture

Projets, domaines et sections

Recherche

Pièces jointes

Flux de calendrier

Adaptateur MCP

`cancelledAt`

Intégrations communautaires

Pages connexes