用途:通过 Workflowy 官方 REST API 访问、读取和修改 Workflowy 大纲。没有 MCP 连接器,需使用 curl 调用。
认证:每个请求都需请求头 Authorization: Bearer <API_KEY>。不要把密钥硬编码在技能或脚本中,调用时从环境变量 $WORKFLOWY_API_KEY 读取;若未设置,向用户索取密钥或让其执行 export WORKFLOWY_API_KEY=...。密钥在 https://workflowy.com/api-key 生成且不过期。基础地址为 https://workflowy.com/api/v1。
主要能力:列出子节点(GET /nodes,按 parent_id 查询)、读取单个节点(GET /nodes/:id)、导出全部(GET /nodes-export,扁平列表,含 completed 字段)、创建(POST /nodes,需 name)、更新(POST /nodes/:id,可改 name、note、layoutMode)、移动(POST /nodes/:id/move)、完成(POST /nodes/:id/complete)、取消完成(POST /nodes/:id/uncomplete)、删除(DELETE /nodes/:id,永久删除)、列出目标(GET /targets)。
节点模型:标准节点含 id、name、note、parent_id、priority、data、createdAt、modifiedAt、completedAt;完成状态由 completedAt(Unix 秒或 null)表示,标准响应无 completed 字段,导出节点额外含 completed 布尔值。parent_id 为 null 表示根级。GET /nodes 与 /nodes-export 返回无序,需按 priority(越小越前)排序并用 parent_id 重建树。
parent_id 与 :id 取值:完整节点 ID 或 URL 中的 12 位短 ID、Workflowy URL、用户自定义快捷键(用 GET /targets 发现)、"None"(根大纲)、"inbox"、"calendar"、"today"、"tomorrow"、"next_week",以及 "YYYY"、"YYYY-MM"、"YYYY-MM-DD" 日历日期。列出根级用 parent_id=None。日历目标在创建/移动时按需创建,列出时若不存在返回 404,读取只解析已存在节点。
Markdown:POST /nodes 与 POST /nodes/:id 会解析 name 中的 markdown。多行时首行成为节点,以 \n\n 分隔的行成为子节点(单个 \n 合并为空格)。支持 粗体、斜体、删除线、代码、文本、[YYYY-MM-DD]、[YYYY-MM-DD HH:MM]。布局前缀:# 为 h1、## 为 h2、### 为 h3、- [ ] / - [x] 为待办、``` 为代码块、> 为引用块,也可显式传 layoutMode。
查找内容:没有搜索 API。可用 GET /nodes-export 一次取全部(限 1 次/分钟)后客户端过滤,或已知父节点时用 GET /nodes 逐层遍历(调用更多但无导出速率限制)。
速率限制:GET /nodes-export 每分钟 1 次(响应较大);其他端点无文档化限制,但仍应避免紧密轮询。
创建参数:name(必填)、parent_id(可选)、note(可选)、position(可选,"top" 或 "bottom",默认 top)、layoutMode(可选:bullets、todo、h1、h2、h3、code-block、quote-block)。创建返回 {"item_id": "..."},更新/移动/完成/取消完成/删除返回 {"status": "ok"}。
限制与提示:猜测的地址如 https://workflowy.com/api/bullets/... 会返回营销 HTML 而非 JSON,务必使用 /api/v1/... 路径。可在 curl 中加 -w "\n[HTTP %{http_code}]\n" 显示状态码。官方文档:https://workflowy.com/api-reference/。