The Two TickTick APIs

Overview

You may notice throughout this documentation that there are two different APIs that are referenced and supported. This is because TickTick has provided two different interfaces that users can, in theory, interact with. The first, API V1, is the official API that TickTick has provided to developers. The second, API V2, is an unofficial API that has been reverse-engineered by the community, and can be observed by inspecting network requests made by the TickTick web app.

API V1

The official API, formally known as the TickTick Open API, is a RESTful API for managing user tasks, and lists. You can learn more from their official documentation. Given that there are two APIs, and this API's URL starts with api.ticktick.com/open/v1/, we will refer to this as API V1.

API V2

The unofficial API does not have a formal name, but we refer to it as API V2, given the URL starts with api.ticktick.com/api/v2/. This API is undocumented, so the information provided in this documentation is based on other projects' efforts to reverse-engineer the API, as well as our own observations, and may not be entirely accurate. This is the API that the TickTick web app uses to communicate with the TickTick servers, so anything you can do in the web app, you can do with this API.

Why support two APIs?

The goal is to provide the best experience possible for developers using this library. The official API is well-documented, and is the one that TickTick has provided. However, the unofficial API is more robust, and provides significantly more functionality than the official API. API V1 is limited to managing lists and tasks alone (not including the inbox list). API V2, on the other hand, provides access to all of the features that the TickTick web app has, including tags, sublists, subtasks, and more. This is why this library supports both APIs.

Which API should I use?

TickTick has not mentioned the API V2 anywhere on their website, but it provides a better experience for developers. Given that TickTick has not given explicit permission to use it, it may go against their Terms of Service. This was discussed in lazeroffmichael/ticktick-py#38 if you want to see other developers' opinions on the matter. This library's recommendation is to use the official API where possible, and only use the unofficial API when necessary. The library client is designed to be flexible, so you can do whatever you feel comfortable with.