Tag

pyticktick.models.v2.parameters.tag

Parameters for creating and update tags via the V2 API.

Unofficial API

These models are part of the unofficial TickTick API. They were created by reverse engineering the API. They may be incomplete or inaccurate.

Classes:

Name	Description
CreateTagV2	Model for creating a tag via the V2 API.
DeleteTagV2	Model for deleting a tag via the V2 API.
PostBatchTagV2	Model for batch tag operations via the V2 API.
RenameTagV2	Model for renaming a tag via the V2 API.
UpdateTagV2	Model for updating a tag via the V2 API.

CreateTagV2 pydantic-model

Bases: BaseModelV2

Model for creating a tag via the V2 API.

This model is used to create a tag via the V2 API. This is not currently documented or supported in the official API docs. This is used in the PostBatchTagV2 model.

Show JSON schema:

{
  "additionalProperties": false,
  "description": "Model for creating a tag via the V2 API.\n\nThis model is used to create a tag via the V2 API. This is not currently documented\nor supported in the official API docs. This is used in the `PostBatchTagV2` model.",
  "properties": {
    "label": {
      "description": "Name of the tag to create",
      "pattern": "^[^\\\\\\/\\\"#:*?<>|\\s]+$",
      "title": "Label",
      "type": "string"
    },
    "color": {
      "anyOf": [
        {
          "format": "color",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Color of the tag, eg. '#F18181'",
      "title": "Color"
    },
    "name": {
      "anyOf": [
        {
          "pattern": "^[^\\\\\\/\\\"#:*?<>|\\sA-Z]+$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Name of the tag to create",
      "title": "Name"
    },
    "parent": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Name of the parent tag",
      "title": "Parent"
    },
    "sort_type": {
      "default": "project",
      "description": "Sort type when displaying by selected tag",
      "enum": [
        "project",
        "title",
        "tag"
      ],
      "title": "Sort Type",
      "type": "string"
    },
    "sort_order": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Sort Order"
    }
  },
  "required": [
    "label"
  ],
  "title": "CreateTagV2",
  "type": "object"
}

Fields:

• label (TagLabel)
• color (Color | None)
• name (TagName | None)
• parent (str | None)
• sort_type (Literal['project', 'title', 'tag'])
• sort_order (int | None)

Validators:

• empty_str_to_none
• _validate_name

color pydantic-field

color: Color | None = None

Color of the tag, eg. '#F18181'

label pydantic-field

label: TagLabel

Name of the tag to create

name pydantic-field

name: TagName | None = None

Name of the tag to create

parent pydantic-field

parent: str | None = None

Name of the parent tag

sort_type pydantic-field

sort_type: Literal['project', 'title', 'tag'] = 'project'

Sort type when displaying by selected tag

empty_str_to_none pydantic-validator

empty_str_to_none(v: Any) -> Any

Convert empty strings to None.

TickTick API responses sometimes conflates None and empty strings for optional fields. This validator ensures that empty strings are converted to None, which then allows for more consistent handling of the data within the library.

Parameters:

Name	Type	Description	Default
v	Any	The value to validate.	required

Returns:

Name	Type	Description
Any	Any	The input value if it is not an empty string, otherwise None.

Source code in src/pyticktick/models/v2/models.py

@field_validator("*", mode="before")
@classmethod
def empty_str_to_none(cls, v: Any) -> Any:
    """Convert empty strings to None.

    TickTick API responses sometimes conflates `None` and empty strings for
    optional fields. This validator ensures that empty strings are converted to
    `None`, which then allows for more consistent handling of the data within the
    library.

    Args:
        v (Any): The value to validate.

    Returns:
        Any: The input value if it is not an empty string, otherwise `None`.
    """
    if isinstance(v, str) and len(v) == 0:
        return None
    return v

DeleteTagV2 pydantic-model

Bases: BaseModelV2

Model for deleting a tag via the V2 API.

This model is used to delete a tag against the V2 API endpoint DELETE /tag. This is not currently documented or supported in the official API docs.

Show JSON schema:

{
  "additionalProperties": false,
  "description": "Model for deleting a tag via the V2 API.\n\nThis model is used to delete a tag against the V2 API endpoint `DELETE /tag`. This\nis not currently documented or supported in the official API docs.",
  "properties": {
    "name": {
      "description": "Identifier of the tag to delete",
      "title": "Name",
      "type": "string"
    }
  },
  "required": [
    "name"
  ],
  "title": "DeleteTagV2",
  "type": "object"
}

Fields:

• name (str)

Validators:

• empty_str_to_none

name pydantic-field

name: str

Identifier of the tag to delete

empty_str_to_none pydantic-validator

empty_str_to_none(v: Any) -> Any

Convert empty strings to None.

TickTick API responses sometimes conflates None and empty strings for optional fields. This validator ensures that empty strings are converted to None, which then allows for more consistent handling of the data within the library.

Parameters:

Name	Type	Description	Default
v	Any	The value to validate.	required

Returns:

Name	Type	Description
Any	Any	The input value if it is not an empty string, otherwise None.

Source code in src/pyticktick/models/v2/models.py

@field_validator("*", mode="before")
@classmethod
def empty_str_to_none(cls, v: Any) -> Any:
    """Convert empty strings to None.

    TickTick API responses sometimes conflates `None` and empty strings for
    optional fields. This validator ensures that empty strings are converted to
    `None`, which then allows for more consistent handling of the data within the
    library.

    Args:
        v (Any): The value to validate.

    Returns:
        Any: The input value if it is not an empty string, otherwise `None`.
    """
    if isinstance(v, str) and len(v) == 0:
        return None
    return v

PostBatchTagV2 pydantic-model

Bases: BaseModelV2

Model for batch tag operations via the V2 API.

This model is used to batch create, and update tags in bulk against the V2 API endpoint POST /batch/tag.

Note

While batch operations usually support adding, updating, and deleting, this endpoint only supports adding and updating tags. Deleting tags supported separately.

Show JSON schema:

{
  "$defs": {
    "CreateTagV2": {
      "additionalProperties": false,
      "description": "Model for creating a tag via the V2 API.\n\nThis model is used to create a tag via the V2 API. This is not currently documented\nor supported in the official API docs. This is used in the `PostBatchTagV2` model.",
      "properties": {
        "label": {
          "description": "Name of the tag to create",
          "pattern": "^[^\\\\\\/\\\"#:*?<>|\\s]+$",
          "title": "Label",
          "type": "string"
        },
        "color": {
          "anyOf": [
            {
              "format": "color",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Color of the tag, eg. '#F18181'",
          "title": "Color"
        },
        "name": {
          "anyOf": [
            {
              "pattern": "^[^\\\\\\/\\\"#:*?<>|\\sA-Z]+$",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Name of the tag to create",
          "title": "Name"
        },
        "parent": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Name of the parent tag",
          "title": "Parent"
        },
        "sort_type": {
          "default": "project",
          "description": "Sort type when displaying by selected tag",
          "enum": [
            "project",
            "title",
            "tag"
          ],
          "title": "Sort Type",
          "type": "string"
        },
        "sort_order": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Sort Order"
        }
      },
      "required": [
        "label"
      ],
      "title": "CreateTagV2",
      "type": "object"
    },
    "UpdateTagV2": {
      "additionalProperties": false,
      "description": "Model for updating a tag via the V2 API.\n\nThis model is used to update a tag via the V2 API. This is not currently documented\nor supported in the official API docs. This is used in the `PostBatchTagV2` model.",
      "properties": {
        "label": {
          "description": "Name of the tag to update",
          "pattern": "^[^\\\\\\/\\\"#:*?<>|\\s]+$",
          "title": "Label",
          "type": "string"
        },
        "color": {
          "anyOf": [
            {
              "format": "color",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Color of the tag, eg. '#F18181'",
          "title": "Color"
        },
        "name": {
          "anyOf": [
            {
              "pattern": "^[^\\\\\\/\\\"#:*?<>|\\sA-Z]+$",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Stand-in for the identifier of the tag, by default will be the tag label, but lowercase, it is recommended to not specify this field",
          "title": "Name"
        },
        "parent": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Name of the parent tag",
          "title": "Parent"
        },
        "raw_name": {
          "anyOf": [
            {
              "pattern": "^[^\\\\\\/\\\"#:*?<>|\\sA-Z]+$",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Original name of the tag, used to identify it",
          "title": "Raw Name"
        },
        "sort_type": {
          "default": "project",
          "description": "Sort type when displaying by selected tag",
          "enum": [
            "project",
            "title",
            "tag"
          ],
          "title": "Sort Type",
          "type": "string"
        },
        "sort_order": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Sort Order"
        }
      },
      "required": [
        "label"
      ],
      "title": "UpdateTagV2",
      "type": "object"
    }
  },
  "additionalProperties": false,
  "description": "Model for batch tag operations via the V2 API.\n\nThis model is used to batch create, and update tags in bulk against the V2 API\nendpoint `POST /batch/tag`.\n\n!!! note\n    While batch operations usually support adding, updating, and deleting, this\n    endpoint only supports adding and updating tags. Deleting tags supported\n    separately.",
  "properties": {
    "add": {
      "default": [],
      "description": "List of tags to add",
      "items": {
        "$ref": "#/$defs/CreateTagV2"
      },
      "title": "Add",
      "type": "array"
    },
    "update": {
      "default": [],
      "description": "List of tags to update",
      "items": {
        "$ref": "#/$defs/UpdateTagV2"
      },
      "title": "Update",
      "type": "array"
    }
  },
  "title": "PostBatchTagV2",
  "type": "object"
}

Fields:

• add (list[CreateTagV2])
• update (list[UpdateTagV2])

Validators:

• empty_str_to_none

add pydantic-field

add: list[CreateTagV2] = []

List of tags to add

update pydantic-field

update: list[UpdateTagV2] = []

List of tags to update

empty_str_to_none pydantic-validator

empty_str_to_none(v: Any) -> Any

Convert empty strings to None.

TickTick API responses sometimes conflates None and empty strings for optional fields. This validator ensures that empty strings are converted to None, which then allows for more consistent handling of the data within the library.

Parameters:

Name	Type	Description	Default
v	Any	The value to validate.	required

Returns:

Name	Type	Description
Any	Any	The input value if it is not an empty string, otherwise None.

Source code in src/pyticktick/models/v2/models.py

@field_validator("*", mode="before")
@classmethod
def empty_str_to_none(cls, v: Any) -> Any:
    """Convert empty strings to None.

    TickTick API responses sometimes conflates `None` and empty strings for
    optional fields. This validator ensures that empty strings are converted to
    `None`, which then allows for more consistent handling of the data within the
    library.

    Args:
        v (Any): The value to validate.

    Returns:
        Any: The input value if it is not an empty string, otherwise `None`.
    """
    if isinstance(v, str) and len(v) == 0:
        return None
    return v

RenameTagV2 pydantic-model

Bases: BaseModelV2

Model for renaming a tag via the V2 API.

This model is used to rename a tag via the V2 API endpoint PUT /tag/rename. This is not currently documented or supported in the official API docs.

Show JSON schema:

{
  "additionalProperties": false,
  "description": "Model for renaming a tag via the V2 API.\n\nThis model is used to rename a tag via the V2 API endpoint `PUT /tag/rename`. This\nis not currently documented or supported in the official API docs.",
  "properties": {
    "name": {
      "description": "Identifier of the tag to rename",
      "pattern": "^[^\\\\\\/\\\"#:*?<>|\\sA-Z]+$",
      "title": "Name",
      "type": "string"
    },
    "new_name": {
      "description": "New name for the tag",
      "pattern": "^[^\\\\\\/\\\"#:*?<>|\\s]+$",
      "title": "New Name",
      "type": "string"
    }
  },
  "required": [
    "name",
    "new_name"
  ],
  "title": "RenameTagV2",
  "type": "object"
}

Fields:

• name (TagName)
• new_name (TagLabel)

Validators:

• empty_str_to_none

name pydantic-field

name: TagName

Identifier of the tag to rename

new_name pydantic-field

new_name: TagLabel

New name for the tag

empty_str_to_none pydantic-validator

empty_str_to_none(v: Any) -> Any

Convert empty strings to None.

TickTick API responses sometimes conflates None and empty strings for optional fields. This validator ensures that empty strings are converted to None, which then allows for more consistent handling of the data within the library.

Parameters:

Name	Type	Description	Default
v	Any	The value to validate.	required

Returns:

Name	Type	Description
Any	Any	The input value if it is not an empty string, otherwise None.

Source code in src/pyticktick/models/v2/models.py

@field_validator("*", mode="before")
@classmethod
def empty_str_to_none(cls, v: Any) -> Any:
    """Convert empty strings to None.

    TickTick API responses sometimes conflates `None` and empty strings for
    optional fields. This validator ensures that empty strings are converted to
    `None`, which then allows for more consistent handling of the data within the
    library.

    Args:
        v (Any): The value to validate.

    Returns:
        Any: The input value if it is not an empty string, otherwise `None`.
    """
    if isinstance(v, str) and len(v) == 0:
        return None
    return v

UpdateTagV2 pydantic-model

Bases: BaseModelV2

Model for updating a tag via the V2 API.

This model is used to update a tag via the V2 API. This is not currently documented or supported in the official API docs. This is used in the PostBatchTagV2 model.

Show JSON schema:

{
  "additionalProperties": false,
  "description": "Model for updating a tag via the V2 API.\n\nThis model is used to update a tag via the V2 API. This is not currently documented\nor supported in the official API docs. This is used in the `PostBatchTagV2` model.",
  "properties": {
    "label": {
      "description": "Name of the tag to update",
      "pattern": "^[^\\\\\\/\\\"#:*?<>|\\s]+$",
      "title": "Label",
      "type": "string"
    },
    "color": {
      "anyOf": [
        {
          "format": "color",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Color of the tag, eg. '#F18181'",
      "title": "Color"
    },
    "name": {
      "anyOf": [
        {
          "pattern": "^[^\\\\\\/\\\"#:*?<>|\\sA-Z]+$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Stand-in for the identifier of the tag, by default will be the tag label, but lowercase, it is recommended to not specify this field",
      "title": "Name"
    },
    "parent": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Name of the parent tag",
      "title": "Parent"
    },
    "raw_name": {
      "anyOf": [
        {
          "pattern": "^[^\\\\\\/\\\"#:*?<>|\\sA-Z]+$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Original name of the tag, used to identify it",
      "title": "Raw Name"
    },
    "sort_type": {
      "default": "project",
      "description": "Sort type when displaying by selected tag",
      "enum": [
        "project",
        "title",
        "tag"
      ],
      "title": "Sort Type",
      "type": "string"
    },
    "sort_order": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Sort Order"
    }
  },
  "required": [
    "label"
  ],
  "title": "UpdateTagV2",
  "type": "object"
}

Fields:

• label (TagLabel)
• color (Color | None)
• name (TagName | None)
• parent (str | None)
• raw_name (TagName | None)
• sort_type (Literal['project', 'title', 'tag'])
• sort_order (int | None)

Validators:

• empty_str_to_none
• _validate_name

color pydantic-field

color: Color | None = None

Color of the tag, eg. '#F18181'

label pydantic-field

label: TagLabel

Name of the tag to update

name pydantic-field

name: TagName | None = None

Stand-in for the identifier of the tag, by default will be the tag label, but lowercase, it is recommended to not specify this field

parent pydantic-field

parent: str | None = None

Name of the parent tag

raw_name pydantic-field

raw_name: TagName | None = None

Original name of the tag, used to identify it

sort_type pydantic-field

sort_type: Literal['project', 'title', 'tag'] = 'project'

Sort type when displaying by selected tag

empty_str_to_none pydantic-validator

empty_str_to_none(v: Any) -> Any

Convert empty strings to None.

TickTick API responses sometimes conflates None and empty strings for optional fields. This validator ensures that empty strings are converted to None, which then allows for more consistent handling of the data within the library.

Parameters:

Name	Type	Description	Default
v	Any	The value to validate.	required

Returns:

Name	Type	Description
Any	Any	The input value if it is not an empty string, otherwise None.

Source code in src/pyticktick/models/v2/models.py

@field_validator("*", mode="before")
@classmethod
def empty_str_to_none(cls, v: Any) -> Any:
    """Convert empty strings to None.

    TickTick API responses sometimes conflates `None` and empty strings for
    optional fields. This validator ensures that empty strings are converted to
    `None`, which then allows for more consistent handling of the data within the
    library.

    Args:
        v (Any): The value to validate.

    Returns:
        Any: The input value if it is not an empty string, otherwise `None`.
    """
    if isinstance(v, str) and len(v) == 0:
        return None
    return v