Todoist API

Todoist API When to use this 技能

Use this 技能 when work involves Todoist data or 自动化, especially:

capture or quick-添加 new tasks inspect, 过滤器, move, complete, reopen, or 删除 tasks manage projects, sections, labels, or comments resolve human names to Todoist IDs before writing perform safer bulk edits with dry-运行s review completed work or recent activity build Todoist scripts, 代理s, or integrations around the public API When not to use this 技能

Do not use this 技能 for:

editing the user’s local Todoist 应用 UI directly calendar-specific 工作流s that belong in a calendar 技能 attachment 上传 flows that require multipart handling unless you are prepared to use curl or the raw escape hatch non-Todoist task 系统s Safety defaults 启动 read-only if the user’s intent is ambiguous. Resolve names to IDs before any write. Prefer close over 删除 unless the user explicitly wants permanent removal. 运行 --dry-运行 first for bulk or destructive work. Use --confirm for bulk closes, moves, repeated comments, and 删除s. If a command may return a large payload, 设置 --输出 FILE so stdout stays small and predictable. Pick the smallest capable surface One object, one 端点 → use a low-level REST wr应用er such as 获取-task, 更新-project, or 获取-comment. Natural-language capture → use quick-添加-task. Resolve names safely → use resolve-project, resolve-section, resolve-label. 创建 if missing → use ensure-project, ensure-section, ensure-label. Many matching tasks → use bulk-close-tasks, bulk-move-tasks, bulk-comment-tasks. Completed-work review → use 报告-completed or 获取-completed-tasks. Full or incremental 同步 / batched writes → use 同步. Unwr应用ed or niche 端点 → use raw. 输出 contract

The mAIn script prints structured 输出 to stdout by default.

--格式化 json returns a stable JSON envelope with fields like action, ok, count, next_cursor, matched_count, changed_count, and resolved. --格式化 summary returns a smaller human-readable summary. --输出 FILE writes the full 输出 to a file and prints a small JSON notice to stdout.

This is de签名ed for 代理 流水线s: stdout stays 解析able, stderr carries diagnostics, and retries are built in for transient 失败s.

Scripts scripts/todoist_API.py — mAIn non-interactive Todoist 命令行工具 scripts/smoke_test.py — read-only connectivity 检查

Inspect help first:

python3 scripts/todoist_API.py --help python3 scripts/todoist_API.py 获取-tasks-by-过滤器 --help python3 scripts/todoist_API.py bulk-move-tasks --help python3 scripts/smoke_test.py --help

Quick 启动

设置 a 令牌:

导出 TODOIST_API_令牌="YOUR_TODOIST_令牌"

Read-only smoke test:

python3 scripts/smoke_test.py

Sanity-检查 访问:

python3 scripts/todoist_API.py 获取-projects --limit 5 python3 scripts/todoist_API.py 获取-labels --limit 10

Resolve names before writes:

python3 scripts/todoist_API.py resolve-project --name "Inbox" python3 scripts/todoist_API.py resolve-section --project-name "命令行工具ent Alpha" --name "Next Actions" python3 scripts/todoist_API.py resolve-label --name "wAIting-on"

High-value 代理 工作流s Quick 添加 python3 scripts/todoist_API.py quick-添加-task \ --text "EmAIl Chris tomorrow at 09:00 #Work @follow-up p2"

创建-if-missing section python3 scripts/todoist_API.py ensure-section \ --project-name "命令行工具ent Alpha" \ --name "Next Actions"

Preview a bulk close python3 scripts/todoist_API.py bulk-close-tasks \ --过滤器 "overdue & @errands" \ --dry-运行

执行 the same bulk close python3 scripts/todoist_API.py bulk-close-tasks \ --过滤器 "overdue & @errands" \ --confirm

Move matching tasks into a resolved section python3 scripts/todoist_API.py bulk-move-tasks \ --过滤器 "#Inbox & !recurring" \ --tar获取-project-name "Work" \ --tar获取-section-name "Next Actions" \ --dry-运行

报告 completed work python3 scripts/todoist_API.py 报告-completed \ --since "2026-03-01T00:00:00Z" \ --until "2026-03-31T23:59:59Z" \ --by completion \ --输出 报告s/march-completed.json

Recommended operating pattern Resolve or 列出 the tar获取 object. Read current 状态 with a low-level 获取ter. Preview the write with --dry-运行. 执行 with --confirm when needed. 验证 by re-reading or by 运行ning a 报告 command. Feature 索引 Command cata记录ue and 端点 coverage → references/REFERENCE.md Task-first recipes → references/RECIPES.md Todoist-specific caveats → references/GOTCHAS.md Escape hatches

Use raw when the public 命令行工具 surface does not yet wrap a needed 端点:

python3 scripts/todoist_API.py raw \ --method 获取 \ --path /projects/PROJECT_ID/full

Use 同步 when you need incremental 同步 or batched commands:

python3 scripts/todoist_API.py 同步 \ --同步-令牌 '*' \ --resource-types '["all"]'