Serveur d’API locale

Mindwtr comprend un serveur d’API REST locale facultatif pour les scripts et les intégrations. Sur ordinateur, il s’exécute dans le binaire de l’application et utilise les mêmes chemins de stockage local que celle-ci. Le dépôt comprend également un utilitaire Bun pour le développement et les scripts avancés.

---

Activation sur ordinateur

Les versions de bureau peuvent démarrer l’API REST locale sans exécuter le code source :

• Ouvrez Réglages -> Avancé.
• Activez Serveur d’API locale.
• Conservez le port par défaut 3456 ou choisissez un autre port localhost.
• Copiez le jeton porteur généré depuis la même carte de réglages.

L’application se lie uniquement à 127.0.0.1 et exige Authorization: Bearer <token> pour chaque requête. Les binaires mobiles n’exposent pas d’API REST locale.

Utilitaire de développement

L’utilitaire du dépôt reste disponible lorsque vous souhaitez exécuter l’API en dehors de l’application de bureau ou lui indiquer des fichiers précis.

---

Démarrage rapide

Depuis l’application de bureau :

Settings -> Advanced -> Enable local API server

URL par défaut :

http://127.0.0.1:3456

Depuis la racine du dépôt avec Bun :

bun install
MINDWTR_API_TOKEN=replace-with-a-strong-token bun run mindwtr:api -- --port 4317 --host 127.0.0.1

Options

Option	Valeur par défaut	Description
--port <n>	4317	Port du serveur
--host <host>	127.0.0.1	Adresse d’écoute
--data <path>	Valeur de la plateforme	Remplacer l’emplacement de data.json
--db <path>	Valeur de la plateforme	Remplacer l’emplacement de mindwtr.db
--dangerously-disable-auth	désactivé	Démarrer sans aucun jeton — non sécurisé, et pas sûr pour un navigateur même en loopback

Variables d’environnement

Variable	Description
MINDWTR_DATA	Remplacer l’emplacement de data.json (si --data est omis)
MINDWTR_DB_PATH	Remplacer l’emplacement de mindwtr.db (si --db est omis)
MINDWTR_API_TOKEN	Obligatoire. Jeton porteur exigé à chaque requête ; l’utilitaire ne démarre pas sans lui, sauf si vous passez --dangerously-disable-auth
MINDWTR_API_CORS_ORIGIN	Facultatif. Une seule origine http(s) exacte autorisée à appeler l’API ; aucun en-tête CORS n’est envoyé si la variable est absente

Par défaut, l’API résout data.json et mindwtr.db à l’aide des chemins de plateforme de Mindwtr (en privilégiant les données XDG sous Linux).

---

Authentification

Les requêtes à l’API locale de l’application de bureau exigent toujours le jeton porteur affiché sous Réglages -> Avancé :

Authorization: Bearer <token>

L’utilitaire Bun exige lui aussi un jeton : il s’arrête immédiatement si MINDWTR_API_TOKEN n’est pas défini, sauf si vous passez explicitement --dangerously-disable-auth (réservé aux tests de compatibilité isolés).

---

Points de terminaison

Méthode	Point de terminaison	Description
GET	/health	Contrôle d’intégrité → { ok: true }
GET	/tasks	Répertorier les tâches
GET	/tasks?status=next	Filtrer par statut
GET	/tasks?query=@work	Rechercher des tâches
GET	/tasks?isFocusedToday=true	Ordinateur : filtrer les tâches étoilées, y compris celles en attente
GET	/tasks?all=1	Inclure les tâches terminées/archivées
GET	/tasks?deleted=1	Inclure les suppressions logiques
POST	/tasks	Créer une tâche
GET	/tasks/:id	Obtenir une tâche
PATCH	/tasks/:id	Mettre à jour une tâche
DELETE	/tasks/:id	Supprimer logiquement une tâche
POST	/tasks/:id/complete	Marquer comme terminée
POST	/tasks/:id/archive	Marquer comme archivée
POST	/tasks/:id/restore	Restaurer une tâche supprimée logiquement
GET	/projects	Répertorier les projets
POST	/projects	Ordinateur : créer un projet
GET	/projects/:id	Ordinateur : obtenir un projet
PATCH	/projects/:id	Ordinateur : modifier un projet
DELETE	/projects/:id	Ordinateur : supprimer logiquement un projet
POST	/projects/:id/restore	Ordinateur : restaurer un projet
GET	/areas	Répertorier les domaines
GET	/areas/:id	Bureau : lire un domaine
PATCH	/areas/:id	Bureau : modifier un domaine
GET	/v1/areas	Alias de compatibilité pour les domaines
GET	/sections	Utilitaire : répertorier les sections, éventuellement ?projectId=
POST	/sections	Utilitaire : créer une section
GET	/sections/:id	Utilitaire : obtenir une section
PATCH	/sections/:id	Utilitaire : mettre à jour une section
DELETE	/sections/:id	Utilitaire : supprimer une section
GET	/search?query=...	Rechercher des tâches et des projets

L’API locale de bureau renvoie 409 (recurrence_requires_app) lorsque terminer une tâche à échéancier fixe, avec une date de début mais sans date d’échéance, nécessite de sauter des occurrences passées. La tâche reste inchangée ; terminez-la dans l’application. Les tâches avec seulement une date de début restent prises en charge si la prochaine occurrence est encore actuelle ou future.

Les lignes marquées Bureau n’existent que dans l’API locale de l’application de bureau. Les lignes marquées Utilitaire n’existent que dans l’utilitaire Bun, qui y répond aussi sous le préfixe /v1/ (/v1/sections).

L’API locale de l’application de bureau accepte isFocusedToday=true/1 et isFocusedToday=false/0. Avec true ou 1, elle renvoie les tâches étoilées, y compris les actions suivantes à début futur en attente de Focus. Avec false ou 0, elle renvoie les tâches non marquées, y compris les anciens enregistrements dépourvus de ce champ. Sans le paramètre, elle ne filtre pas la liste selon ce champ. Pour toute autre valeur, elle répond avec 400.

Ici, query est une recherche en texte brut : la valeur est mise en minuscules et testée comme sous-chaîne sur le titre, la description, le statut, les tags, les contextes, les identifiants de projet et de domaine et les notes de suivi de la tâche. Ce n’est pas le langage d’opérateurs. status:, context:, tag:, due:<=7d, les expressions entre guillemets et la -négation appartiennent au champ de recherche de l’application, au --query de la CLI et à la liste de tâches du serveur MCP ; envoyés ici, ils sont comparés comme des caractères littéraux et ne renvoient généralement rien.

Formes des réponses

Tâche (partielle)

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

Projet (partiel)

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

Domaine

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

Corps de création d’une tâche

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

L’application de bureau utilise title lorsqu’il est présent, sinon input, et applique les props explicites. L’utilitaire Bun exécute en plus parseQuickAdd pour input.

Écriture des projets sur ordinateur

L’API intégrée à l’application de bureau permet de créer, obtenir, modifier, supprimer logiquement et restaurer des projets. La création exige title ; areaId, color, status, isSequential et order sont facultatifs. Les mises à jour acceptent les mêmes champs modifiables. La création, la lecture, la modification et la restauration renvoient le projet enregistré sous la forme { "project": { ... } } ; la suppression renvoie { "ok": true }.

Placez les options de création dans props, par exemple { "title": "Plan the move", "props": { "isSequential": true } } ; les champs PATCH vont directement dans le corps. sequentialScope accepte project ou section. Le status du projet accepte active, someday, waiting ou archived. Utilisez areaId: null pour retirer le domaine. L’archivage et la réactivation suivent les règles de l’application pour les tâches et sections du projet. Pour PATCH, un projet absent renvoie 404 ; un projet supprimé ou purgé renvoie 409.

GET /projects/:id renvoie également un projet conservé après suppression logique, afin qu’un script puisse l’examiner avant de le restaurer. DELETE /projects/:id supprime logiquement le projet et ses sections actives, puis dissocie les tâches actives au lieu de les supprimer ou de modifier leur état. POST /projects/:id/restore restaure le projet et les enfants supprimés par la même ancienne cascade, mais ne réassocie pas les tâches dissociées par une suppression actuelle. Répéter la suppression ou la restauration est sans danger et conserve l’état actuel. Les changements de cycle de vie d’un projet purgé renvoient 409.

Créer un projet séquentiel:

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 .

Passer un projet existant en mode parallèle:

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 .

Modifier les domaines sur ordinateur

GET /areas/:id et PATCH /areas/:id renvoient { "area": { ... } }. Les deux renvoient 404 pour les domaines inconnus ou supprimés. Ces endpoints appartiennent à l’API intégrée de bureau, pas à l’assistant Bun.

PATCH accepte un objet non vide contenant uniquement name, color, icon et order. name doit être une chaîne non vide ; les espaces aux extrémités sont supprimés. color et icon acceptent des chaînes ou null pour effacer le champ. order doit être un nombre fini ; les valeurs négatives et fractionnaires sont acceptées. Les champs inconnus, types incorrects, noms vides et objets vides renvoient 400.

Un nom identique à celui d’un autre domaine non supprimé, après suppression des espaces aux extrémités et comparaison insensible à la casse, renvoie 409 sans aucune modification. L’API ne fusionne jamais implicitement les domaines. Les changements de nom et de couleur conservent le comportement de l’app pour les métadonnées des projets associés et sont enregistrés ensemble. Effacer la couleur d’un domaine rétablit aussi la couleur par défaut (#94a3b8) de ses projets associés. order modifie la position numérique de ce domaine ; ce n’est pas un réordonnancement par lots. La création et la suppression de domaines ne sont pas incluses.

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 .

Classement des tâches sur ordinateur

Utilisez PATCH /tasks/:id avec status pour déplacer une tâche active entre inbox, next, waiting, someday et reference. Continuez à utiliser les actions dédiées /complete, /archive et /restore pour ces opérations. PATCH n’accepte pas les états terminaux.

PATCH ne peut pas rouvrir une tâche terminée ou archivée (409) ; rouvrez-la d’abord dans l’application. Restaurez une tâche supprimée avec /restore avant de la classer. Les tâches purgées ne peuvent pas être classées.

Déplacer une tâche vers inbox, next, waiting ou someday dans un projet archivé renvoie 409. Réactivez d’abord le projet avec PATCH /projects/:id et {"status":"active"}, ou déplacez la tâche hors de ce projet dans le même PATCH de tâche.

Déplacer une tâche de la boîte de réception vers les prochaines actions:

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 .

---

Exemples

Répertorier les prochaines actions :

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

Créer avec des propriétés explicites :

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 .

Terminer une tâche :

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

---

Outil en ligne de commande

Une interface en ligne de commande plus simple est également disponible :

# 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

Référence de la CLI

Commande	Exemple	Remarques
add	mindwtr:cli -- add "Call mom @phone"	Utilise l’analyse de l’ajout rapide
list	mindwtr:cli -- list --status next	Prend en charge --all, --deleted, --query
get	mindwtr:cli -- get <taskId>	Affiche le JSON complet de la tâche
update	mindwtr:cli -- update <taskId> '{"status":"next"}'	Applique un correctif JSON
search	mindwtr:cli -- search "@work due:<=7d"	Recherche des tâches/projets
complete	mindwtr:cli -- complete <taskId>	Marque la tâche comme terminée
archive	mindwtr:cli -- archive <taskId>	Marque la tâche comme archivée
delete	mindwtr:cli -- delete <taskId>	Supprime logiquement la tâche
restore	mindwtr:cli -- restore <taskId>	Restaure une tâche supprimée
projects	mindwtr:cli -- projects	Répertorie les projets actifs

---

Notes de sécurité

• Le serveur est conçu pour s’exécuter sur 127.0.0.1 (localhost). Ne l’exposez pas publiquement à moins d’en comprendre les risques.
• L’accès à l’API de bureau exige le jeton porteur généré dans les réglages. Gardez ce jeton privé.
• Si vous avez besoin d’un accès distant à l’utilitaire Bun, définissez MINDWTR_API_TOKEN et placez le serveur derrière un proxy inverse authentifié.

---

Voir aussi

• Guide du développeur
• API Cloud