API de la nube

Mindwtr Cloud expone una pequeña API con token al portador para sincronización, automatización de tareas y transferencia de adjuntos. Está diseñada para despliegues autohospedados y usa el mismo espacio de nombres de tokens que el backend de nube autohospedada.

Abrir el diagrama interactivo

Autenticación

Envía un token al portador en cada solicitud /v1/*:

Authorization: Bearer <token>

En producción, usa MINDWTR_CLOUD_AUTH_TOKENS o MINDWTR_CLOUD_AUTH_TOKENS_FILE. MINDWTR_CLOUD_ALLOW_ANY_TOKEN=true es solo para automatización controlada y limita los espacios nuevos mediante MINDWTR_CLOUD_ANY_TOKEN_MAX_NAMESPACES.

Estado

GET /health

Devuelve el estado del servidor sin autenticación.

Sincronización de instantáneas

GET /v1/data
PUT /v1/data

GET /v1/data devuelve la instantánea del espacio autenticado. Si no existe y se permiten escrituras, el servidor crea una vacía.

PUT /v1/data valida el AppData subido, lo combina con el espacio existente mediante el algoritmo del núcleo, valida el resultado y lo escribe. No fuerza una sobrescritura. Una respuesta correcta devuelve { ok: true, stats, clockSkewWarning }; stats usa la misma estructura de estadísticas que el diagnóstico local. La subida puede ocupar hasta MINDWTR_CLOUD_MAX_DATA_BODY_BYTES (50 MB por defecto); una mayor recibe 413 con { error, limitBytes }.

Tareas

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

Parámetros de lista:

Parámetro	Función
query	Búsqueda sin distinguir mayúsculas en título y metadatos.
status	Un estado: inbox, next, waiting, someday, reference, done o archived.
all=1	Incluye tareas completadas.
deleted=1	Incluye tareas eliminadas de forma reversible.
isFocusedToday	true/1 devuelve las tareas marcadas con estrella, incluidas las próximas acciones con inicio futuro en espera de Foco; false/0 devuelve el resto. Omítelo para no filtrar.
limit, offset	Tamaño de página y desplazamiento inicial.

La creación acepta title o un input de adición rápida, además de props opcional. El parche acepta campos compatibles con la validación de nube y aumenta los metadatos de revisión.

Al crear, props acepta estos campos de tarea: 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 y viewSectionIds. title es un campo de nivel superior, no un prop. El parche acepta los mismos campos más title, order, orderNum, boardOrder y focusOrder. Los campos gestionados por el servidor, como id, createdAt, updatedAt, completedAt, deletedAt y rev, nunca pueden escribirse desde el cliente. Las listas provienen del indicador cloudWrite en packages/core/src/task-sync-schema.ts, así que ese archivo es la referencia actual.

assignedTo es el nombre de una sola persona como cadena, por ejemplo "Alex", no un array de identificadores de personas. Usa null o "" para quitar la asignación. La creación y actualización de tareas por REST rechazan arrays, objetos, números y booleanos con HTTP 400. La búsqueda ignora las asignaciones ya almacenadas con un tipo incorrecto sin reescribirlas.

Mindwtr Cloud 1.2.8 y versiones posteriores devuelven un ETag fuerte en GET /v1/tasks/:id y GET /v1/projects/:id. Para actualizar la versión que leíste, envía esa etiqueta en If-Match con el PATCH correspondiente. El servidor comprueba el registro actual dentro de su bloqueo de escritura y devuelve 412 Precondition Failed sin escribir si el registro cambió, incluso si solo cambió un adjunto. Vuelve a leer el registro y reconstruye la actualización antes de reintentar. Si omites If-Match, se mantiene el comportamiento anterior de actualización incondicional.

En las automatizaciones, coloca status dentro de props y omite dueDate si no hay fecha límite. attachments debe ser un array de objetos de adjunto, no una cadena con una URL. Para adjuntar un enlace, proporciona un ID, kind: "link", título, URI y las fechas de creación y actualización, como en el ejemplo. Genera un ID único para cada adjunto nuevo y consérvalo al editar ese enlace. También puedes poner la URL en props.description si solo la necesitas en las notas de la tarea.

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

Captura

POST /v1/capture

La captura crea una tarea en la bandeja de entrada a partir de una transcripción, una grabación de audio o ambas. El cuerpo puede enviarse como datos de formulario multiparte, como JSON o como texto plano, pero solo los datos de formulario multiparte pueden llevar audio. Consulta Webhook de captura para ver los campos, las respuestas y la configuración del Pebble Index 01.

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

• POST /v1/capture-tokens crea un token solo de captura para la cuenta. El cuerpo es { "label": "Pebble ring" }, y la etiqueta es opcional. Devuelve 201 con id, token, label y createdAt. El token se muestra una sola vez.
• GET /v1/capture-tokens lista los tokens solo de captura de la cuenta con id, label y createdAt. Sin secretos.
• DELETE /v1/capture-tokens/:id revoca uno.

Los tres necesitan el token de portador completo. Un token solo de captura se acepta únicamente en POST /v1/capture y se rechaza con 403 en cualquier otra ruta.

Proyectos, áreas y secciones

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

Todos los endpoints de lista aceptan limit, offset y deleted=1. Las secciones también aceptan projectId.

Los campos de referencia deben apuntar a registros activos. El areaId de un proyecto debe referirse a un área activa. Usa areaId: null para quitarla; areaId: "" no es válido. El projectId de una sección debe referirse a un proyecto activo.

Al eliminar áreas, proyectos y secciones se usan marcadores y reparación en el servidor para conservar una instantánea válida.

Buscar

GET /v1/search?query=<text>

Devuelve tareas y proyectos activos en listas separadas. Admite limit y offset compartidos, además de cursores independientes:

Parámetro	Función
taskLimit, taskOffset	Paginar el conjunto de tareas.
projectLimit, projectOffset	Paginar el conjunto de proyectos.

La respuesta incluye taskTotal, projectTotal y los valores de cursor efectivos.

Adjuntos

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

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

Las rutas se resuelven dentro del espacio del token autenticado. Las subidas respetan el límite de bytes configurado y las reglas de validación del núcleo.

La limpieza de huérfanos busca archivos sin referencia en data.json. Omite los modificados en los últimos cinco minutos para no eliminar una subida que compita con una escritura posterior de la instantánea.

Feed de calendario

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

GET /v1/calendar/:token.ics

Los tres primeros requieren el token bearer y leen, rotan y revocan el token del feed del espacio de nombres. Devuelven { "feed": { "token", "path", "createdAt" } }, o { "feed": null } cuando no hay nada publicado. POST devuelve 404 para un espacio de nombres que nunca ha sincronizado datos.

GET /v1/calendar/:token.ics no lleva cabecera Authorization — el token de la URL es la credencial — y devuelve text/calendar para ese espacio de nombres. Un token desconocido devuelve 404.

El feed incluye un evento por tarea programada (startTime) y uno por fecha límite (dueDate), igual que la vista Calendario de la app: se excluyen las tareas completadas, archivadas, de referencia, eliminadas y las de proyectos no activos, y una tarea programada y vencida el mismo día aparece una sola vez. Los eventos llevan un UID estable y solo el título de la tarea: sin descripción, lista de control, adjuntos, etiquetas ni datos del proyecto.

Adaptador MCP

El auxiliar publicado mindwtr-mcp puede usar un endpoint Cloud autohospedado como backend. Configúralo mediante --cloud-url y --cloud-token, o las variables MINDWTR_MCP_CLOUD_URL / MINDWTR_MCP_CLOUD_TOKEN.

El modo MCP con nube lee /v1/data y ofrece herramientas de lectura para tareas, proyectos, secciones, áreas y personas. Con --write, dirige las mutaciones de tareas, proyectos, secciones y áreas a los endpoints REST anteriores. Sigue siendo de solo lectura de forma predeterminada y no convierte Mindwtr Cloud en un servicio MCP alojado.

cancelledAt

Task y Project admiten cancelledAt, una marca de tiempo ISO opcional con zona horaria. Archiva el compromiso como cancelado. La tarea no tiene completedAt ni genera otra repetición. Al cancelar un proyecto se conservan los pasos completados y se cancelan las acciones restantes. Actualiza todos los clientes que escriban datos antes de sincronizar. Consulta el flujo GTD.

cancelledAt: null por sí solo borra la marca sin reactivar el elemento. Para reactivarlo, establece explícitamente un status no archivado.

Integraciones de la comunidad

omarchy-mindwtr, creado por ssalentin, es un complemento de la comunidad para la barra de Omarchy. Ofrece un panel de tareas con navegación por teclado, captura en la bandeja de entrada y la posibilidad de completar tareas mediante la API REST de la nube.

Requiere Omarchy con Quickshell y un servidor Mindwtr Cloud autoalojado accesible con un token Bearer. Consulta el repositorio del complemento para la instalación, la configuración y el soporte, o participa en la discusión #1308.

Páginas relacionadas

• Servidor MCP
• Despliegue en la nube
• Algoritmo de sincronización