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

Tasks

• GET /tasks?q=&limit=&cursor= — 顶层未删除任务的游标分页；q 匹配标题、描述和清单名
• POST /tasks — 创建任务；parent_id 只允许指向同清单顶层任务
• 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、soft_delete。所有任务和目标清单在写入前完成归属校验；任一不存在则整批不修改。

Countdowns

• GET /countdowns?archived=false — 查询倒数日；置顶项优先，其余按下一次发生日期排序
• POST /countdowns — 创建倒数日、纪念日或生日；支持 none/weekly/monthly/yearly 重复
• PATCH /countdowns/{countdown_id} — 编辑名称、日期、类型、重复与图标
• POST /countdowns/{countdown_id}/pin — 单一置顶，自动取消其他置顶项
• DELETE /countdowns/{countdown_id} — 归档
• POST /countdowns/{countdown_id}/restore — 恢复归档项
• DELETE /countdowns/{countdown_id}/purge — 永久删除已归档项

Recycle bin

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

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

Health

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