How to Remove a Task from a List in ClickUp via API

This step-by-step guide explains how to remove a task from a list in ClickUp using the official REST API endpoint, including required permissions, parameters, and example requests.

Understanding the ClickUp Remove Task from List Endpoint

The ClickUp API provides a dedicated endpoint to remove an existing task from a specific list without deleting the task itself. This is useful when you want to reorganize work, clean up lists, or maintain a single task across multiple lists.

The operation is performed with an HTTP DELETE request to the following path:

/api/v2/list/{list_id}/task/{task_id}

Here is what happens when you call this endpoint:

• The task is removed from the given list.
• The task itself is not deleted from your workspace.
• The change is applied immediately if the request is valid and authorized.

You can review the official reference for this endpoint on the ClickUp Developer site at Remove task from list.

Prerequisites and Permissions in ClickUp

Before you send requests to this ClickUp API endpoint, you must meet a few prerequisites.

Required scopes in ClickUp

Your app or token must have the proper OAuth scope to manage tasks. According to the reference, you need at least the following scope:

• tasks:write – Allows updates to tasks, including removal from lists.

Without this scope, the request will fail with an authorization error.

Authentication requirements

Every API request to ClickUp must be authenticated. Depending on your setup, you will typically use:

• A personal API token for testing or simple automation.
• An OAuth 2.0 access token for production integrations.

The token is passed in the request headers. If the token is missing or invalid, the ClickUp API will reject the call.

ClickUp Endpoint URL and HTTP Method

To remove a task from a list, use the DELETE method with the following base structure:

DELETE https://api.clickup.com/api/v2/list/{list_id}/task/{task_id}

Replace the placeholders with real identifiers from your workspace:

• {list_id}: The numeric ID of the list from which you want to remove the task.
• {task_id}: The ID of the task you want to remove from that list.

These identifiers are required path parameters, and the request will fail if either is missing or invalid.

Path Parameters for the ClickUp Request

The ClickUp API call relies on two path parameters that you must supply in the URL.

list_id parameter

Description: Unique identifier of the list containing the task you want to remove.

• Type: String or numeric ID as returned by other ClickUp endpoints.
• Required: Yes.

Make sure you are using the correct list ID, especially when the same task might appear on multiple lists.

task_id parameter

Description: Unique identifier of the task to be removed from the list.

• Type: String ID as provided when the task was created or fetched from the API.
• Required: Yes.

If the task ID does not exist or does not belong to the specified list, the ClickUp API will return an error.

Required Headers for the ClickUp API Call

To successfully send the request to ClickUp, include the following headers.

• Authorization: Your API or OAuth token, typically formatted as:
  Authorization: <your_token_here>
• Content-Type: While DELETE requests for this endpoint do not send a body, including application/json is a good practice:
  Content-Type: application/json

Ensure that your token is active and associated with a user who has permission to manage tasks in the target workspace.

Example: Remove a Task from a List in ClickUp

The following example shows a typical request you might send with curl to the ClickUp API.

cURL example request

curl -X DELETE \
  "https://api.clickup.com/api/v2/list/123456/task/9hjklm" \
  -H "Authorization: YOUR_CLICKUP_TOKEN" \
  -H "Content-Type: application/json"

In this example:

• 123456 is the list ID.
• 9hjklm is the task ID.
• YOUR_CLICKUP_TOKEN is your personal or OAuth token.

If the request succeeds, the task is removed from list 123456, but the task remains available in other lists or locations where it was previously assigned.

Step-by-Step Process in ClickUp API

Here is a clear process you can follow each time you need to remove a task from a list through the ClickUp API.

1. Gather required IDs

1. Use the ClickUp API or web app to locate the list_id.
2. Retrieve the task_id from a task detail view or a tasks listing API endpoint.

2. Verify your permissions

1. Confirm that your token includes the tasks:write scope.
2. Make sure the associated user can edit tasks in the target workspace and list.

3. Build the request URL

1. Insert the IDs into the URL:
   https://api.clickup.com/api/v2/list/{list_id}/task/{task_id}
2. Double-check for typos to avoid 404 or 400 errors.

4. Send the DELETE request

1. Use your preferred HTTP client, CLI, or integration library.
2. Include the Authorization and Content-Type headers.

5. Handle the response

1. On success, the API confirms that the task has been removed from the list.
2. On failure, review the status code and error message to adjust your request.

Common Errors When Using the ClickUp Endpoint

When working with the ClickUp remove task from list endpoint, you may encounter a few common issues.

Invalid or missing token

If the Authorization header is missing, expired, or invalid, the ClickUp API will return an authorization error. Confirm that the token is correct and that you are including it in every request.

Insufficient scope or permissions

Without the required tasks:write scope or proper workspace permissions, the request fails. Ensure your app configuration and user rights match what is required by the ClickUp API documentation.

Incorrect IDs

Using the wrong list_id or task_id can lead to 404 or validation errors. Always verify that both values exist and that the task is actually present on the list you are targeting.

Best Practices for Managing Lists with ClickUp

When designing workflows or integrations that use this ClickUp endpoint, consider the following best practices.

• Log all requests and responses so you can troubleshoot issues quickly.
• Validate IDs before sending the delete request to reduce unnecessary errors.
• Use test workspaces or sandbox environments before applying changes to production data.
• Combine this endpoint with task creation and list assignment endpoints to build flexible automation.

Following these practices will help you maintain clean lists and consistent task structure in your workspace.

Additional Resources Beyond ClickUp Docs

For strategy, automation design, and implementation help that goes beyond the core ClickUp API reference, you can explore external resources.

• Visit Consultevo for consulting and technical implementation guidance.
• Review the official documentation for this specific endpoint directly on the ClickUp Developer site at Remove task from list.

Using these resources together with the endpoint described above will help you build reliable, maintainable integrations that keep your task lists accurate and organized.