Plan to Migrate to Todoist API v1

[AhmedZaki99]

On January 7, the Todoist Dev team took the first steps towards shutting down the Sync v9 API as discussed in this announcement.
We have until February 10 to migrate to the new unified API, so I started working on the migration with the help of Claude Opus 4.5 AI Agent.

Proper context has been provided by scraping the entire Todoist API v1 documentation and turning it into a set of markdown files that Claude Opus can easily read and refer to.
I have tried to follow the best practices of writing prompts and spent some time planning before taking the first steps to start code modifications.
I have also instructed the Agent to split the work required into multiple PRs so that they become easy to review.

Starting from this line, most of the content below and the upcoming PR descriptions are generated by AI.

Overview

This issue tracks the migration of Todoist.Net from the Todoist Sync API v9 to the new unified Todoist API v1. This is a major breaking release that will be versioned as v11.0.0.

The Todoist API v1 combines the previous REST and Sync APIs into a single unified API with improved consistency, cursor-based pagination, and updated error handling.

Migration Phases

• PR 1: Core Renames
• PR 2: Foundation and new REST Endpoints and Services
• PR 3: Documentation and Final Release Prep

PR 1: Core Renames

• Rename Item -> DetailedTask, AddItem -> AddTask, UpdateItem -> UpdateTask
• Rename Note -> Comment
• Rename ItemsService -> TasksService, NotesService -> CommentsService
• Update client properties: Items -> Tasks, Notes -> Comments
• Update test files to use new naming

PR 2: Foundation and new REST Endpoints and Services

• Update REST client base URL from sync/v9 to api/v1
• Add new HTTP methods (DeleteAsync, PutAsync, PostJsonAsync)
• Add PaginatedResponse<T> model for cursor-based pagination
• Update error handling for v1 API format (error_tag, http_code, error_extra)
• Remove deprecated properties (UserInfo.IsBizAdmin, CompletedTask.CommentCount)
• Implement new v1 REST endpoints for Tasks
• Implement new v1 REST endpoints for Comments
• Implement new v1 REST endpoints for Projects
• Implement new v1 REST endpoints for Sections
• Implement new v1 REST endpoints for Labels
• Add pagination support to list methods
• Update service implementations for v1 endpoint patterns

PR 3: Documentation and Final Release Prep

• Update README with new API usage examples
• Update inline XML documentation
• Add migration guide for users upgrading from v10.x
• Final integration testing

Update: Phase 3 Scope Expansion (Implemented)

During implementation, migration gaps were identified that required broad contract/model/service finalization beyond the original docs-focused PR 3 plan.
This update documents what changed and why.

• Reorganized models and services by domain (entity-based folder structure)
• Redesigned common abstractions:
  • sync response model family,
  • command result/operation models,
  • pagination/query primitives,
  • guard/exception foundations
• Refactored domain models for v1-aligned request/response/query contracts
• Added new model coverage for:
  • Workspaces,
  • Workspace Filters,
  • View Options,
  • Calendars,
  • ID mappings,
  • Template import contracts
• Redesigned/finalized client contracts (ITodoistClient, IAdvancedTodoistClient, ITodoistRestClient)
• Refactored service interfaces/implementations to redesigned contracts and v1 route semantics
• Added new services for Workspaces, Workspace Filters, View Options, Calendars, and IDs
• Finalized TodoistClient + TodoistRestClient wiring for the expanded v1 surface
• Retained release prep tasks (README/docs/migration guide/integration validation) as part of finalization

Breaking Changes Summary

Category	Old	New
Model	Item	DetailedTask
Model	AddItem	AddTask
Model	UpdateItem	UpdateTask
Model	Note	Comment
Service	ItemsService	TasksService
Service	NotesService	CommentsService
Client Property	ITodoistClient.Items	ITodoistClient.Tasks
Client Property	ITodoistClient.Notes	ITodoistClient.Comments

Additional Breaking Changes Introduced in Phase 3

• Service/interface contract reshaping and method signature updates for v1 query/request/response models
• Service/interface renames in parts of the public surface (for example: IBackupService -> IBackupsService, IUploadService -> IUploadsService)
• Significant model refactors/replacements and relocations across domains
• Sync/command abstraction redesign requiring migration for consumers depending on previous internals
• Expanded public client surface with new domains:
  • Workspaces,
  • Workspace Filters,
  • View Options,
  • Calendars,
  • ID mappings

Compatibility Notes

• JSON property names remain unchanged (items, notes, item_id) for sync API response compatibility
• Sync command type strings remain unchanged (item_add, note_add) for API compatibility
• Target frameworks unchanged: netstandard2.0, net462

[ivorco]

This is dependency for a pretty important project I have
Tell me if you need any help

[olsh]

All integration tests are passing, so I pushed a prerelease version of the package — 11.0.0-beta.1.
It should be available soon here: https://www.nuget.org/packages/Todoist.Net/11.0.0-beta.1

The migration was done by @AhmedZaki99 — I don't have time to work on this myself.
Once he finishes the migration (Phase 3 is still left), I'll publish the final version.

[olsh]

Hi @AhmedZaki99,

Please let me know if you have any plans to work on phase 3. It seems like I have some spare time and I could work on this.

[rossdargan]

I'm trying the beta, but this code doesn't return any tasks:

var todoistItems = await _lazyClient.Value.Projects.GetDataAsync(shoppingProject.Id);

todoistItems.Project is populated and correct, but todoistItems.Task is null.

I think we should probably be calling:

https://api.todoist.com/api/v1/tasks?project_id=PROJECT_ID

[AhmedZaki99]

@olsh I have already started working on it for the past week. I decided that I continue working without the AI and I already found so much needs changing.

I will create a PR in a few hours, but this time I decided since the migration has many breaking changes anyways then it's worth nothing to refactor some parts of the code on my way.

I also corrected some mistakes made by the AI and added many missing models, propertes, and a couple of extra services.