{"id":10299,"library":"todoist-api-python","title":"Todoist API Python SDK","description":"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.","status":"active","version":"4.0.0","language":"en","source_language":"en","source_url":"https://github.com/Doist/todoist-api-python","tags":["todoist","api","productivity","task management","sdk"],"install":[{"cmd":"pip install todoist-api-python","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Internal HTTP client for making requests to the Todoist API.","package":"httpx","optional":false},{"reason":"Used for data validation and parsing API responses into Python objects.","package":"pydantic","optional":false}],"imports":[{"note":"As of v3.0.0, the API classes moved to the `api` subpackage.","wrong":"from todoist_api_python import TodoistAPI","symbol":"TodoistAPI","correct":"from todoist_api_python.api import TodoistAPI"},{"note":"As of v3.0.0, the API classes moved to the `api` subpackage.","wrong":"from todoist_api_python import TodoistAPIAsync","symbol":"TodoistAPIAsync","correct":"from todoist_api_python.api import TodoistAPIAsync"}],"quickstart":{"code":"import os\nfrom todoist_api_python.api import TodoistAPI\n\n# Get your Todoist API token from environment variables or provide directly\napi_token = os.environ.get('TODOIST_API_TOKEN', 'YOUR_API_TOKEN_HERE')\n\nif not api_token or api_token == 'YOUR_API_TOKEN_HERE':\n    print(\"Warning: TODOIST_API_TOKEN environment variable not set. Using placeholder.\")\n    # In a real application, you would raise an error or exit.\n\napi = TodoistAPI(api_token)\n\ntry:\n    # Fetch all active projects\n    projects = api.get_projects()\n    print(f\"Successfully fetched {len(projects)} projects:\")\n    for project in projects[:3]: # Print first 3 projects\n        print(f\"- {project.name} (ID: {project.id})\")\n\n    # Create a new task\n    new_task = api.add_task(\n        content=\"Buy groceries\",\n        project_id=projects[0].id if projects else None, # Assign to first project if available\n        due_string=\"tomorrow\",\n        priority=4\n    )\n    print(f\"\\nCreated new task: {new_task.content} (ID: {new_task.id})\")\n\nexcept Exception as error:\n    print(f\"An error occurred: {error}\")\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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`.","severity":"breaking","affected_versions":"3.0.0 and later"},{"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.","message":"Version 4.0.0 and above require Python 3.10 or higher. Previous versions (3.x.x) required Python 3.8+.","severity":"breaking","affected_versions":"4.0.0 and later"},{"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.","message":"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.","severity":"gotcha","affected_versions":"3.0.0 and later"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Update the import statement to `from todoist_api_python.api import TodoistAPI` as per v3.0.0 and later.","cause":"Attempting to import `TodoistAPI` directly from the top-level package, which was the pattern in v2.x.x.","error":"ImportError: cannot import name 'TodoistAPI' from 'todoist_api_python'"},{"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'))`.","cause":"The `TodoistAPI` client was initialized without providing the API token.","error":"TypeError: TodoistAPI() missing 1 required positional argument: 'token'"},{"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`).","cause":"Running `todoist-api-python` version 4.0.0 or higher with a Python interpreter older than 3.10.","error":"This app requires Python 3.10.0 or later."},{"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.","cause":"Attempting to use old method names from v2.x.x, specifically `add_item` which was renamed in v3.0.0.","error":"AttributeError: 'TodoistAPI' object has no attribute 'add_item'"}]}