Tasks Overview

Tasks in ClickUp are the building blocks for organizing work. Each task can contain detailed information, such as descriptions, assignees, priorities, due dates, and Custom Fields. Using the ClickUp API, you can create, update, and manage tasks programmatically. When creating a task, you can set metadata like the task’s name, assignees, priority level, and time estimates. Additionally, tasks can be linked to other tasks, tagged, or customized with Custom Fields to suit specific needs. The API also allows for handling task dependencies and grouping assignees for collaborative workflows.

Here are the key components when creating a task using the ClickUp API:

• Name and description : The task’s name ( name ) and description ( description or markdown_description ).
• Assignees : Users assigned to the task, managed via an array of user IDs.
• Status and priority : The task’s status ( status ) and priority ( priority ), which follow preset values.
• Dates : Start and due dates ( start_date , due_date ), with options for including or excluding time components.
• Tags : Tags ( tags ) for categorizing tasks.
• Custom Fields : Customizable fields that allow for flexible task management, set via the custom_fields array.
• Time estimates and Sprint Points : Time estimates ( time_estimate ) for task completion, and Sprint Points ( points ) to quantify task size or effort.
• Parent and dependencies : The parent field to be defined for sub-tasks, and the links_to field to manage task dependencies.

Setting Assignees

assignees is an array of user IDs to assign to a task. You can retrieve available user IDs using the Get Teams (Workspaces) endpoint.

Setting Priority

priority corresponds to the priority levels in the ClickUp UI:

• 1 : Urgent
• 2 : High
• 3 : Normal
• 4 : Low

Priorities cannot be customized.

Setting Time Estimates

time_estimate values are in milliseconds.

Using Custom Fields

You can set Custom Fields when creating a task using the Create Task endpoint. To update Custom Fields on an existing task, use the Set Custom Field Value endpoint, as the Update Task endpoint does not support updating Custom Fields.

Formatting Task Descriptions

To include double quotation marks in text_content, description, or markdown_description fields, escape them with \".

Example:

"description": "Here is some text. \"This is speech.\" Additional text."

This appears as:

Here is some text. "This is speech." Additional text.

Using Markdown in Task Descriptions

You can use markdown_description instead of description to format task descriptions with Markdown.

Supported Markdown features include:

• Headers
• Emphasis
• Unordered/ordered lists
• Images and links
• Blockquotes
• Inline code

For more on Markdown syntax, see GitHub’s guide.

Large Requests and other Considerations

If a List contains many tasks and subtasks, the request body can become quite large, potentially causing API timeouts. We're developing API v3 to address these issues.