ticktick-py is an unofficial API library for interacting with TickTick.com. It allows users a way to interact with their TickTick account using Python.

The library automatically fetches all the tasks, tags, lists, and more linked to your profile and stores them in a dictionary named state.

• Tasks
  • Create, Update, and Delete Tasks
  • Acquire all your uncompleted tasks
  • Move tasks easily between projects
  • Acquire all completed tasks in a certain date range
• Tags
  • Batch create, update, and delete tags
  • Create tags with parameters that are not usually allowed: \\ / " # : * ? < > | Space
• Projects
  • Batch create, update, and delete 'lists' (projects)
  • Batch archive projects

Lets create a task in our inbox titled "Get Groceries"

name = 'Get Groceries'                      # Task Name
local_task = client.task.builder(name)      # Create a dictionary for the task
groceries = client.task.create(local_task)  # Actually create the task

A simplified dictionary for the newly created task is returned.

print(groceries)

{'id': '60c6a40b8f083f896c9444a0', 'projectId': 'inbox115781412', 'title': 'Get Groceries', 'timeZone': '', 
 'reminders': [], 'priority': 0, 'status': 0, 'sortOrder': -3298534883328, 'items': []}

You can retrieve the full dictionary with every parameter by using the get_by_id method.

full_task = client.get_by_id(groceries['id'])
print(full_task)

{'id': '60c6a40b8f083f896c9444a0', 'projectId': 'inbox115781412', 'sortOrder': -3298534883328, 
 'title': 'Get Groceries', 'timeZone': '', 'isFloating': False, 'reminder': '', 'reminders': [], 
 'priority': 0, 'status': 0, 'items': [], 'modifiedTime': '2021-06-14T00:34:19.907+0000', 'etag': 't8xnwewi', 
 'deleted': 0, 'createdTime': '2021-06-14T00:34:19.907+0000', 'creator': 113581412, 'tags': [], 'kind': 'TEXT'}

Created Task In TickTick

Most methods will return the object that was changed. Consult the usage documentation for more information on specific methods.

Note: ticktick-py requires Python 3.6 or above.

pip install ticktick-py

The library now uses TickTick's OpenAPI scheme when possible. This requires registering a new app through TickTick's developer documentation.

OpenAPI Documentation

Click on Manage Apps in the top right corner. You will be prompted to login with your normal TickTick credentials if you are not already logged in.

Register a new app by clicking the +App Name button.

Name is the only required parameter here. Once created you should see the app and be able to edit it.

There should now be a generated Client ID and Client Secret parameters. It is recommended you save these to your environment, and make sure you do not share your actual Client Secret.

For OAuth Redirect URL enter any URL you would like to be redirected to upon giving permissions to your account. It does not have to be an actually live URL - this local host URL is fine for most purposes. It is also recommended you save this URL to your environment.

Once you have registered the app, you can now proceed with the rest of the setup.

from ticktick.oauth2 import OAuth2        # OAuth2 Manager
from ticktick.api import TickTickClient   # Main Interface

auth_client = OAuth2(client_id=client_id,
                     client_secret=client_secret,
                     redirect_uri=uri)

client = TickTickClient(username, password, auth_client)

The first time the OAuth2 object runs, you will need to manually accept permissions. A webbrowser will automatically open.

The default permissions are to Read and Write tasks (and are the only options right now). You can change the permissions by specifying the scope parameter when creating your OAuth2 instance. More information can be found in the OAuth2 documention.

In the console you will be prompted to enter the URL that you were redirected to. It will be your specified OAuth URL with some added parameters.

Enter the URL you were redirected to:
>? http://127.0.0.1:8080/?code=RK3dSi&state=None

That is it! Your token information is cached in a file (default is .token-oauth) so you will only have to manually allow access the first time, and whenever the token expires. As of now it seems tokens expire after about 6 months.

• General
  • Enhanced Team Support
• Tasks
  • Get and Restore From Trash
• Projects
  • Smart List Support
  • Column Creation For Kanban View
• Pomo and Focus
  • Getting the focus / pomo statistics for your profile
  • Starting and stopping the focus / pomo timer
• Habits
  • Get, create, archive, delete, and complete habits