Todoist API
by @tristanmanchester
Manages Todoist tasks, projects, sections, labels, comments, completed-task reports, activity logs, ID migration, project templates, and sync workflows throu...
clawhub install todoist-api-skillπ About This Skill
name: todoist-api description: >- Manages Todoist tasks, projects, sections, labels, comments, completed-task reports, activity logs, ID migration, project templates, and sync workflows through Todoist API v1. Use when the user asks to capture tasks, quick-add work, triage an inbox, resolve Todoist names to IDs, bulk-close or move tasks, add repeated comments, review completed work, manage project structure, export templates, or automate Todoist workflows. license: MIT. See LICENSE.txt compatibility: Requires HTTPS access to api.todoist.com plus Python 3.9+ or curl. Write operations require a Todoist API token or OAuth access token. metadata: author: OpenAI version: "2.0.0" todoist_api: "v1" last_reviewed: "2026-03-05"
Todoist API
When to use this skill
Use this skill when work involves Todoist data or automation, especially:
When not to use this skill
Do not use this skill for:
curl or the raw escape hatchSafety defaults
--dry-run first for bulk or destructive work.--confirm for bulk closes, moves, repeated comments, and deletes.--output FILE so stdout stays small and predictable.Pick the smallest capable surface
get-task, update-project, or get-comment.quick-add-task.resolve-project, resolve-section, resolve-label.ensure-project, ensure-section, ensure-label.bulk-close-tasks, bulk-move-tasks, bulk-comment-tasks.report-completed or get-completed-tasks.sync.raw.Output contract
The main script prints structured output to stdout by default.
--format json returns a stable JSON envelope with fields like action, ok, count, next_cursor, matched_count, changed_count, and resolved.--format summary returns a smaller human-readable summary.--output FILE writes the full output to a file and prints a small JSON notice to stdout.This is designed for agent pipelines: stdout stays parseable, stderr carries diagnostics, and retries are built in for transient failures.
Scripts
scripts/todoist_api.py β main non-interactive Todoist CLIscripts/smoke_test.py β read-only connectivity checkInspect help first:
python3 scripts/todoist_api.py --help
python3 scripts/todoist_api.py get-tasks-by-filter --help
python3 scripts/todoist_api.py bulk-move-tasks --help
python3 scripts/smoke_test.py --help
Quick start
Set a token:
export TODOIST_API_TOKEN="YOUR_TODOIST_TOKEN"
Read-only smoke test:
python3 scripts/smoke_test.py
Sanity-check access:
python3 scripts/todoist_api.py get-projects --limit 5
python3 scripts/todoist_api.py get-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 "Client Alpha" --name "Next Actions"
python3 scripts/todoist_api.py resolve-label --name "waiting-on"
High-value agent workflows
Quick add
python3 scripts/todoist_api.py quick-add-task \
--text "Email Chris tomorrow at 09:00 #Work @follow-up p2"
Create-if-missing section
python3 scripts/todoist_api.py ensure-section \
--project-name "Client Alpha" \
--name "Next Actions"
Preview a bulk close
python3 scripts/todoist_api.py bulk-close-tasks \
--filter "overdue & @errands" \
--dry-run
Execute the same bulk close
python3 scripts/todoist_api.py bulk-close-tasks \
--filter "overdue & @errands" \
--confirm
Move matching tasks into a resolved section
python3 scripts/todoist_api.py bulk-move-tasks \
--filter "#Inbox & !recurring" \
--target-project-name "Work" \
--target-section-name "Next Actions" \
--dry-run
Report completed work
python3 scripts/todoist_api.py report-completed \
--since "2026-03-01T00:00:00Z" \
--until "2026-03-31T23:59:59Z" \
--by completion \
--output reports/march-completed.json
Recommended operating pattern
1. Resolve or list the target object.
2. Read current state with a low-level getter.
3. Preview the write with --dry-run.
4. Execute with --confirm when needed.
5. Verify by re-reading or by running a report command.
Feature index
Escape hatches
Use raw when the public CLI surface does not yet wrap a needed endpoint:
python3 scripts/todoist_api.py raw \
--method GET \
--path /projects/PROJECT_ID/full
Use sync when you need incremental sync or batched commands:
python3 scripts/todoist_api.py sync \
--sync-token '*' \
--resource-types '["all"]'
π‘ Examples
Set a token:
export TODOIST_API_TOKEN="YOUR_TODOIST_TOKEN"
Read-only smoke test:
python3 scripts/smoke_test.py
Sanity-check access:
python3 scripts/todoist_api.py get-projects --limit 5
python3 scripts/todoist_api.py get-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 "Client Alpha" --name "Next Actions"
python3 scripts/todoist_api.py resolve-label --name "waiting-on"