{"skill":{"slug":"todoist-api-skill","displayName":"Todoist API","summary":"Manages Todoist tasks, projects, sections, labels, comments, completed-task reports, activity logs, ID migration, project templates, and sync workflows throu...","description":"---\nname: todoist-api\ndescription: >-\n  Manages Todoist tasks, projects, sections, labels, comments, completed-task reports,\n  activity logs, ID migration, project templates, and sync workflows through Todoist API v1.\n  Use when the user asks to capture tasks, quick-add work, triage an inbox, resolve Todoist\n  names to IDs, bulk-close or move tasks, add repeated comments, review completed work,\n  manage project structure, export templates, or automate Todoist workflows.\nlicense: MIT. See LICENSE.txt\ncompatibility: Requires HTTPS access to api.todoist.com plus Python 3.9+ or curl. Write operations require a Todoist API token or OAuth access token.\nmetadata:\n  author: OpenAI\n  version: \"2.0.0\"\n  todoist_api: \"v1\"\n  last_reviewed: \"2026-03-05\"\n---\n\n# Todoist API\n\n## When to use this skill\n\nUse this skill when work involves **Todoist data or automation**, especially:\n\n- capture or quick-add new tasks\n- inspect, filter, move, complete, reopen, or delete tasks\n- manage projects, sections, labels, or comments\n- resolve human names to Todoist IDs before writing\n- perform safer bulk edits with dry-runs\n- review completed work or recent activity\n- build Todoist scripts, agents, or integrations around the public API\n\n## When not to use this skill\n\nDo **not** use this skill for:\n\n- editing the user’s local Todoist app UI directly\n- calendar-specific workflows that belong in a calendar skill\n- attachment upload flows that require multipart handling unless you are prepared to use `curl` or the `raw` escape hatch\n- non-Todoist task systems\n\n## Safety defaults\n\n- Start **read-only** if the user’s intent is ambiguous.\n- Resolve names to IDs before any write.\n- Prefer **close** over **delete** unless the user explicitly wants permanent removal.\n- Run `--dry-run` first for bulk or destructive work.\n- Use `--confirm` for bulk closes, moves, repeated comments, and deletes.\n- If a command may return a large payload, set `--output FILE` so stdout stays small and predictable.\n\n## Pick the smallest capable surface\n\n- **One object, one endpoint** → use a low-level REST wrapper such as `get-task`, `update-project`, or `get-comment`.\n- **Natural-language capture** → use `quick-add-task`.\n- **Resolve names safely** → use `resolve-project`, `resolve-section`, `resolve-label`.\n- **Create if missing** → use `ensure-project`, `ensure-section`, `ensure-label`.\n- **Many matching tasks** → use `bulk-close-tasks`, `bulk-move-tasks`, `bulk-comment-tasks`.\n- **Completed-work review** → use `report-completed` or `get-completed-tasks`.\n- **Full or incremental sync / batched writes** → use `sync`.\n- **Unwrapped or niche endpoint** → use `raw`.\n\n## Output contract\n\nThe main script prints structured output to stdout by default.\n\n- `--format json` returns a stable JSON envelope with fields like `action`, `ok`, `count`, `next_cursor`, `matched_count`, `changed_count`, and `resolved`.\n- `--format summary` returns a smaller human-readable summary.\n- `--output FILE` writes the full output to a file and prints a small JSON notice to stdout.\n\nThis is designed for agent pipelines: stdout stays parseable, stderr carries diagnostics, and retries are built in for transient failures.\n\n## Scripts\n\n- **`scripts/todoist_api.py`** — main non-interactive Todoist CLI\n- **`scripts/smoke_test.py`** — read-only connectivity check\n\nInspect help first:\n\n```bash\npython3 scripts/todoist_api.py --help\npython3 scripts/todoist_api.py get-tasks-by-filter --help\npython3 scripts/todoist_api.py bulk-move-tasks --help\npython3 scripts/smoke_test.py --help\n```\n\n## Quick start\n\nSet a token:\n\n```bash\nexport TODOIST_API_TOKEN=\"YOUR_TODOIST_TOKEN\"\n```\n\nRead-only smoke test:\n\n```bash\npython3 scripts/smoke_test.py\n```\n\nSanity-check access:\n\n```bash\npython3 scripts/todoist_api.py get-projects --limit 5\npython3 scripts/todoist_api.py get-labels --limit 10\n```\n\nResolve names before writes:\n\n```bash\npython3 scripts/todoist_api.py resolve-project --name \"Inbox\"\npython3 scripts/todoist_api.py resolve-section --project-name \"Client Alpha\" --name \"Next Actions\"\npython3 scripts/todoist_api.py resolve-label --name \"waiting-on\"\n```\n\n## High-value agent workflows\n\n### Quick add\n\n```bash\npython3 scripts/todoist_api.py quick-add-task \\\n  --text \"Email Chris tomorrow at 09:00 #Work @follow-up p2\"\n```\n\n### Create-if-missing section\n\n```bash\npython3 scripts/todoist_api.py ensure-section \\\n  --project-name \"Client Alpha\" \\\n  --name \"Next Actions\"\n```\n\n### Preview a bulk close\n\n```bash\npython3 scripts/todoist_api.py bulk-close-tasks \\\n  --filter \"overdue & @errands\" \\\n  --dry-run\n```\n\n### Execute the same bulk close\n\n```bash\npython3 scripts/todoist_api.py bulk-close-tasks \\\n  --filter \"overdue & @errands\" \\\n  --confirm\n```\n\n### Move matching tasks into a resolved section\n\n```bash\npython3 scripts/todoist_api.py bulk-move-tasks \\\n  --filter \"#Inbox & !recurring\" \\\n  --target-project-name \"Work\" \\\n  --target-section-name \"Next Actions\" \\\n  --dry-run\n```\n\n### Report completed work\n\n```bash\npython3 scripts/todoist_api.py report-completed \\\n  --since \"2026-03-01T00:00:00Z\" \\\n  --until \"2026-03-31T23:59:59Z\" \\\n  --by completion \\\n  --output reports/march-completed.json\n```\n\n## Recommended operating pattern\n\n1. **Resolve or list** the target object.\n2. **Read current state** with a low-level getter.\n3. **Preview** the write with `--dry-run`.\n4. **Execute** with `--confirm` when needed.\n5. **Verify** by re-reading or by running a report command.\n\n## Feature index\n\n- **Command catalogue and endpoint coverage** → [references/REFERENCE.md](references/REFERENCE.md)\n- **Task-first recipes** → [references/RECIPES.md](references/RECIPES.md)\n- **Todoist-specific caveats** → [references/GOTCHAS.md](references/GOTCHAS.md)\n\n## Escape hatches\n\nUse `raw` when the public CLI surface does not yet wrap a needed endpoint:\n\n```bash\npython3 scripts/todoist_api.py raw \\\n  --method GET \\\n  --path /projects/PROJECT_ID/full\n```\n\nUse `sync` when you need incremental sync or batched commands:\n\n```bash\npython3 scripts/todoist_api.py sync \\\n  --sync-token '*' \\\n  --resource-types '[\"all\"]'\n```\n","topics":["Sync"],"tags":{"latest":"1.0.0"},"stats":{"comments":0,"downloads":711,"installsAllTime":26,"installsCurrent":0,"stars":0,"versions":1},"createdAt":1772709289241,"updatedAt":1779077696462},"latestVersion":{"version":"1.0.0","createdAt":1772709289241,"changelog":"Initial public release with CLI and references for robust Todoist automation.\n\n- Adds a command-line Todoist API client (scripts/todoist_api.py) with coverage for core resources, bulk/batched operations, and safe-agent workflows.\n- Includes smoke test for read-only connectivity (scripts/smoke_test.py).\n- Provides detailed user and agent documentation: reference, recipes, and gotchas for real-world Todoist automation.\n- Features name resolution, dry-run/confirm modes, and bulk operation safety defaults.\n- Supports output in JSON or summary format, with optional file output for large results.\n- Assets for sync and review templates included for advanced Todoist workflows.","license":null},"metadata":null,"owner":{"handle":"tristanmanchester","userId":"s17c3xv8wvvzzbj84z9vcj498n83gnkp","displayName":"Tristan Manchester","image":"https://avatars.githubusercontent.com/u/108270628?v=4"},"moderation":null}