Cloud API

Mindwtr Cloud 提供一套小型 bearer-token API，用于同步、任务自动化和附件传输。它面向自托管部署，并与自托管云端后端使用相同的令牌命名空间。

访问 Mindwtr 数据的两条通道：AI 助手调用 MCP 服务器，由它运行共享的 core 包；应用则带着 bearer token 访问自行托管的云服务器，云服务器提供同步文档、记录端点、附件和日历订阅。只有健康检查不需要 token。

打开交互式图表

认证

每个 /v1/* 请求都需发送 bearer token：

http

Authorization: Bearer <token>

生产环境请使用 MINDWTR_CLOUD_AUTH_TOKENS 或 MINDWTR_CLOUD_AUTH_TOKENS_FILE。MINDWTR_CLOUD_ALLOW_ANY_TOKEN=true 仅用于受控自动化，并通过 MINDWTR_CLOUD_ANY_TOKEN_MAX_NAMESPACES 限制新命名空间数量。

健康检查

text

GET /health

无需认证即可返回服务器健康状态。

快照同步

text

GET /v1/data
PUT /v1/data

GET /v1/data 返回已认证命名空间的快照。如果命名空间不存在且允许写入，服务器会创建空快照。

PUT /v1/data 会验证上传的 AppData，使用核心同步算法与现有命名空间合并，验证合并结果后再写回。它不是强制覆盖。成功响应返回 { ok: true, stats, clockSkewWarning }，其中 stats 与本地同步诊断使用相同的合并统计结构。上传大小上限为 MINDWTR_CLOUD_MAX_DATA_BODY_BYTES（默认 50 MB）；超出时返回 413 和 { error, limitBytes }。

任务

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

列表查询参数：

参数	用途
`query`	在任务标题和元数据中进行不区分大小写的文本搜索。
`status`	一种任务状态：`inbox`、`next`、`waiting`、`someday`、`reference`、`done` 或 `archived`。
`all=1`	包含已完成任务。
`deleted=1`	包含软删除任务。
`isFocusedToday`	`true`/`1` 返回加星任务，包括排队等待进入专注的未来开始任务；`false`/`0` 返回其余任务。省略则不过滤。
`limit`、`offset`	页面大小与起始偏移。

创建操作接受 title 或快速添加 input，以及可选的 props。Patch 接受云端验证层支持的任务字段，并推进同步修订元数据。

创建时，props 接受以下任务字段：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 和 viewSectionIds。title 是顶层字段，不是 prop。Patch 接受相同的字段，另加 title, order, orderNum, boardOrder 和 focusOrder。由服务器管理的字段（如 id, createdAt, updatedAt, completedAt, deletedAt 和 rev）客户端永远不能写入。这些列表来自 packages/core/src/task-sync-schema.ts 中的 cloudWrite 标记，因此该文件是当前的参考依据。

assignedTo 是单个人员姓名的字符串，例如 "Alex"，不是人员 ID 数组。使用 null 或 "" 清除指派。通过 REST 创建或更新任务时，数组、对象、数字和布尔值会被拒绝，并返回 HTTP 400。搜索会忽略已存储的非字符串指派值，不会改写原始数据。

Mindwtr Cloud 1.2.8 及更高版本会在 GET /v1/tasks/:id 和 GET /v1/projects/:id 的响应中返回强 ETag。要更新刚读取的版本，请在对应的 PATCH 请求中通过 If-Match 发送该标签。服务器会在写锁内检查当前记录；如果记录已改变，即使只改变了附件，也会返回 412 Precondition Failed，不执行写入。请重新读取记录并重新构建更新后再试。省略 If-Match 时，仍使用原有的无条件更新行为。

自动化创建任务时，请把 status 放在 props 内；没有截止日期时省略 dueDate。attachments 必须是附件对象数组，不能直接传入 URL 字符串。链接附件需要提供 ID、kind: "link"、标题、URI 和创建/更新时间，格式如下。为每个新附件生成唯一 ID；编辑同一链接时保留该 ID。如果只需在任务备注中保存网址，也可以使用 props.description。

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

收集

text

POST /v1/capture

收集端点可以用转写文本、录音或两者一起创建一条收集箱任务。请求体可以是多部分表单数据、JSON 或纯文本，但只有多部分表单数据能携带音频。字段、响应以及 Pebble Index 01 的设置方法，请见收集 Webhook。

text

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

POST /v1/capture-tokens 为账户创建一个只能收集的令牌。请求体是 { "label": "Pebble ring" }，label 可以不填。返回 201，带有 id、token、label 和 createdAt。令牌只显示一次。
GET /v1/capture-tokens 列出账户的只能收集的令牌，包含 id、label 和 createdAt。不含密钥。
DELETE /v1/capture-tokens/:id 撤销一个令牌。

这三个端点都需要完整的 bearer 令牌。只能收集的令牌只在 POST /v1/capture 上被接受，在其他任何路由上都会被拒绝并返回 403。

项目、领域与分区

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

所有列表端点都接受 limit、offset 和 deleted=1。分区还接受 projectId。

引用字段必须指向现存记录。项目的 areaId 必须引用现存领域。使用 areaId: null 清除项目领域；areaId: "" 无效。分区的 projectId 必须引用现存项目。

删除领域、项目和分区时会使用删除标记与服务器端修复，确保快照对同步仍然有效。

搜索

text

GET /v1/search?query=<text>

搜索在不同数组中返回现存任务和项目。它支持共享的 limit 与 offset 参数，以及独立游标：

参数	用途
`taskLimit`、`taskOffset`	对任务结果集分页。
`projectLimit`、`projectOffset`	对项目结果集分页。

响应包含 taskTotal、projectTotal 和实际游标值。

附件

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

附件路径会在已认证令牌命名空间内解析。上传受已配置字节上限和核心附件验证规则约束。

失去关联文件清理端点会扫描命名空间，查找不再被 data.json 引用的文件。它会跳过最近五分钟内修改的文件，避免在上传与稍后快照写入竞争时误删。

日历订阅源

text

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

GET /v1/calendar/:token.ics

前三个接口需要 bearer 令牌，分别用于读取、轮换和撤销该命名空间的订阅源令牌。它们返回 { "feed": { "token", "path", "createdAt" } }；若尚未发布则返回 { "feed": null }。对于从未同步过数据的命名空间，POST 返回 404。

GET /v1/calendar/:token.ics 不需要 Authorization 头——URL 中的令牌本身就是凭据——并返回该命名空间的 text/calendar 内容。未知令牌返回 404。

订阅源为每个已安排的任务（startTime）生成一个事件，为每个截止日期（dueDate）生成一个事件，与应用内日历视图保持一致：已完成、已归档、参考资料、已删除以及不在活动项目中的任务都会被排除；同一天既已安排又到期的任务只出现一次。事件仅包含稳定的 UID 和任务标题，不含描述、清单、附件、标签或项目信息。

MCP 适配器

已发布的 mindwtr-mcp 辅助程序可将自托管 Cloud 端点用作后端。通过 --cloud-url 和 --cloud-token，或 MINDWTR_MCP_CLOUD_URL / MINDWTR_MCP_CLOUD_TOKEN 环境变量配置。

Cloud 后端 MCP 模式读取 /v1/data，并提供任务、项目、分区、领域和人员的读取工具。使用 --write 后，任务、项目、分区和领域更改会经过上述逐资源 REST 端点；默认保持只读，也不会把 Mindwtr Cloud 本身变成托管 MCP 服务。

`cancelledAt`

Task 和 Project 的 cancelledAt 是带时区的可选 ISO 时间戳。设置它会取消并归档该记录。取消的任务没有 completedAt，也不会生成下一次重复任务；取消项目会保留已完成步骤，取消剩余待办。同步使用此字段前，请升级所有会写入数据的客户端。详见 GTD 工作流。

单独发送 cancelledAt: null 只会清除取消标记，不会重新激活。重新激活请显式设置非归档的 status。

社区集成

omarchy-mindwtr 是 ssalentin 开发并由社区维护的 Omarchy 状态栏插件。它提供支持键盘导航的任务面板，可通过 Cloud REST API 将任务收集到收件箱并标记任务完成。

使用该插件需要配备 Quickshell 的 Omarchy，以及可访问的自托管 Mindwtr Cloud 服务器和 Bearer 令牌。安装、配置和支持信息请参阅插件仓库，也可以参与讨论 #1308。

Cloud API ​

认证 ​

健康检查 ​

快照同步 ​

任务 ​

收集 ​

项目、领域与分区 ​

搜索 ​

附件 ​

日历订阅源 ​

MCP 适配器 ​

cancelledAt ​

社区集成 ​

相关页面 ​

Cloud API

认证

健康检查

快照同步

任务

收集

项目、领域与分区

搜索

附件

日历订阅源

MCP 适配器

`cancelledAt`

社区集成

相关页面