Client (V1)

This reference documentation provides a comprehensive overview of all V1 endpoint methods available in the client. To see the V2 methods, please refer to the Client (V2) reference docs.

Note

This attempts to follow the TickTick API Reference as closely as possible. If functionality is missing, but you expect it to be there, it may be supported in the V2 client functions.

pyticktick.client.Client

Bases: Settings

Client class for TickTick API.

The client class provides methods to interact with both the V1 and V2 API endpoints. This can be used to get, create, update, and delete, projects, tasks, tags, and other objects in the TickTick application.

Authenticating the client

The client class requires the user to be authenticated. The user must login to the V1 and/or V2 API endpoints before using the client class:

from pyticktick import Client

client = Client(
    v1_client_id="client_id",
    v1_client_secret="client_secret",
    v1_token={
        "value": "fa371b10-8b95-442b-b4a5-11a9959d3590",
        "expiration": 1701701789,
    },
    v2_username="username",
    v2_password="password",
)

To see more details on how to authenticate, refer to pyticktick.Settings. The client class inherits the Settings class, so all the setting configurations will be available in the client class.

Methods:

Name	Description
get_project_v1	Get a single project from the V1 API.
get_projects_v1	Get all projects from the V1 API.
get_project_with_data_v1	Get details of a single project from the V1 API.
create_project_v1	Create a project in the V1 API.
update_project_v1	Update a project in the V1 API.
delete_project_v1	Delete a project in the V1 API.
get_task_v1	Get a single task from the V1 API.
create_task_v1	Create a task in the V1 API.
update_task_v1	Update a task in the V1 API.
complete_task_v1	Complete a task in the V1 API.
delete_task_v1	Delete a task in the V1 API.

get_project_v1

get_project_v1(project_id: str) -> ProjectRespV1

Get a single project from the V1 API.

This method calls the GET /project/{project_id} V1 endpoint, where project_id is the identifier of the project. It is equivalent to get_projects_v1 followed by filtering to the project with the given project_id.

Example

from pyticktick import Client

client = Client()
project = client.get_project_v1("67ec23b18f08cf38dd957e10")
print(project.model_dump())

will output:

{
    "id": "67ec23b18f08cf38dd957e10",
    "name": "Project 1",
    "color": null,
    "sort_order": -3298534883328,
    "closed": null,
    "group_id": null,
    "view_mode": "list",
    "permission": null,
    "kind": "TASK"
}

Args: project_id (str): Identifier of the project to retrieve.

Returns:

Name	Type	Description
ProjectRespV1	ProjectRespV1	Project object containing project details.

Source code in src/pyticktick/client.py

def get_project_v1(self, project_id: str) -> ProjectRespV1:
    """Get a single project from the V1 API.

    This method calls the [`GET /project/{project_id}`](https://developer.ticktick.com/docs/index.html#/openapi?id=get-project-by-id)
    V1 endpoint, where `project_id` is the identifier of the project. It is
    equivalent to `get_projects_v1` followed by filtering to the project with the
    given `project_id`.

    ??? example "Example"
        ```python hl_lines="4"
        from pyticktick import Client

        client = Client()
        project = client.get_project_v1("67ec23b18f08cf38dd957e10")
        print(project.model_dump())
        ```

        will output:
        ```json
        {
            "id": "67ec23b18f08cf38dd957e10",
            "name": "Project 1",
            "color": null,
            "sort_order": -3298534883328,
            "closed": null,
            "group_id": null,
            "view_mode": "list",
            "permission": null,
            "kind": "TASK"
        }
        ```
    Args:
        project_id (str): Identifier of the project to retrieve.

    Returns:
        ProjectRespV1: Project object containing project details.
    """
    resp = self._get_api_v1(f"/project/{project_id}")
    return ProjectRespV1.model_validate(resp)

get_projects_v1

get_projects_v1() -> ProjectsRespV1

Get all projects from the V1 API.

This method gets all the active projects from the GET /project V1 endpoint.

Example

from pyticktick import Client

client = Client()
projects = client.get_projects_v1()
for project in projects:
    print(project.model_dump())

will output:

{
    "id": "67ec23b18f08cf38dd957e10",
    "name": "Project 1",
    "color": null,
    "sort_order": -3298534883328,
    "closed": null,
    "group_id": null,
    "view_mode": "list",
    "permission": null,
    "kind": "TASK"
}
{
    "id": "67ec23b68f08cf38dd957ece",
    "name": "Project 2",
    "color": null,
    "sort_order": -2199023255552,
    "closed": null,
    "group_id": null,
    "view_mode": "list",
    "permission": null,
    "kind": "TASK"
}
{
    "id": "67ec23c28f08cf38dd957ff1",
    "name": "Project 3",
    "color": null,
    "sort_order": -1649267441664,
    "closed": null,
    "group_id": null,
    "view_mode": "list",
    "permission": null,
    "kind": "TASK"
}

Returns:

Name	Type	Description
ProjectsRespV1	ProjectsRespV1	List of projects from the V1 API.

Source code in src/pyticktick/client.py

def get_projects_v1(self) -> ProjectsRespV1:
    """Get all projects from the V1 API.

    This method gets all the active projects from the [`GET /project`](https://developer.ticktick.com/docs/index.html#/openapi?id=get-user-project)
    V1 endpoint.

    ??? example "Example"
        ```python hl_lines="4"
        from pyticktick import Client

        client = Client()
        projects = client.get_projects_v1()
        for project in projects:
            print(project.model_dump())
        ```

        will output:
        ```json
        {
            "id": "67ec23b18f08cf38dd957e10",
            "name": "Project 1",
            "color": null,
            "sort_order": -3298534883328,
            "closed": null,
            "group_id": null,
            "view_mode": "list",
            "permission": null,
            "kind": "TASK"
        }
        {
            "id": "67ec23b68f08cf38dd957ece",
            "name": "Project 2",
            "color": null,
            "sort_order": -2199023255552,
            "closed": null,
            "group_id": null,
            "view_mode": "list",
            "permission": null,
            "kind": "TASK"
        }
        {
            "id": "67ec23c28f08cf38dd957ff1",
            "name": "Project 3",
            "color": null,
            "sort_order": -1649267441664,
            "closed": null,
            "group_id": null,
            "view_mode": "list",
            "permission": null,
            "kind": "TASK"
        }
        ```

    Returns:
        ProjectsRespV1: List of projects from the V1 API.
    """
    resp = self._get_api_v1("/project")
    return ProjectsRespV1.model_validate(resp)

get_project_with_data_v1

get_project_with_data_v1(
    project_id: str,
) -> ProjectDataRespV1

Get details of a single project from the V1 API.

This method calls the GET /project/{project_id}/data V1 endpoint, where project_id is the identifier of the project. It provides a superset of the information available in get_project_v1.

Example

from pyticktick import Client

client = Client()
project_data = client.get_project_with_data_v1("67ec23b18f08cf38dd957e10")
print(project_data.model_dump())

will output:

{
    "project": {
        "id": "67ec23b18f08cf38dd957e10",
        "name": "Project 1",
        "color": null,
        "sort_order": -3298534883328,
        "closed": null,
        "group_id": null,
        "view_mode": "list",
        "permission": null,
        "kind": "TASK"
    },
    "tasks": [
        {
            "id": "67ec273212e1101e875f078b",
            "project_id": "67ec23b18f08cf38dd957e10",
            "title": "Task 1",
            "is_all_day": false,
            "completed_time": null,
            "content": "",
            "desc": null,
            "due_date": null,
            "items": null,
            "priority": 0,
            "reminders": null,
            "repeat_flag": null,
            "sort_order": -4398046511104,
            "start_date": null,
            "status": false,
            "time_zone": "America/Chicago",
            "etag": "k9r8mw9b",
            "kind": "TEXT"
        },
        {
            "id": "67ec273412e1101e875f0791",
            "project_id": "67ec23b18f08cf38dd957e10",
            "title": "Task 2 ",
            "is_all_day": false,
            "completed_time": null,
            "content": "",
            "desc": null,
            "due_date": null,
            "items": null,
            "priority": 0,
            "reminders": null,
            "repeat_flag": null,
            "sort_order": -2199023255552,
            "start_date": null,
            "status": false,
            "time_zone": "America/Chicago",
            "etag": "1q51czxo",
            "kind": "TEXT"
        },
        {
            "id": "67ec273a12e1101e875f079e",
            "project_id": "67ec23b18f08cf38dd957e10",
            "title": "Task 3",
            "is_all_day": false,
            "completed_time": null,
            "content": "",
            "desc": null,
            "due_date": null,
            "items": null,
            "priority": 0,
            "reminders": null,
            "repeat_flag": null,
            "sort_order": -1099511627776,
            "start_date": null,
            "status": false,
            "time_zone": "America/Chicago",
            "etag": "pan652fb",
            "kind": "TEXT"
        }
    ],
    "columns": []
}

Args: project_id (str): Identifier of the project to retrieve.

Returns:

Name	Type	Description
ProjectDataRespV1	ProjectDataRespV1	Project data object containing project and task details.

Source code in src/pyticktick/client.py

def get_project_with_data_v1(self, project_id: str) -> ProjectDataRespV1:
    """Get details of a single project from the V1 API.

    This method calls the [`GET /project/{project_id}/data`](https://developer.ticktick.com/docs/index.html#/openapi?id=get-project-with-data)
    V1 endpoint, where `project_id` is the identifier of the project. It provides a
    superset of the information available in `get_project_v1`.

    ??? example "Example"
        ```python hl_lines="4"
        from pyticktick import Client

        client = Client()
        project_data = client.get_project_with_data_v1("67ec23b18f08cf38dd957e10")
        print(project_data.model_dump())
        ```

        will output:
        ```json
        {
            "project": {
                "id": "67ec23b18f08cf38dd957e10",
                "name": "Project 1",
                "color": null,
                "sort_order": -3298534883328,
                "closed": null,
                "group_id": null,
                "view_mode": "list",
                "permission": null,
                "kind": "TASK"
            },
            "tasks": [
                {
                    "id": "67ec273212e1101e875f078b",
                    "project_id": "67ec23b18f08cf38dd957e10",
                    "title": "Task 1",
                    "is_all_day": false,
                    "completed_time": null,
                    "content": "",
                    "desc": null,
                    "due_date": null,
                    "items": null,
                    "priority": 0,
                    "reminders": null,
                    "repeat_flag": null,
                    "sort_order": -4398046511104,
                    "start_date": null,
                    "status": false,
                    "time_zone": "America/Chicago",
                    "etag": "k9r8mw9b",
                    "kind": "TEXT"
                },
                {
                    "id": "67ec273412e1101e875f0791",
                    "project_id": "67ec23b18f08cf38dd957e10",
                    "title": "Task 2 ",
                    "is_all_day": false,
                    "completed_time": null,
                    "content": "",
                    "desc": null,
                    "due_date": null,
                    "items": null,
                    "priority": 0,
                    "reminders": null,
                    "repeat_flag": null,
                    "sort_order": -2199023255552,
                    "start_date": null,
                    "status": false,
                    "time_zone": "America/Chicago",
                    "etag": "1q51czxo",
                    "kind": "TEXT"
                },
                {
                    "id": "67ec273a12e1101e875f079e",
                    "project_id": "67ec23b18f08cf38dd957e10",
                    "title": "Task 3",
                    "is_all_day": false,
                    "completed_time": null,
                    "content": "",
                    "desc": null,
                    "due_date": null,
                    "items": null,
                    "priority": 0,
                    "reminders": null,
                    "repeat_flag": null,
                    "sort_order": -1099511627776,
                    "start_date": null,
                    "status": false,
                    "time_zone": "America/Chicago",
                    "etag": "pan652fb",
                    "kind": "TEXT"
                }
            ],
            "columns": []
        }
        ```
    Args:
        project_id (str): Identifier of the project to retrieve.

    Returns:
        ProjectDataRespV1: Project data object containing project and task details.
    """
    resp = self._get_api_v1(f"/project/{project_id}/data")
    return ProjectDataRespV1.model_validate(resp)

create_project_v1

create_project_v1(
    data: Union[CreateProjectV1, dict[str, Any]],
) -> ProjectRespV1

Create a project in the V1 API.

This method creates a new project in the TickTick application using the POST /project V1 endpoint. The data parameter can be a CreateProjectV1 model or a dictionary that matches the same structure. The method returns the created project as a ProjectV1 model.

Example

from pyticktick import Client
from pyticktick.models.v1 import CreateProjectV1

client = Client()
project = client.create_project_v1(
    data=CreateProjectV1(
        name="Test Project",
        color="#002fa7",
        sort_order=50,
        view_mode="list",
        kind="TASK",
    ),
)
print(project.model_dump())

will output:

{
    "id": "67ec9d148f08723133663fd1",
    "name": "Test Project",
    "color": "#002fa7",
    "sort_order": 50,
    "closed": null,
    "group_id": null,
    "view_mode": "list",
    "permission": null,
    "kind": "TASK"
}

Parameters:

Name	Type	Description	Default
data	Union[CreateProjectV1, dict[str, Any]]	Data to create the project.	required

Returns:

Name	Type	Description
ProjectRespV1	ProjectRespV1	Created project.

Source code in src/pyticktick/client.py

def create_project_v1(
    self,
    data: Union[CreateProjectV1, dict[str, Any]],
) -> ProjectRespV1:
    """Create a project in the V1 API.

    This method creates a new project in the TickTick application using the
    [`POST /project`](https://developer.ticktick.com/docs/index.html#/openapi?id=create-project)
    V1 endpoint. The `data` parameter can be a `CreateProjectV1` model or a
    dictionary that matches the same structure. The method returns the created
    project as a `ProjectV1` model.

    ??? example "Example"
        ```python hl_lines="5"
        from pyticktick import Client
        from pyticktick.models.v1 import CreateProjectV1

        client = Client()
        project = client.create_project_v1(
            data=CreateProjectV1(
                name="Test Project",
                color="#002fa7",
                sort_order=50,
                view_mode="list",
                kind="TASK",
            ),
        )
        print(project.model_dump())
        ```

        will output:
        ```json
        {
            "id": "67ec9d148f08723133663fd1",
            "name": "Test Project",
            "color": "#002fa7",
            "sort_order": 50,
            "closed": null,
            "group_id": null,
            "view_mode": "list",
            "permission": null,
            "kind": "TASK"
        }
        ```

    Args:
        data (Union[CreateProjectV1, dict[str, Any]]): Data to create the project.

    Returns:
        ProjectRespV1: Created project.
    """
    if isinstance(data, dict):
        data = CreateProjectV1.model_validate(data)
    resp = self._post_api_v1("/project", data=self._model_dump(data))
    return ProjectRespV1.model_validate(resp)

update_project_v1

update_project_v1(
    project_id: str,
    data: Union[UpdateProjectV1, dict[str, Any]],
) -> ProjectRespV1

Update a project in the V1 API.

This method updates an existing project in the TickTick application using the POST /project/{project_id} V1 endpoint. The data parameter can be an UpdateProjectV1 model or a dictionary that matches the same structure. The method returns the updated project as a ProjectV1 model.

Example

from pyticktick import Client
from pyticktick.models.v1 import UpdateProjectV1

client = Client()
project = client.update_project_v1(
    project_id="67ec9d148f08723133663fd1",
    data=UpdateProjectV1(
        name="Updated Project",
        color="#ee6c4d",
        sort_order=100,
        view_mode="list",
        kind="TASK",
    ),
)
print(project.model_dump())

will output:

{
    "id": "67ec9d148f08723133663fd1",
    "name": "Updated Project",
    "color": "#ee6c4d",
    "sort_order": 100,
    "closed": null,
    "group_id": null,
    "view_mode": "list",
    "permission": null,
    "kind": "TASK"
}

Args: project_id (str): Identifier of the project to update. data (Union[UpdateProjectV1, dict[str, Any]]): Data to update the project.

Returns:

Name	Type	Description
ProjectRespV1	ProjectRespV1	Updated project.

Source code in src/pyticktick/client.py

def update_project_v1(
    self,
    project_id: str,
    data: Union[UpdateProjectV1, dict[str, Any]],
) -> ProjectRespV1:
    """Update a project in the V1 API.

    This method updates an existing project in the TickTick application using the
    [`POST /project/{project_id}`](https://developer.ticktick.com/docs/index.html#/openapi?id=update-project)
    V1 endpoint. The `data` parameter can be an `UpdateProjectV1` model or a
    dictionary that matches the same structure. The method returns the updated
    project as a `ProjectV1` model.

    ??? example "Example"
        ```python hl_lines="5"
        from pyticktick import Client
        from pyticktick.models.v1 import UpdateProjectV1

        client = Client()
        project = client.update_project_v1(
            project_id="67ec9d148f08723133663fd1",
            data=UpdateProjectV1(
                name="Updated Project",
                color="#ee6c4d",
                sort_order=100,
                view_mode="list",
                kind="TASK",
            ),
        )
        print(project.model_dump())
        ```

        will output:
        ```json
        {
            "id": "67ec9d148f08723133663fd1",
            "name": "Updated Project",
            "color": "#ee6c4d",
            "sort_order": 100,
            "closed": null,
            "group_id": null,
            "view_mode": "list",
            "permission": null,
            "kind": "TASK"
        }
        ```
    Args:
        project_id (str): Identifier of the project to update.
        data (Union[UpdateProjectV1, dict[str, Any]]): Data to update the project.

    Returns:
        ProjectRespV1: Updated project.
    """
    if isinstance(data, dict):
        data = UpdateProjectV1.model_validate(data)
    resp = self._post_api_v1(f"/project/{project_id}", data=self._model_dump(data))
    return ProjectRespV1.model_validate(resp)

delete_project_v1

delete_project_v1(project_id: str) -> None

Delete a project in the V1 API.

This method deletes an existing project in the TickTick application using the DELETE /project/{project_id} V1 endpoint. The project_id parameter is the identifier of the project to delete.

Example

from pyticktick import Client

client = Client()
client.delete_project_v1("67ec9d148f08723133663fd1")

This will return nothing if the project is successfully deleted.

Parameters:

Name	Type	Description	Default
project_id	str	Identifier of the project to delete.	required

Source code in src/pyticktick/client.py

def delete_project_v1(self, project_id: str) -> None:
    """Delete a project in the V1 API.

    This method deletes an existing project in the TickTick application using the
    [`DELETE /project/{project_id}`](https://developer.ticktick.com/docs/index.html#/openapi?id=delete-project)
    V1 endpoint. The `project_id` parameter is the identifier of the project to
    delete.

    ??? example "Example"
        ```python hl_lines="4"
        from pyticktick import Client

        client = Client()
        client.delete_project_v1("67ec9d148f08723133663fd1")
        ```
        This will return nothing if the project is successfully deleted.

    Args:
        project_id (str): Identifier of the project to delete.
    """
    self._delete_api_v1(f"/project/{project_id}")

get_task_v1

get_task_v1(project_id: str, task_id: str) -> TaskRespV1

Get a single task from the V1 API.

This method calls the GET /project/{project_id}/task/{task_id} V1 endpoint, where project_id and task_id are the identifiers of the project and task, respectively.

Example

from pyticktick import Client

client = Client()
task = client.get_task_v1(
    project_id="67ec23b18f08cf38dd957e10",
    task_id="67ec273212e1101e875f078b",
)
print(task.model_dump())

will output:

{
    "id": "67ec273212e1101e875f078b",
    "project_id": "67ec23b18f08cf38dd957e10",
    "title": "Task 1",
    "is_all_day": false,
    "completed_time": null,
    "content": "",
    "desc": null,
    "due_date": null,
    "items": null,
    "priority": 0,
    "reminders": null,
    "repeat_flag": null,
    "sort_order": -4398046511104,
    "start_date": null,
    "status": false,
    "time_zone": "America/Chicago",
    "etag": "k9r8mw9b",
    "kind": "TEXT"
}

Parameters:

Name	Type	Description	Default
project_id	str	Identifier of the project containing the task.	required
task_id	str	Identifier of the task to retrieve.	required

Returns:

Name	Type	Description
TaskRespV1	TaskRespV1	The task object retrieved from the API.

Source code in src/pyticktick/client.py

def get_task_v1(self, project_id: str, task_id: str) -> TaskRespV1:
    """Get a single task from the V1 API.

    This method calls the [`GET /project/{project_id}/task/{task_id}`](https://developer.ticktick.com/docs/index.html#/openapi?id=get-task-by-project-id-and-task-id)
    V1 endpoint, where `project_id` and `task_id` are the identifiers of the
    project and task, respectively.

    ??? example "Example"
        ```python hl_lines="4"
        from pyticktick import Client

        client = Client()
        task = client.get_task_v1(
            project_id="67ec23b18f08cf38dd957e10",
            task_id="67ec273212e1101e875f078b",
        )
        print(task.model_dump())
        ```

        will output:
        ```json
        {
            "id": "67ec273212e1101e875f078b",
            "project_id": "67ec23b18f08cf38dd957e10",
            "title": "Task 1",
            "is_all_day": false,
            "completed_time": null,
            "content": "",
            "desc": null,
            "due_date": null,
            "items": null,
            "priority": 0,
            "reminders": null,
            "repeat_flag": null,
            "sort_order": -4398046511104,
            "start_date": null,
            "status": false,
            "time_zone": "America/Chicago",
            "etag": "k9r8mw9b",
            "kind": "TEXT"
        }
        ```

    Args:
        project_id (str): Identifier of the project containing the task.
        task_id (str): Identifier of the task to retrieve.

    Returns:
        TaskRespV1: The task object retrieved from the API.
    """
    resp = self._get_api_v1(f"/project/{project_id}/task/{task_id}")
    return TaskRespV1.model_validate(resp)

create_task_v1

create_task_v1(
    data: Union[CreateTaskV1, dict[str, Any]],
) -> TaskRespV1

Create a task in the V1 API.

This method creates a new task in the TickTick application using the POST /task V1 endpoint. The data parameter can be a CreateTaskV1 model or a dictionary that matches the same structure. The method returns the created task as a TaskRespV1 model.

Example

from pyticktick import Client
from pyticktick.models.v1 import CreateTaskV1

client = Client()
task = client.create_task_v1(
    data=CreateTaskV1(
        project_id="67eca3918f08e7c706354740",
        title="Test Task",
        content="This is a test task.",
        start_date="2025-11-13T03:00:00+0000",
        due_date="2025-11-14T03:00:00+0000",
    ),
)
print(task.model_dump())

will output:

{
    "id": "67eca3b78f08cf38dda26ca4",
    "project_id": "67eca3918f08e7c706354740",
    "title": "Test Task",
    "is_all_day": false,
    "completed_time": null,
    "content": "This is a test task.",
    "desc": null,
    "due_date": "2025-11-14T03:00:00.000+0000",
    "items": null,
    "priority": 0,
    "reminders": null,
    "repeat_flag": null,
    "sort_order": -1099511627776,
    "start_date": "2025-11-14T03:00:00.000+0000",
    "status": false,
    "time_zone": "America/Chicago",
    "tags": [],
    "etag": "8yp4pfmh",
    "kind": "TEXT"
}

Args: data (Union[CreateTaskV1, dict[str, Any]]): Data to create the task.

Returns:

Name	Type	Description
TaskRespV1	TaskRespV1	Created task object.

Source code in src/pyticktick/client.py

def create_task_v1(self, data: Union[CreateTaskV1, dict[str, Any]]) -> TaskRespV1:
    """Create a task in the V1 API.

    This method creates a new task in the TickTick application using the [`POST /task`](https://developer.ticktick.com/docs/index.html#/openapi?id=create-task)
    V1 endpoint. The `data` parameter can be a `CreateTaskV1` model or a dictionary
    that matches the same structure. The method returns the created task as a
    `TaskRespV1` model.

    ??? example "Example"
        ```python hl_lines="5"
        from pyticktick import Client
        from pyticktick.models.v1 import CreateTaskV1

        client = Client()
        task = client.create_task_v1(
            data=CreateTaskV1(
                project_id="67eca3918f08e7c706354740",
                title="Test Task",
                content="This is a test task.",
                start_date="2025-11-13T03:00:00+0000",
                due_date="2025-11-14T03:00:00+0000",
            ),
        )
        print(task.model_dump())
        ```

        will output:
        ```json
        {
            "id": "67eca3b78f08cf38dda26ca4",
            "project_id": "67eca3918f08e7c706354740",
            "title": "Test Task",
            "is_all_day": false,
            "completed_time": null,
            "content": "This is a test task.",
            "desc": null,
            "due_date": "2025-11-14T03:00:00.000+0000",
            "items": null,
            "priority": 0,
            "reminders": null,
            "repeat_flag": null,
            "sort_order": -1099511627776,
            "start_date": "2025-11-14T03:00:00.000+0000",
            "status": false,
            "time_zone": "America/Chicago",
            "tags": [],
            "etag": "8yp4pfmh",
            "kind": "TEXT"
        }
        ```
    Args:
        data (Union[CreateTaskV1, dict[str, Any]]): Data to create the task.

    Returns:
        TaskRespV1: Created task object.
    """
    if isinstance(data, dict):
        data = CreateTaskV1.model_validate(data)
    resp = self._post_api_v1("/task", self._model_dump(data))
    return TaskRespV1.model_validate(resp)

update_task_v1

update_task_v1(
    task_id: str, data: Union[UpdateTaskV1, dict[str, Any]]
) -> TaskRespV1

Update a task in the V1 API.

This method updates an existing task in the TickTick application using the POST /task/{task_id} V1 endpoint. The data parameter can be an UpdateTaskV1 model or a dictionary that matches the same structure. The method returns the updated task as a TaskRespV1 model.

Example

from pyticktick import Client
from pyticktick.models.v1 import UpdateTaskV1

client = Client()
task = client.update_task_v1(
    task_id="67eca3b78f08cf38dda26ca4",
    data=UpdateTaskV1(
        id="67eca3b78f08cf38dda26ca4",
        project_id="67eca3918f08e7c706354740",
        title="Updated test task",
        content="This is a test task that has been updated.",
        start_date="2026-03-13T03:00:00+0000",
        due_date="2026-03-14T03:00:00+0000",
    ),
)
print(task.model_dump())

will output:

{
    "id": "67eca3b78f08cf38dda26ca4",
    "project_id": "67eca3918f08e7c706354740",
    "title": "Updated test task",
    "is_all_day": false,
    "completed_time": null,
    "content": "This is a test task that has been updated.",
    "desc": null,
    "due_date": "2026-03-14T03:00:00.000+0000",
    "items": null,
    "priority": 0,
    "reminders": null,
    "repeat_flag": null,
    "sort_order": -1099511627776,
    "start_date": "2026-03-14T03:00:00.000+0000",
    "status": false,
    "time_zone": "America/Chicago",
    "etag": "3x4xgnmn",
    "kind": "TEXT"
}

Parameters:

Name	Type	Description	Default
task_id	str	Identifier of the task to update.	required
data	Union[UpdateTaskV1, dict[str, Any]]	Data to update the task.	required

Returns:

Name	Type	Description
TaskRespV1	TaskRespV1	Updated task.

Source code in src/pyticktick/client.py

def update_task_v1(
    self,
    task_id: str,
    data: Union[UpdateTaskV1, dict[str, Any]],
) -> TaskRespV1:
    """Update a task in the V1 API.

    This method updates an existing task in the TickTick application using the
    [`POST /task/{task_id}`](https://developer.ticktick.com/docs/index.html#/openapi?id=update-task)
    V1 endpoint. The `data` parameter can be an `UpdateTaskV1` model or a dictionary
    that matches the same structure. The method returns the updated task as a
    `TaskRespV1` model.

    ??? example "Example"
        ```python hl_lines="5"
        from pyticktick import Client
        from pyticktick.models.v1 import UpdateTaskV1

        client = Client()
        task = client.update_task_v1(
            task_id="67eca3b78f08cf38dda26ca4",
            data=UpdateTaskV1(
                id="67eca3b78f08cf38dda26ca4",
                project_id="67eca3918f08e7c706354740",
                title="Updated test task",
                content="This is a test task that has been updated.",
                start_date="2026-03-13T03:00:00+0000",
                due_date="2026-03-14T03:00:00+0000",
            ),
        )
        print(task.model_dump())
        ```

        will output:
        ```json
        {
            "id": "67eca3b78f08cf38dda26ca4",
            "project_id": "67eca3918f08e7c706354740",
            "title": "Updated test task",
            "is_all_day": false,
            "completed_time": null,
            "content": "This is a test task that has been updated.",
            "desc": null,
            "due_date": "2026-03-14T03:00:00.000+0000",
            "items": null,
            "priority": 0,
            "reminders": null,
            "repeat_flag": null,
            "sort_order": -1099511627776,
            "start_date": "2026-03-14T03:00:00.000+0000",
            "status": false,
            "time_zone": "America/Chicago",
            "etag": "3x4xgnmn",
            "kind": "TEXT"
        }
        ```

    Args:
        task_id (str): Identifier of the task to update.
        data (Union[UpdateTaskV1, dict[str, Any]]): Data to update the task.

    Returns:
        TaskRespV1: Updated task.
    """
    if isinstance(data, dict):
        data = UpdateTaskV1.model_validate(data)
    resp = self._post_api_v1(f"/task/{task_id}", self._model_dump(data))
    return TaskRespV1.model_validate(resp)

complete_task_v1

complete_task_v1(project_id: str, task_id: str) -> None

Complete a task in the V1 API.

This method marks a task as completed in the TickTick application using the POST /project/{project_id}/task/{task_id}/complete V1 endpoint. The project_id and task_id parameters are the identifiers of the project and task to complete.

Example

from pyticktick import Client

client = Client()
client.complete_task_v1(
    project_id="67eca3918f08e7c706354740",
    task_id="67eca3b78f08cf38dda26ca4",
)

This will return nothing if the task is successfully completed.

Parameters:

Name	Type	Description	Default
project_id	str	Identifier of the project containing the task.	required
task_id	str	Identifier of the task to complete.	required

Raises:

Type	Description
ValueError	If there is an error in HTTP request or response, except when the response content is empty.

Source code in src/pyticktick/client.py

def complete_task_v1(self, project_id: str, task_id: str) -> None:
    """Complete a task in the V1 API.

    This method marks a task as completed in the TickTick application using the
    [`POST /project/{project_id}/task/{task_id}/complete`](https://developer.ticktick.com/docs/index.html#/openapi?id=complete-task)
    V1 endpoint. The `project_id` and `task_id` parameters are the identifiers of
    the project and task to complete.

    ??? example "Example"
        ```python hl_lines="4"
        from pyticktick import Client

        client = Client()
        client.complete_task_v1(
            project_id="67eca3918f08e7c706354740",
            task_id="67eca3b78f08cf38dda26ca4",
        )
        ```
        This will return nothing if the task is successfully completed.

    Args:
        project_id (str): Identifier of the project containing the task.
        task_id (str): Identifier of the task to complete.

    Raises:
        ValueError: If there is an error in HTTP request or response, except when
            the response content is empty.
    """
    try:
        self._post_api_v1(f"/project/{project_id}/task/{task_id}/complete")
    except ValueError as e:
        if "Response content is empty" in str(e):
            return
        raise

delete_task_v1

delete_task_v1(project_id: str, task_id: str) -> None

Delete a task in the V1 API.

This method deletes an existing task in the TickTick application using the DELETE /project/{project_id}/task/{task_id} V1 endpoint. The project_id and task_id parameters are the identifiers of the project and task to delete.

Example

from pyticktick import Client

client = Client()
client.delete_task_v1(
    project_id="67eca3918f08e7c706354740",
    task_id="67eca3b78f08cf38dda26ca4",
)

This will return nothing if the task is successfully deleted.

Parameters:

Name	Type	Description	Default
project_id	str	Identifier of the project containing the task.	required
task_id	str	Identifier of the task to delete.	required

Source code in src/pyticktick/client.py

def delete_task_v1(self, project_id: str, task_id: str) -> None:
    """Delete a task in the V1 API.

    This method deletes an existing task in the TickTick application using the
    [`DELETE /project/{project_id}/task/{task_id}`](https://developer.ticktick.com/docs/index.html#/openapi?id=delete-task)
    V1 endpoint. The `project_id` and `task_id` parameters are the identifiers of
    the project and task to delete.

    ??? example "Example"
        ```python hl_lines="4"
        from pyticktick import Client

        client = Client()
        client.delete_task_v1(
            project_id="67eca3918f08e7c706354740",
            task_id="67eca3b78f08cf38dda26ca4",
        )
        ```
        This will return nothing if the task is successfully deleted.

    Args:
        project_id (str): Identifier of the project containing the task.
        task_id (str): Identifier of the task to delete.
    """
    self._delete_api_v1(f"/project/{project_id}/task/{task_id}")