---
name: todoist-api
description: >-
  Work with Todoist tasks and projects through the official td CLI or Todoist API v1. Use for explicitly requested Todoist capture, triage, bulk edits, completed-work reports, or integration development. Do not activate for generic reminders or tasks in another system.
license: MIT. See LICENSE.txt
compatibility: Requires authorised Todoist access. Routine operations use the official @doist/todoist-cli package; API integrations use HTTPS and the project's supported SDK/runtime.
metadata:
  version: "3.0.0"
  reviewed: "2026-09-13"
title: todoist-api
canonical_url: https://skilld.dev/gh/tristanmanchester/agent-skills/todoist-api
last_updated: 2026-10-06T19:32:36.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [evals/scenarios.json](https://skilld.dev/api/skills-raw/tristanmanchester/agent-skills/todoist-api/evals/scenarios.json), [LICENSE.txt](https://skilld.dev/api/skills-raw/tristanmanchester/agent-skills/todoist-api/LICENSE.txt), [references/API_AND_BULK.md](https://skilld.dev/api/skills-raw/tristanmanchester/agent-skills/todoist-api/references/API_AND_BULK.md).
>
> If the user asked to install this Skill, run `npx skilld install tristanmanchester/agent-skills/todoist-api`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/todoist-api`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/tristanmanchester/agent-skills/todoist-api) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/todoist-api`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/todoist-api --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/todoist-api --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# Todoist workflows

Use the official CLI for routine operations. Use the public API only for a
specific integration or a gap confirmed in installed CLI help. Do not maintain
another complete client or silently switch the user's account/connection.

## Establish the surface

1. Prefer an already authorised Todoist connector when it exposes the requested
   operation. Otherwise inspect `td --version`, `td --help`, and `td auth status`.
2. The official package is `@doist/todoist-cli`, executable `td`. Installation and
   authentication change the host/account state; do them only as authorised.
3. Use OS credential storage, not a token in a command argument, report, or repo.
   `TODOIST_API_TOKEN` overrides stored credentials: check its presence without
   printing its value when the apparent account or permissions are wrong.
4. For read-only work, prefer read-only OAuth. CLI auth metadata is not proof
   that an externally supplied token has a particular scope.
5. Read the exact subcommand's help before use. Prefer its structured output;
   do not parse a human-formatted table or assume a flag exists across commands.

Doist maintains its own CLI skill (`td skill install universal`, or the relevant
agent target). Use that for exhaustive command syntax when available; installing
it is optional, not a prerequisite or permission to modify agent configuration.
This skill adds the resolution, bulk-change, and reconciliation workflow below.

## Resolve, execute, verify

```bash
td project list --json
td task list --project "Work" --json
td task view TASK_ID --json
```

Resolve names within their context: account/workspace, project, section, and
personal versus shared label. Preserve opaque string IDs. On duplicate names,
show the candidates; do not choose the first match. Never pass a `tmp-` client
placeholder to a server endpoint.

For an authorised capture, a simple example is:

```bash
td add "Email Chris tomorrow at 09:00 #Work @follow-up p2"
```

Read the resulting task and verify project, labels, parsed date/time, timezone,
and recurrence. Natural-language parsing is not proof the intended date was
stored. API priority numbering and user-facing `p1` notation are different;
verify their mapping rather than copying numbers between surfaces.

For edits, read current state, apply the requested change using installed help,
and read back the affected fields. Complete rather than permanently delete when
that matches the request. Completing a recurring occurrence and ending the
series are different operations; inspect the returned next due date.

## Bulk edits and recovery

Before bulk close/move/comment/delete, read
[API and bulk operations](https://skilld.dev/api/skills-raw/tristanmanchester/agent-skills/todoist-api/references/API_AND_BULK.md). Freeze an explicit set of
IDs and proposed changes, preview it, and apply that set rather than re-running
a changing filter. Existing user authorisation can cover the plan; CLI flags or
plan files cannot grant extra permission.

Keep an outcome ledger of confirmed successes, confirmed failures, and unknown
outcomes. A timeout after a write is **unknown**, not evidence that nothing
happened. Reconcile before retrying. Never restart an entire partially completed
batch or regenerate deduplication IDs on recovery.

## Reports and integration work

For completed-work reports, define the timezone and interval, and distinguish
completion time from due date. Follow all returned cursors needed for the
request, or label the result partial. Do not mistake a page size for total count.

For Sync API, attachments, templates, archived resources, or migration work, use
the reference only after confirming the live endpoint/SDK contract. The old
custom Python CLI and its flags are removed; there is no compatibility shim.

Return what was found/changed, stable IDs or provider-returned links, verification
performed, unresolved outcomes, and pagination boundaries. Do not claim a
successful connection, write, or report from a command example alone.

## Sources and checks

Reviewed 2026-09-13 against [Todoist API v1](https://developer.todoist.com/api/v1/)
and the [official CLI](https://github.com/Doist/todoist-cli). Installed help and
current endpoint documentation remain the authority for exact syntax.

Maintainers: run the scenarios in [evals/scenarios.json](https://skilld.dev/api/skills-raw/tristanmanchester/agent-skills/todoist-api/evals/scenarios.json)
against agent traces. They are evaluation cases, not a claim of live tests.