dodo/docs/api.md

API

Base path: /api/v1. 除初始化、登录和健康检查外均需 dodo_session Cookie。

Setup / Auth

• GET /setup/status
• POST /setup/initialize
• POST /auth/login
• POST /auth/logout
• GET /me

Folders

• GET /folders — 仅返回未删除文件夹
• POST /folders — 创建文件夹
• PATCH /folders/{folder_id} — 重命名
• DELETE /folders/{folder_id} — 软删除；其清单移到根层级

Lists

• GET /lists — 仅返回未删除清单，系统收集箱排首位
• POST /lists — 创建清单，可指定 folder_id
• PATCH /lists/{list_id} — 重命名；系统收集箱返回 409
• DELETE /lists/{list_id} — 软删除并将任务移入系统收集箱；系统收集箱返回 409

Tags

标签属于当前用户，可跨清单复用。

• GET /tags
• POST /tags — {name, color}；同一用户名称唯一

Tasks

• GET /tasks?q=&limit=&cursor= — 顶层未删除任务的游标分页；q 匹配标题、描述、标签名和清单名
• POST /tasks — 创建任务；parent_id 只允许指向同清单顶层任务；tag_ids 必须属于当前用户
• GET /tasks/{task_id} — 返回任务、标签和一层子任务
• PATCH /tasks/{task_id} — 必须携带当前 version，原子比较更新；版本冲突返回 409
• DELETE /tasks/{task_id} — 软删除任务及其直接子任务
• POST /tasks/{task_id}/restore — 恢复任务及其直接子任务
• POST /tasks/batch — 原子批量完成、移动、设置截止时间、替换标签或软删除

批量请求字段：task_ids、completed、list_id、due_at、tag_ids、soft_delete。所有任务、目标清单和标签在写入前完成归属校验；任一不存在则整批不修改。

Recycle bin

• GET /trash?limit=&cursor= — 已删除顶层任务的游标分页
• DELETE /trash/{task_id} — 永久删除任务及其子任务

游标是不透明字符串。无效游标返回 422；limit 范围为 1–100。

Health

• GET /health/live
• GET /health/ready