MoliTodo / API 文档

API 文档

MoliTodo 内置本地 REST API 服务器，为 AI Agent、自动化脚本和第三方工具提供任务管理接口。

基础 URL

http://127.0.0.1:1234

默认仅监听本地回环地址，端口可在设置中配置。

跨域支持

Access-Control-Allow-Origin: *

所有响应均包含 CORS 头，允许任意来源访问。

认证

None

无需认证。安全基于仅监听 localhost 的特性。

请求格式

application/json

请求体使用 JSON 格式，响应体同样为 JSON。

错误响应

{
  "success": false,
  "error": "<error message>"
}

任务状态流转

任务支持以下状态转换：

todo start doing
doing pause paused
paused start doing
todo complete done
doing complete done
paused complete done

智能分类

查询任务时可使用以下分类进行筛选：

字段 说明
inbox Status = todo AND no reminderTime
today Due today OR status = doing
doing Status = doing
paused Status = paused
planned Has a reminderTime
completed Status = done
all All tasks

接口列表

GET /

服务信息

返回 API 服务基本信息，包括名称、版本和相关链接。

请求示例

curl http://127.0.0.1:1234/

响应示例

{
  "name": "MoliTodo Local API",
  "version": "1.0.0",
  "baseUrl": "http://127.0.0.1:1234",
  "docsUrl": "http://127.0.0.1:1234/api/docs",
  "openApiUrl": "http://127.0.0.1:1234/api/openapi.json"
}
GET /api/health

健康检查

返回服务运行状态和当前时间戳，可用于检测服务是否可用。

请求示例

curl http://127.0.0.1:1234/api/health

响应示例

{
  "ok": true,
  "server": "MoliTodo Local API",
  "timestamp": "2026-05-03T10:30:00.000Z"
}
GET /api/lists

获取所有清单

返回所有清单列表，按 sortOrder 排序，默认清单始终排在第一位。

请求示例

curl http://127.0.0.1:1234/api/lists

响应示例

{
  "success": true,
  "data": [
    {
      "id": 0,
      "name": "默认清单",
      "color": "#007AFF",
      "icon": "inbox",
      "isDefault": true,
      "sortOrder": 0
    }
  ]
}
POST /api/lists

创建清单

创建一个新的任务清单，需指定名称，可选颜色和图标。

请求参数 (JSON Body)

字段 类型 必填 说明
name string 必填 1-50 characters, unique
color string 可选 HEX color, e.g. "#4F46E5"
icon string 可选 Icon name (list, inbox, star...)

请求示例

curl -X POST http://127.0.0.1:1234/api/lists \
  -H "Content-Type: application/json" \
  -d '{"name":"AI Tasks","color":"#4F46E5","icon":"star"}'

响应示例

{
  "success": true,
  "data": {
    "id": 1714725600000,
    "name": "AI Tasks",
    "color": "#4F46E5",
    "icon": "star",
    "isDefault": false,
    "sortOrder": 1
  }
}
GET /api/tasks

查询任务

查询任务列表。支持按状态、清单、分类、关键词筛选。默认返回未完成任务。

请求参数

字段 类型 必填 说明
status string 可选 todo | doing | paused | done
listId number 可选 Filter by list ID
category string 可选 inbox | today | doing | paused | planned | completed | all
query string 可选 Full-text search keyword
includeCompleted string 可选 "true" to include completed tasks

请求示例

# All incomplete tasks
curl http://127.0.0.1:1234/api/tasks

# Search by keyword
curl "http://127.0.0.1:1234/api/tasks?query=API"

# Filter by category
curl "http://127.0.0.1:1234/api/tasks?category=today"

# Combined filters
curl "http://127.0.0.1:1234/api/tasks?status=doing&listId=0"

响应示例

{
  "success": true,
  "data": [
    {
      "id": "m1abc2def3",
      "content": "Write API docs",
      "status": "todo",
      "completed": false,
      "createdAt": "2026-05-03T08:00:00.000Z",
      "reminderTime": null,
      "startedAt": null,
      "completedAt": null,
      "totalDuration": 0,
      "listId": 0,
      "metadata": {},
      "dueDate": null,
      "dueTime": null
    }
  ]
}
POST /api/tasks

创建任务

创建新任务。需指定内容，可选清单、提醒时间、截止日期等。

请求参数 (JSON Body)

字段 类型 必填 说明
content string 必填 Task content (non-empty)
listId number 可选 Target list ID (default: 0)
reminderTime string 可选 ISO 8601 datetime
dueDate string 可选 e.g. "2026-05-03"
dueTime string 可选 e.g. "18:00"
metadata object 可选 Free-form metadata object

请求示例

curl -X POST http://127.0.0.1:1234/api/tasks \
  -H "Content-Type: application/json" \
  -d '{"content":"Write API docs","listId":0,"dueDate":"2026-05-03","dueTime":"18:00"}'

响应示例

{
  "success": true,
  "data": {
    "id": "m1abc2def3",
    "content": "Write API docs",
    "status": "todo",
    "completed": false,
    "dueDate": "2026-05-03",
    "dueTime": "18:00",
    "listId": 0
  }
}
PATCH /api/tasks/:id

更新任务

部分更新任务字段。支持修改内容、状态、提醒时间、清单等。

请求参数 (JSON Body)

字段 类型 必填 说明
content string 可选 New task content
status string 可选 todo | doing | done
reminderTime string|null 可选 ISO 8601 or null to clear
listId number 可选 Move to different list
metadata object 可选 Merged with existing metadata

副作用: If reminderTime is included, existing reminder is cancelled and rescheduled.

请求示例

curl -X PATCH http://127.0.0.1:1234/api/tasks/TASK_ID \
  -H "Content-Type: application/json" \
  -d '{"content":"Updated title","metadata":{"priority":"high"}}'

响应示例

{
  "success": true,
  "data": { "id": "m1abc2def3", "content": "Updated title", ... }
}
DELETE /api/tasks/:id

删除任务

删除指定任务，同时取消该任务的提醒通知。任务不存在时静默返回成功。

副作用: Cancels any scheduled reminder for this task.

请求示例

curl -X DELETE http://127.0.0.1:1234/api/tasks/TASK_ID

响应示例

{ "success": true }
POST /api/tasks/:id/start

开始任务

将任务状态从待办或暂停转为进行中，记录开始时间。

请求示例

curl -X POST http://127.0.0.1:1234/api/tasks/TASK_ID/start

响应示例

{
  "success": true,
  "data": { "id": "m1abc2def3", "status": "doing", "startedAt": "..." }
}
POST /api/tasks/:id/pause

暂停任务

将进行中的任务暂停，累计已用时间，清除开始时间。

请求示例

curl -X POST http://127.0.0.1:1234/api/tasks/TASK_ID/pause

响应示例

{
  "success": true,
  "data": { "id": "m1abc2def3", "status": "paused", "totalDuration": 125000 }
}
POST /api/tasks/:id/complete

完成任务

完成任务，累计剩余工时，记录完成时间，取消提醒通知。

副作用: Accumulates remaining work time, records completion time, cancels reminder.

请求示例

curl -X POST http://127.0.0.1:1234/api/tasks/TASK_ID/complete

响应示例

{
  "success": true,
  "data": { "id": "m1abc2def3", "status": "done", "completed": true, "completedAt": "..." }
}

任务数据模型

任务对象包含以下字段：

字段 类型 说明
id string Base-36 encoded unique ID
content string Task content/title
status string todo | doing | paused | done
completed boolean true if status is done
createdAt string ISO 8601 creation time
updatedAt string ISO 8601 last update time
reminderTime string|null ISO 8601 reminder time
startedAt string|null When task was started
completedAt string|null When task was completed
totalDuration number Total work time in ms
listId number Parent list ID (0 = default)
metadata object Free-form metadata
dueDate string|null Due date, e.g. "2026-05-03"
dueTime string|null Due time, e.g. "18:00"
recurrence object|null Recurring task rule
seriesId string|null Links to parent series

使用说明

  • 1 写入操作前建议先读取当前任务状态。
  • 2 服务器仅监听 localhost，专为本地 AI Agent 和自动化工具设计。
  • 3 任务 ID 为 base-36 编码的时间戳加随机后缀。
  • 4 清单 ID 为毫秒时间戳，默认清单 ID 为 0。
  • 5 metadata 字段为自由格式对象，评论存储在 metadata.comment 中。