Registry / crm-productivity / todoist-api-python

todoist-api-python

library4.0.0pypypi✓ verified 84d ago

The official Python SDK for interacting with the Todoist API. It provides synchronous and asynchronous clients to manage tasks, projects, labels, filters, and more. The current stable version is 4.0.0, and it generally receives updates aligned with API changes and new features from Todoist.

crm-productivity http-networking

pip install todoist-api-python

github ↗package ↗homepage ↗docs ↗

INSTALL

IMPORT

SIG · TODOIST-API-PYTHON

todoist-api-python

crm-productivitypythonv4.0.0

Install

2.4s avg

Import

466ms

Disk

22MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v4.0.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.910 runs

installs and imports cleanly · install 0.0s · import 0.477s · 23.9MB

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 2.4s · import 0.454s · 24MB

22MB installed

● package 22MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

TodoistAPI

✓ from todoist_api_python.api import TodoistAPI

✗ from todoist_api_python import TodoistAPI

As of v3.0.0, the API classes moved to the `api` subpackage.

TodoistAPIAsync

✓ from todoist_api_python.api import TodoistAPIAsync

✗ from todoist_api_python import TodoistAPIAsync

As of v3.0.0, the API classes moved to the `api` subpackage.

This quickstart initializes the Todoist API client using an API token (preferably from an environment variable). It then fetches all projects and creates a new task, demonstrating basic read and write operations. Remember to replace 'YOUR_API_TOKEN_HERE' or set the TODOIST_API_TOKEN environment variable.

import os from todoist_api_python.api import TodoistAPI # Get your Todoist API token from environment variables or provide directly api_token = os.environ.get('TODOIST_API_TOKEN', 'YOUR_API_TOKEN_HERE') if not api_token or api_token == 'YOUR_API_TOKEN_HERE': print("Warning: TODOIST_API_TOKEN environment variable not set. Using placeholder.") # In a real application, you would raise an error or exit. api = TodoistAPI(api_token) try: # Fetch all active projects projects = api.get_projects() print(f"Successfully fetched {len(projects)} projects:") for project in projects[:3]: # Print first 3 projects print(f"- {project.name} (ID: {project.id})") # Create a new task new_task = api.add_task( content="Buy groceries", project_id=projects[0].id if projects else None, # Assign to first project if available due_string="tomorrow", priority=4 ) print(f"\nCreated new task: {new_task.content} (ID: {new_task.id})") except Exception as error: print(f"An error occurred: {error}")

Debug

Known issues

breakingMajor architectural changes in v3.0.0, including switching from `requests` to `httpx` as the internal HTTP client, moving API classes to `todoist_api_python.api`, and renaming most `add_*` methods to `create_*` and `update_item` to `update_task`.

fix

Review the changelog and update import paths (`from todoist_api_python.api import ...`), method names (e.g., `create_task` instead of `add_task`), and method signatures as needed. Existing code written for v2.x.x will not work without modifications.

affects: 3.0.0 and later

breakingVersion 4.0.0 and above require Python 3.10 or higher. Previous versions (3.x.x) required Python 3.8+.

fix

Upgrade your Python environment to 3.10 or newer. If you must use an older Python version, consider pinning to `todoist-api-python<4.0.0` for Python 3.8-3.9, or `todoist-api-python<3.0.0` for Python 3.7 and below.

affects: 4.0.0 and later

gotchaThe SDK provides both synchronous (`TodoistAPI`) and asynchronous (`TodoistAPIAsync`) clients. Ensure you use the correct client for your application's concurrency model. The async client methods must be awaited within an `async def` function.

fix

For sync code, use `TodoistAPI`. For async code, use `TodoistAPIAsync` and `await` its methods. Do not mix them directly without proper async/sync bridging.

affects: 3.0.0 and later

gotchaThe `project_id` parameter when creating a task (using `add_task` or `create_task`) can be `None` to add the task to the user's inbox, or a string ID for a specific project. If providing an invalid ID, the API will silently add it to the inbox.

fix

Always validate project IDs if they are dynamically obtained. If you explicitly want a task in a specific project, ensure the `project_id` is correct and belongs to the user. For inbox tasks, explicitly pass `None` or omit the `project_id`.

affects: All versions

Errors

Common errors & fixes

ImportError: cannot import name 'TodoistAPI' from 'todoist_api_python'

Attempting to import `TodoistAPI` directly from the top-level package, which was the pattern in v2.x.x.

fix

Update the import statement to `from todoist_api_python.api import TodoistAPI` as per v3.0.0 and later.

TypeError: TodoistAPI() missing 1 required positional argument: 'token'

The `TodoistAPI` client was initialized without providing the API token.

fix

Provide your Todoist API token as the first argument when initializing the client, e.g., `api = TodoistAPI('YOUR_API_TOKEN')` or `api = TodoistAPI(os.environ.get('TODOIST_API_TOKEN'))`.

This app requires Python 3.10.0 or later.

Running `todoist-api-python` version 4.0.0 or higher with a Python interpreter older than 3.10.

fix

Upgrade your Python environment to 3.10 or newer. Alternatively, if you cannot upgrade Python, install an older version of the library (e.g., `pip install todoist-api-python<4.0.0`).

AttributeError: 'TodoistAPI' object has no attribute 'add_item'

Attempting to use old method names from v2.x.x, specifically `add_item` which was renamed in v3.0.0.

fix

Update the method call to the new naming convention. `add_item` is now `create_task`. Similarly, `update_item` is `update_task`, and `add_project` is `create_project`, etc.

Upgrade

Version history

4.0.0latest on PyPI · released Mar 25, 2026

Audit

Dependencies

httpxrequiredInternal HTTP client for making requests to the Todoist API.

pydanticrequiredUsed for data validation and parsing API responses into Python objects.

Agent activity

52 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/Doist/todoist-api-python ↗

packagehttps://pypi.org/project/todoist-api-python/ ↗

homepagehttps://www.todoist.com ↗

docshttps://doist.github.io/todoist-api-python ↗