Servidor de API local

Mindwtr incluye un servidor de API REST local opcional para scripts e integraciones. En escritorio, se ejecuta dentro del binario de la aplicación y usa las mismas rutas de almacenamiento local que esta. El repositorio también incluye un asistente de Bun para desarrollo y scripts avanzados.

---

Activación en escritorio

Las compilaciones de escritorio pueden iniciar la API REST local sin ejecutar el código fuente:

• Abre Ajustes -> Avanzado.
• Activa Servidor de API local.
• Mantén el puerto predeterminado 3456 o elige otro puerto de localhost.
• Copia el token de portador generado desde la misma tarjeta de ajustes.

La aplicación solo se vincula a 127.0.0.1 y requiere Authorization: Bearer <token> en cada solicitud. Los binarios móviles no exponen una API REST local.

Asistente de desarrollo

El asistente del repositorio sigue disponible cuando quieras ejecutar la API fuera de la aplicación de escritorio o hacer que apunte a archivos explícitos.

---

Inicio rápido

Desde la aplicación de escritorio:

Settings -> Advanced -> Enable local API server

URL predeterminada:

http://127.0.0.1:3456

Desde la raíz del repositorio con Bun:

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

Opciones

Opción	Valor predeterminado	Descripción
--port <n>	4317	Puerto del servidor
--host <host>	127.0.0.1	Dirección de enlace
--data <path>	Valor predeterminado de la plataforma	Sobrescribe la ubicación de data.json
--db <path>	Valor predeterminado de la plataforma	Sobrescribe la ubicación de mindwtr.db
--dangerously-disable-auth	desactivado	Ejecutar sin ningún token: inseguro y tampoco seguro para navegadores aunque sea en loopback

Variables de entorno

Variable	Descripción
MINDWTR_DATA	Sobrescribe la ubicación de data.json (si se omite --data)
MINDWTR_DB_PATH	Sobrescribe la ubicación de mindwtr.db (si se omite --db)
MINDWTR_API_TOKEN	Obligatorio. Token de portador que el asistente exige en cada solicitud; no arranca sin uno salvo que pases --dangerously-disable-auth
MINDWTR_API_CORS_ORIGIN	Opcional. Un origen http(s) exacto autorizado a llamar a la API; sin valor no se envían cabeceras CORS

De forma predeterminada, la API resuelve tanto data.json como mindwtr.db mediante las rutas de plataforma de Mindwtr (con preferencia por los datos XDG en Linux).

---

Autenticación

Las solicitudes a la API local de escritorio siempre requieren el token de portador que se muestra en Ajustes -> Avanzado:

Authorization: Bearer <token>

El asistente de Bun también requiere un token: sale de inmediato si no se establece MINDWTR_API_TOKEN, salvo que pases explícitamente --dangerously-disable-auth (pensado solo para pruebas de compatibilidad aisladas).

---

Endpoints

Método	Endpoint	Descripción
GET	/health	Comprobación de estado → { ok: true }
GET	/tasks	Enumera las tareas
GET	/tasks?status=next	Filtra por estado
GET	/tasks?query=@work	Busca tareas
GET	/tasks?isFocusedToday=true	Escritorio: filtra tareas marcadas, incluidas las futuras en espera
GET	/tasks?all=1	Incluye las completadas/archivadas
GET	/tasks?deleted=1	Incluye las eliminadas de forma lógica
POST	/tasks	Crea una tarea
GET	/tasks/:id	Obtiene una sola tarea
PATCH	/tasks/:id	Actualiza una tarea
DELETE	/tasks/:id	Elimina una tarea de forma lógica
POST	/tasks/:id/complete	Marca como completada
POST	/tasks/:id/archive	Marca como archivada
POST	/tasks/:id/restore	Restaura una tarea eliminada de forma lógica
GET	/projects	Enumera los proyectos
POST	/projects	Escritorio: crear proyecto
GET	/projects/:id	Escritorio: obtener un proyecto
PATCH	/projects/:id	Escritorio: actualizar proyecto
DELETE	/projects/:id	Escritorio: eliminar proyecto de forma lógica
POST	/projects/:id/restore	Escritorio: restaurar proyecto
GET	/areas	Enumera las áreas
GET	/areas/:id	Escritorio: obtener un área
PATCH	/areas/:id	Escritorio: actualizar un área
GET	/v1/areas	Alias de compatibilidad para las áreas
GET	/sections	Asistente: enumera las secciones, opcionalmente con ?projectId=
POST	/sections	Asistente: crea una sección
GET	/sections/:id	Asistente: obtiene una sección
PATCH	/sections/:id	Asistente: actualiza una sección
DELETE	/sections/:id	Asistente: elimina una sección
GET	/search?query=...	Busca tareas y proyectos

La API local de escritorio devuelve 409 (recurrence_requires_app) si completar una tarea de calendario fijo con fecha de inicio y sin fecha de vencimiento requiere saltar ocurrencias pasadas. La tarea no cambia; complétala en la aplicación. Las tareas con solo fecha de inicio siguen siendo compatibles si la siguiente ocurrencia aún es vigente o futura.

Las filas marcadas con Escritorio solo existen en la API local de la aplicación de escritorio. Las filas marcadas con Asistente solo existen en el asistente de Bun, que además las responde con el prefijo /v1/ (/v1/sections).

La API local de escritorio acepta isFocusedToday=true/1 e isFocusedToday=false/0. Con true o 1, devuelve las tareas marcadas con estrella, incluidas las próximas acciones con inicio futuro en espera de Foco. Con false o 0, devuelve las tareas sin esa marca, incluidos los registros antiguos que no contienen el campo. Si omites el parámetro, la lista no se filtra por este campo. Los demás valores devuelven 400.

Aquí query es una búsqueda de texto plano: el valor se pasa a minúsculas y se comprueba como subcadena contra el título, la descripción, el estado, las etiquetas, los contextos, los identificadores de proyecto y área y las notas de apoyo de la tarea. No es el lenguaje de operadores. status:, context:, tag:, due:<=7d, las frases entre comillas y la -negación pertenecen al buscador de la aplicación, al --query de la CLI y al listado de tareas del servidor MCP; enviados aquí se comparan como caracteres literales y normalmente no devuelven nada.

Formas de las respuestas

Tarea (parcial)

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

Proyecto (parcial)

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

Área

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

Cuerpo para crear una tarea

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

En escritorio se usa title cuando está presente; de lo contrario, se usa input, y se aplican las props explícitas. El asistente de Bun ejecuta además parseQuickAdd para input.

Escritura de proyectos en escritorio

La API integrada de escritorio permite crear, obtener, actualizar, eliminar de forma lógica y restaurar proyectos. Para crear un proyecto, title es obligatorio; areaId, color, status, isSequential y order son opcionales. Las actualizaciones aceptan los mismos campos editables. Crear, obtener, actualizar y restaurar devuelven el proyecto guardado como { "project": { ... } }; eliminar devuelve { "ok": true }.

Envía las opciones de creación dentro de props, por ejemplo { "title": "Plan the move", "props": { "isSequential": true } }; los campos PATCH van directamente en el cuerpo. sequentialScope acepta project o section. El status del proyecto acepta active, someday, waiting o archived. Usa areaId: null para quitar el área. Archivar y reactivar un proyecto sigue las reglas de la aplicación para tareas y secciones. En PATCH, los proyectos inexistentes devuelven 404; los eliminados o purgados devuelven 409.

GET /projects/:id también devuelve un proyecto almacenado que se eliminó de forma lógica, para que un script pueda inspeccionarlo antes de restaurarlo. DELETE /projects/:id elimina de forma lógica el proyecto y sus secciones activas, y desvincula las tareas activas en vez de eliminarlas o cambiar su estado. POST /projects/:id/restore restaura el proyecto y los elementos secundarios eliminados por la misma cascada antigua, pero no vuelve a vincular las tareas desvinculadas por una eliminación actual. Repetir la eliminación o restauración es seguro y no cambia el estado actual. Los cambios de ciclo de vida de un proyecto purgado devuelven 409.

Crear un proyecto secuencial:

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 .

Cambiar un proyecto existente a paralelo:

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 .

Editar áreas en escritorio

GET /areas/:id y PATCH /areas/:id devuelven { "area": { ... } }. Ambos devuelven 404 para áreas desconocidas o eliminadas. Estos endpoints pertenecen a la API integrada de escritorio, no al auxiliar Bun.

PATCH acepta un objeto no vacío que contenga únicamente name, color, icon y order. name debe ser una cadena no vacía; se recortan los espacios de los extremos. color e icon aceptan cadenas o null para borrar el campo. order debe ser un número finito; se permiten fracciones y valores negativos. Los campos desconocidos, tipos inválidos, nombres en blanco y objetos vacíos devuelven 400.

Si el nombre coincide con otra área no eliminada tras recortar espacios e ignorar mayúsculas y minúsculas, se devuelve 409 sin cambios. La API nunca fusiona áreas implícitamente. Los cambios de nombre y color mantienen el comportamiento de la app para los metadatos de proyectos relacionados y se guardan juntos. Borrar el color del área también restablece el color predeterminado (#94a3b8) de sus proyectos vinculados. order modifica la posición numérica de esta área; no es una operación de reordenación por lotes. La creación y eliminación de áreas quedan fuera de estos endpoints.

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 .

Clasificación de tareas en escritorio

Usa PATCH /tasks/:id con status para mover una tarea activa entre inbox, next, waiting, someday y reference. Sigue usando las acciones específicas /complete, /archive y /restore para esas operaciones. PATCH no acepta estados terminales.

PATCH no puede reabrir una tarea completada o archivada (409); vuelve a abrirla primero en la aplicación. Restaura una tarea eliminada con /restore antes de clasificarla. Las tareas purgadas no se pueden clasificar.

Mover una tarea a inbox, next, waiting o someday dentro de un proyecto archivado devuelve 409. Reactiva primero el proyecto con PATCH /projects/:id y {"status":"active"}, o mueve la tarea fuera de ese proyecto en el mismo PATCH de la tarea.

Mover una tarea de la bandeja de entrada a próximas acciones:

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 .

---

Ejemplos

Enumerar las siguientes acciones:

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

Crear con propiedades explícitas:

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 .

Completar una tarea:

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

---

Herramienta de CLI

También está disponible una interfaz de línea de comandos más sencilla:

# 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

Referencia de la CLI

Comando	Ejemplo	Notas
add	mindwtr:cli -- add "Call mom @phone"	Usa el análisis de adición rápida
list	mindwtr:cli -- list --status next	Admite --all, --deleted, --query
get	mindwtr:cli -- get <taskId>	Imprime el JSON completo de la tarea
update	mindwtr:cli -- update <taskId> '{"status":"next"}'	Aplica un parche JSON
search	mindwtr:cli -- search "@work due:<=7d"	Busca tareas/proyectos
complete	mindwtr:cli -- complete <taskId>	Marca la tarea como completada
archive	mindwtr:cli -- archive <taskId>	Marca la tarea como archivada
delete	mindwtr:cli -- delete <taskId>	Elimina la tarea de forma lógica
restore	mindwtr:cli -- restore <taskId>	Restaura una tarea eliminada
projects	mindwtr:cli -- projects	Enumera los proyectos activos

---

Notas de seguridad

• El servidor está pensado para ejecutarse en 127.0.0.1 (localhost). No lo expongas públicamente salvo que comprendas los riesgos.
• El acceso a la API de escritorio requiere el token de portador generado en Ajustes. Mantén ese token en privado.
• Si necesitas acceso remoto al asistente de Bun, establece MINDWTR_API_TOKEN y coloca el servidor detrás de un proxy inverso autenticado.

---

Véase también

• Guía para desarrolladores
• API de Cloud