Todoist API

When to use this skill

Use this skill when work involves Todoist data or automation, especially:

capture or quick-add new tasks
inspect, filter, move, complete, reopen, or delete tasks
manage projects, sections, labels, or comments
resolve human names to Todoist IDs before writing
perform safer bulk edits with dry-runs
review completed work or recent activity
build Todoist scripts, agents, or integrations around the public API

When not to use this skill

Do not use this skill for:

editing the user’s local Todoist app UI directly
calendar-specific workflows that belong in a calendar skill
attachment upload flows that require multipart handling unless you are prepared to use curl or the raw escape hatch
non-Todoist task systems

Safety defaults

Start read-only if the user’s intent is ambiguous.
Resolve names to IDs before any write.
Prefer close over delete unless the user explicitly wants permanent removal.
Run --dry-run first for bulk or destructive work.
Use --confirm for bulk closes, moves, repeated comments, and deletes.
If a command may return a large payload, set --output FILE so stdout stays small and predictable.

Pick the smallest capable surface

One object, one endpoint → use a low-level REST wrapper such as get-task, update-project, or get-comment.
Natural-language capture → use quick-add-task.
Resolve names safely → use resolve-project, resolve-section, resolve-label.
Create 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 report-completed or get-completed-tasks.
Full or incremental sync / batched writes → use sync.
Unwrapped or niche endpoint → use 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 CLI
scripts/smoke_test.py — read-only connectivity check

Inspect 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

Resolve or list the target object.
Read current state with a low-level getter.
Preview the write with --dry-run.
Execute with --confirm when needed.
Verify by re-reading or by running a report command.

Feature index

Command catalogue and endpoint coverage → references/REFERENCE.md
Task-first recipes → references/RECIPES.md
Todoist-specific caveats → references/GOTCHAS.md

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"]'

todoist-api