Todoist API Python SDK

Common errors

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

  cause 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'

  cause 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.

  cause 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'

  cause 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.

Warnings

• breaking Major 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.
• breaking Version 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.
• gotcha The 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.
• gotcha The `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`.

Install

• pip install todoist-api-python Install stable version

Imports

• TodoistAPI
  wrong:

  from todoist_api_python import TodoistAPI

  correct:

  from todoist_api_python.api import TodoistAPI

  As of v3.0.0, the API classes moved to the `api` subpackage.
• TodoistAPIAsync
  wrong:

  from todoist_api_python import TodoistAPIAsync

  correct:

  from todoist_api_python.api import TodoistAPIAsync

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

Quickstart

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}")