Todoist Api

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

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

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

Gotchas

Table of contents

• Opaque IDs
• Search first, then write
• Archived objects
• Pagination and bounded output
• Retry behaviour
• Bulk safety
• Legacy naming in sync
• Template and upload gaps
• Task and project deep links
• Plan-gated features

Opaque IDs

Todoist IDs are opaque strings in API v1. Do not assume integers or sortable sequences.

What to do:

• keep IDs as strings
• do not coerce to integers
• use ids-map when migrating from older stored IDs
• prefer resolve-* commands when starting from names

Search first, then write

Names are not stable IDs.

Safe pattern:

1. resolve or search the object 2. inspect the current object 3. preview the change 4. execute the change 5. verify

This matters most for:

• shared projects
• sections with repeated names across projects
• labels that may exist as personal or shared labels

Archived objects

Archived projects and sections usually need explicit inclusion during resolution.

Examples:

python3 scripts/todoist_api.py resolve-project --name "Archive" --include-archived
python3 scripts/todoist_api.py resolve-section --project-name "Old Client" --name "Done" --include-archived

Pagination and bounded output

Many Todoist endpoints are cursor-paginated.

Use:

• --limit for page size
• --cursor for the next page
• --all to drain the cursor chain
• --max-items to stop early
• --output FILE for very large payloads

If you only need a quick answer, prefer a small first page before loading everything.

Retry behaviour

The CLI retries transient failures by default.

Built-in defaults:

• retry on 429, 500, 502, 503, 504
• honour Retry-After / error_extra.retry_after when available
• exponential backoff from --retry-backoff

Tune when needed:

python3 scripts/todoist_api.py get-projects --retry 4 --retry-backoff 2

Bulk safety

Bulk commands are designed for agents, not manual shell heroics.

Rules:

• bulk-close-tasks, bulk-move-tasks, and bulk-comment-tasks require --dry-run or --confirm
• they return counts and explicit change lists
• they skip tasks already at the destination in bulk-move-tasks
• they do not guess ambiguous names

Legacy naming in sync

Todoist API v1 uses current names in top-level REST endpoints, but /sync still carries some legacy object names.

Examples you will still see in sync payloads:

• items where REST uses tasks
• notes where REST uses comments

If a task is small and single-purpose, prefer the modern REST wrapper. Use sync only when batching or incremental sync is the real goal.

Template and upload gaps

The main wrapper intentionally avoids full multipart upload support.

Use raw or curl for:

• file uploads
• attachment workflows
• template import from file
• template export as file download

This keeps the main agent surface deterministic and non-fragile.

Task and project deep links

The script adds todoist://task?id=... links to task objects where practical and todoist://project?id=... links to project objects where practical. These are useful when the next step is “open this object in Todoist”.

Plan-gated features

Some Todoist API capabilities depend on the authenticated user’s plan or token scopes.

Watch for this especially around:

• reminders and other premium features
• backups
• uploads and upload limits
• template import/export availability in the user plan

Recipes

Table of contents

• Inbox triage
• Quick capture from natural language
• Project setup
• Weekly review
• Overdue clean-up
• Audit trail comments
• Shared project assignment prep
• Legacy ID migration
• Template export

Inbox triage

Preview what is currently in a project:

python3 scripts/todoist_api.py resolve-project --name "Inbox"
python3 scripts/todoist_api.py get-tasks --project-id PROJECT_ID --all

Move non-recurring inbox work into a target section:

python3 scripts/todoist_api.py bulk-move-tasks \
  --filter "#Inbox & !recurring" \
  --target-project-name "Work" \
  --target-section-name "Next Actions" \
  --dry-run

Then execute:

python3 scripts/todoist_api.py bulk-move-tasks \
  --filter "#Inbox & !recurring" \
  --target-project-name "Work" \
  --target-section-name "Next Actions" \
  --confirm

Quick capture from natural language

For user requests that already sound like Todoist input, prefer quick add:

python3 scripts/todoist_api.py quick-add-task \
  --text "Pay electricity bill next Tuesday 18:00 #Admin @finance p2"

This is usually better than manually constructing create-task payloads when the user already phrased dates, labels, and priorities naturally.

Project setup

Create a project if needed:

python3 scripts/todoist_api.py ensure-project \
  --name "Client Alpha" \
  --description "Delivery work"

Create standard sections:

python3 scripts/todoist_api.py ensure-section --project-name "Client Alpha" --name "Next Actions"
python3 scripts/todoist_api.py ensure-section --project-name "Client Alpha" --name "Waiting"
python3 scripts/todoist_api.py ensure-section --project-name "Client Alpha" --name "Done"

Optionally seed tasks via /sync:

python3 scripts/todoist_api.py sync \
  --commands-file assets/sync/seed-project.json \
  --dry-run

Weekly review

Get completed work for the last week:

python3 scripts/todoist_api.py report-completed \
  --since "2026-03-01T00:00:00Z" \
  --until "2026-03-07T23:59:59Z" \
  --by completion \
  --output reports/weekly-review.json

Get recent activity for one project:

python3 scripts/todoist_api.py get-activities \
  --parent-project-id PROJECT_ID \
  --all \
  --output reports/weekly-activity.json

Overdue clean-up

Preview overdue work:

python3 scripts/todoist_api.py get-tasks-by-filter \
  --query "overdue" \
  --all

Preview closing all overdue errands:

python3 scripts/todoist_api.py bulk-close-tasks \
  --filter "overdue & @errands" \
  --dry-run

If the user confirms that completed/irrelevant errands should be closed, execute with --confirm.

Audit trail comments

Add a comment to every matching urgent task:

python3 scripts/todoist_api.py bulk-comment-tasks \
  --filter "today & p1" \
  --content "Reviewed during daily planning." \
  --dry-run

This is useful when an agent needs to leave a trace explaining a bulk review, escalation, or triage pass.

Shared project assignment prep

Resolve collaborators before assigning:

python3 scripts/todoist_api.py get-project-collaborators --project-id PROJECT_ID

Then update a task with the selected collaborator ID:

python3 scripts/todoist_api.py update-task \
  --task-id TASK_ID \
  --assignee-id USER_ID \
  --dry-run

Legacy ID migration

When the user has old cached IDs or data from an older integration:

python3 scripts/todoist_api.py ids-map \
  --object-name tasks \
  --ids 918273645,918273646

Repeat for projects, sections, or comments as needed.

Template export

Get a shareable template URL from an existing project:

python3 scripts/todoist_api.py template-export-url \
  --project-id PROJECT_ID

If the user wants a full downloadable template file or a file-based import, switch to raw or curl, because those flows are not fully wrapped here.

Reference

Table of contents

• Command families
• Global flags
• Result envelope
• Name-resolution commands
• Ensure commands
• Bulk commands
• Low-level wrappers
• Escape hatches
• Coverage notes
• Quick grep targets

Command families

Read/list/search

• get-projects
• get-archived-projects
• search-projects
• get-project
• get-project-collaborators
• get-project-full
• get-sections
• get-archived-sections
• search-sections
• get-section
• get-labels
• get-shared-labels
• search-labels
• get-label
• get-tasks
• get-tasks-by-filter
• get-task
• get-completed-tasks
• get-completed-stats
• get-comments
• get-comment
• get-activities
• ids-map
• get-backups
• template-export-url

Write one object

• create-project
• update-project
• delete-project
• archive-project
• unarchive-project
• create-section
• update-section
• delete-section
• archive-section
• unarchive-section
• create-label
• update-label
• delete-label
• quick-add-task
• create-task
• update-task
• move-task
• close-task
• reopen-task
• delete-task
• create-comment
• update-comment
• delete-comment
• get-or-create-email
• disable-email

Agent-friendly helpers

• resolve-project
• resolve-section
• resolve-label
• ensure-project
• ensure-section
• ensure-label
• bulk-close-tasks
• bulk-move-tasks
• bulk-comment-tasks
• report-completed

Escape hatches

• sync
• raw

Global flags

Available on the main script:

• --token — explicit Todoist token
• --base-url — override API base URL
• --timeout — request timeout
• --retry — retries for 429/5xx/network failures
• --retry-backoff — initial backoff in seconds
• --format json|summary
• --output FILE|-
• --verbose

For paginated commands:

• --limit
• --cursor
• --all
• --max-items

For write commands:

• --dry-run
• --confirm for bulk and destructive operations

Result envelope

Default output is a stable JSON envelope.

Typical read:

{
  "ok": true,
  "action": "get-projects",
  "dry_run": false,
  "count": 3,
  "next_cursor": null,
  "data": {
    "results": [
      {"id": "abc", "name": "Inbox"},
      {"id": "def", "name": "Work"}
    ],
    "next_cursor": null
  }
}

Typical resolver:

{
  "ok": true,
  "action": "resolve-section",
  "dry_run": false,
  "data": {
    "id": "6fFPHV272WWh3gpW",
    "project_id": "6XGgm6PHrGgMpCFX",
    "name": "Next Actions"
  }
}

Typical bulk preview:

{
  "ok": true,
  "action": "bulk-move-tasks",
  "dry_run": true,
  "matched_count": 5,
  "changed_count": 4,
  "skipped_count": 1,
  "resolved": {
    "filter": "#Inbox & !recurring",
    "project_id": "6XGgm6PHrGgMpCFX",
    "section_id": "6fFPHV272WWh3gpW"
  },
  "data": [
    {
      "task_id": "6XGgmFVcrG5RRjVr",
      "from_project_id": "old-project",
      "to_project_id": "6XGgm6PHrGgMpCFX",
      "to_section_id": "6fFPHV272WWh3gpW"
    }
  ]
}

Name-resolution commands

These commands are the safest way to bridge from user language to Todoist IDs.

Resolve a project

python3 scripts/todoist_api.py resolve-project --name "Inbox"
python3 scripts/todoist_api.py resolve-project --name "Archive" --include-archived
python3 scripts/todoist_api.py resolve-project --name "Client Alpha" --strict

Resolve a section within a project scope

python3 scripts/todoist_api.py resolve-section \
  --project-name "Client Alpha" \
  --name "Next Actions"

Resolve a shared label too

python3 scripts/todoist_api.py resolve-label \
  --name "blocked" \
  --include-shared

Resolution rules:

1. exact case-insensitive name 2. if --strict is absent, unique prefix match 3. if still unresolved, unique substring match 4. otherwise fail loudly with candidate details

Ensure commands

These commands are useful for idempotent agents.

Ensure a project exists

python3 scripts/todoist_api.py ensure-project --name "Client Alpha"

Ensure a project and patch a few fields if it already exists

python3 scripts/todoist_api.py ensure-project \
  --name "Client Alpha" \
  --description "Delivery work" \
  --color blue \
  --update-existing \
  --dry-run

Ensure a section within a resolved project

python3 scripts/todoist_api.py ensure-section \
  --project-name "Client Alpha" \
  --name "Waiting" \
  --update-existing \
  --dry-run

Ensure a label exists

python3 scripts/todoist_api.py ensure-label \
  --name "waiting-on" \
  --color berry_red

Bulk commands

Close all matching tasks

python3 scripts/todoist_api.py bulk-close-tasks \
  --filter "overdue & @errands" \
  --dry-run

Move all matching tasks

python3 scripts/todoist_api.py bulk-move-tasks \
  --filter "#Inbox & !recurring" \
  --target-project-name "Work" \
  --target-section-name "Next Actions" \
  --dry-run

Add the same comment to all matching tasks

python3 scripts/todoist_api.py bulk-comment-tasks \
  --filter "today & p1" \
  --content "Reviewed during morning triage." \
  --dry-run

Bulk commands are intentionally conservative:

• they always require --dry-run or --confirm
• they respect --max-items
• they return matched_count, changed_count, skipped_count
• they fail name resolution instead of guessing

Low-level wrappers

Projects

python3 scripts/todoist_api.py get-projects --all
python3 scripts/todoist_api.py get-project --project-id PROJECT_ID
python3 scripts/todoist_api.py get-project-full --project-id PROJECT_ID --output project-full.json
python3 scripts/todoist_api.py archive-project --project-id PROJECT_ID --dry-run

Sections

python3 scripts/todoist_api.py get-sections --project-id PROJECT_ID --all
python3 scripts/todoist_api.py update-section --section-id SECTION_ID --name "Later" --dry-run

Labels

python3 scripts/todoist_api.py get-labels --all
python3 scripts/todoist_api.py get-shared-labels
python3 scripts/todoist_api.py update-label --label-id LABEL_ID --color blue --dry-run

Tasks

python3 scripts/todoist_api.py get-tasks --project-id PROJECT_ID --all
python3 scripts/todoist_api.py get-tasks-by-filter --query "today & !recurring" --lang en --all
python3 scripts/todoist_api.py quick-add-task --text "Email Jess tomorrow 09:00 #Personal"
python3 scripts/todoist_api.py update-task --task-id TASK_ID --priority 1 --dry-run
python3 scripts/todoist_api.py move-task --task-id TASK_ID --section-id SECTION_ID --dry-run

Comments

python3 scripts/todoist_api.py get-comments --task-id TASK_ID --all
python3 scripts/todoist_api.py create-comment --task-id TASK_ID --content "Waiting on review" --dry-run

Reporting and utilities

python3 scripts/todoist_api.py report-completed \
  --since "2026-03-01T00:00:00Z" \
  --until "2026-03-31T23:59:59Z"

python3 scripts/todoist_api.py get-activities --parent-project-id PROJECT_ID --all
python3 scripts/todoist_api.py ids-map --object-name tasks --ids 918273645,918273646
python3 scripts/todoist_api.py get-or-create-email --obj-type task --obj-id TASK_ID --dry-run
python3 scripts/todoist_api.py template-export-url --project-id PROJECT_ID

Escape hatches

sync

Use this when the work is inherently batched or when you need incremental sync:

python3 scripts/todoist_api.py sync \
  --sync-token '*' \
  --resource-types '["all"]'

Preview sync commands:

python3 scripts/todoist_api.py sync \
  --commands-file assets/sync/seed-project.json \
  --dry-run

raw

Use this for niche endpoints or temporary gaps in the wrapper:

python3 scripts/todoist_api.py raw \
  --method GET \
  --path /projects/PROJECT_ID/full

python3 scripts/todoist_api.py raw \
  --method GET \
  --path /activities \
  --query parent_project_id=PROJECT_ID \
  --all

Coverage notes

Wrapped directly in V2:

• projects, archived projects, collaborators, project full
• sections, archived sections
• labels and shared labels
• tasks, task filter, quick add, move, close, reopen, completed tasks, completed stats
• comments
• activities
• ID mapping
• backups list
• task/project email creation and disable
• template export URL
• sync/raw escape hatches
• name resolution, ensure, bulk close/move/comment, completed report

Still best handled with raw or curl:

• multipart uploads
• template import from file
• template export as file download
• attachment upload and comment attachment wiring
• any very new endpoint not yet exposed by the CLI

Quick grep targets

Useful search terms for this reference set:

grep -n "bulk-" references/REFERENCE.md
grep -n "ensure-" references/REFERENCE.md
grep -n "completed" references/REFERENCE.md
grep -n "ids-map" references/REFERENCE.md
grep -n "template" references/REFERENCE.md