This is the official Python SDK for the Todoist API.

Installation

pip install todoist-api-python

Or add the project as a dependency in pyproject.toml:

dependencies = [
  "todoist-api-python>=3.1.0,<4",
]

Supported Python Versions

Python version 3.10 and above.

Usage

Here's an example of initializing the API client, fetching a task, and paginating through its comments:

from todoist_api_python.api import TodoistAPI

api = TodoistAPI("YOUR_API_TOKEN")

task = api.get_task("6X4Vw2Hfmg73Q2XR")
print(f"Task: {task.content}")

comments_iter = api.get_comments(task_id=task.id)
for comments in comments_iter:
    for comment in comments:
        print(f"Comment: {comment.content}")

Async usage

Always close TodoistAPIAsync explicitly, either via async with (recommended) or by calling await api.close().

from todoist_api_python.api_async import TodoistAPIAsync

async with TodoistAPIAsync("YOUR_API_TOKEN") as api:
    task = await api.get_task("6X4Vw2Hfmg73Q2XR")
    print(task.content)

Documentation

For more detailed reference documentation, have a look at the SDK documentation and the API documentation.

Migrating from 3.x

Version 4.x introduces a breaking HTTP stack migration from requests to httpx.

• TodoistAPI(..., session=...) is now TodoistAPI(..., client=...) with httpx.Client.
• TodoistAPIAsync(..., session=...) is now TodoistAPIAsync(..., client=...) with httpx.AsyncClient.
• Error handling should catch httpx.HTTPStatusError instead of requests.exceptions.HTTPError.

Development

To install Python dependencies:

To install pre-commit:

$ uv run pre-commit install

You can try your changes via REPL by running:

You can then import the library as described in Usage without having to create a file. If you decide to use TodoistAPIAsync, please keep in mind that you have to import asyncio and run asyncio.run(yourmethod()) to make your async methods run as expected.

Releases

This API client is public, and available in a PyPI repository.

A new update is automatically released by GitHub Actions, by creating a release with a tag in the format vX.Y.Z (v<Major>.<Minor>.<Patch>).

Users of the API client can then update to the new version in their pyproject.toml file.

Feedback

Any feedback, bugs, questions, comments, etc., can be reported as Issues in this repository.

Contributions

We would love contributions! Pull requests are welcome.