todoist-api

What this skill does

# 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:

```bash
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:

```bash
export TODOIST_API_TOKEN="YOUR_TODOIST_TOKEN"
```

Read-only smoke test:

```bash
python3 scripts/smoke_test.py
```

Sanity-check access:

```bash
python3 scripts/todoist_api.py get-projects --limit 5
python3 scripts/todoist_api.py get-labels --limit 10
```

Resolve names before writes:

```bash
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

```bash
python3 scripts/todoist_api.py quick-add-task \
  --text "Email Chris tomorrow at 09:00 #Work @follow-up p2"
```

### Create-if-missing section

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

### Preview a bulk close

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

### Execute the same bulk close

```bash
python3 scripts/todoist_api.py bulk-close-tasks \
  --filter "overdue & @errands" \
  --confirm
```

### Move matching tasks into a resolved section

```bash
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

```bash
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](references/REFERENCE.md)
- **Task-first recipes** → [references/RECIPES.md](references/RECIPES.md)
- **Todoist-specific caveats** → [references/GOTCHAS.md](references/GOTCHAS.md)

## Escape hatches

Use `raw` when the public CLI surface does not yet wrap a needed endpoint:

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

Use `sync` when you need incremental sync or batched commands:

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