Delete a List in ClickUp with the REST API

This guide explains how to delete a List in ClickUp using the official REST API. You will learn the HTTP method, required headers, URL structure, and practical tips to call the endpoint safely in your integrations or automation workflows.

Understanding the ClickUp delete List endpoint

The ClickUp developer platform exposes a dedicated endpoint to remove an existing List from a Workspace. This endpoint is part of the Lists collection and is designed for permanent deletion, so it should be used carefully in production environments.

The operation is a standard HTTP DELETE request. Once called successfully, the List and its data are removed based on the behavior defined by the ClickUp API, so ensure you truly want to remove that List before sending the request.

ClickUp delete List endpoint overview

The endpoint to delete a List is:

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

• HTTP method: DELETE
• Base URL: https://api.clickup.com/api/v2
• Path: /list/{list_id}
• Authentication: personal token or OAuth token in the header

The core requirement is a valid list_id, which is a unique identifier for the target List in your ClickUp Workspace.

Required headers for ClickUp API requests

Every call to the ClickUp API must include the correct authentication header. For this operation, use your token in the Authorization header.

Authorization: <your_clickup_token>

Depending on your HTTP client or SDK, you typically set this header once for all ClickUp endpoints you call.

How to find the List ID in ClickUp

Before you can delete a List in ClickUp, you need the list_id. You can obtain it by calling other endpoints such as:

• GET /space/{space_id}/list to list all Lists in a Space
• GET /folder/{folder_id}/list to list Lists in a specific Folder

From the JSON response, note the id field for the List you want to delete. That value becomes the {list_id} path parameter in the delete request.

Step-by-step: delete a List using ClickUp API

Follow these steps to remove a List from your Workspace programmatically.

1. Prepare your ClickUp API token

Ensure you have a valid ClickUp API token with permission to manage Lists in the target Workspace. Use either:

• A personal API token for your account
• An OAuth 2.0 token if your app uses OAuth authorization

Keep this token secret and never embed it directly in client-side code.

2. Build the DELETE request URL

Insert the List ID into the endpoint path. For example:

DELETE https://api.clickup.com/api/v2/list/123456

Replace 123456 with the real ID returned by other ClickUp API endpoints.

3. Add the authorization header

In your HTTP client, add the required header:

Authorization: <your_clickup_token>

You do not need a request body for this endpoint. The authorization header and path parameter are sufficient for ClickUp to process the delete request.

4. Send the request and review the response

Send the DELETE request to the ClickUp API. The response will indicate whether the deletion succeeded or failed. Check:

• HTTP status code for success or error
• Response body for any message or error details, if provided

Handle errors gracefully, especially in automation workflows, to avoid partial operations or inconsistent state in your application.

Example: delete a ClickUp List with cURL

Here is a simple cURL example that demonstrates how to call the endpoint from a terminal or script.

curl -X DELETE 
  -H "Authorization: <your_clickup_token>" 
  https://api.clickup.com/api/v2/list/123456

Update the placeholder token and ID with your actual values. You can integrate this pattern into build scripts, deployment tooling, or scheduled jobs that manage ClickUp Lists automatically.

Best practices when deleting Lists in ClickUp

Because this operation removes data, plan your integration carefully. Consider the following recommendations:

• Confirm the List target before sending the request. Always log the list_id and name retrieved from prior ClickUp API calls.
• Implement a safety check in your application UI, such as a confirmation dialog, before calling the delete endpoint.
• Backup critical data by exporting tasks or related information to another system before deleting a key List.
• Limit who can trigger deletes in internal tools to reduce accidental removal of important Lists in ClickUp.

Common error scenarios in the ClickUp API

When calling the delete List endpoint, you may encounter common HTTP errors. Typical scenarios include:

• 401 Unauthorized: The authorization header is missing, invalid, or the token is expired.
• 403 Forbidden: The token does not have permission to delete the specified List in ClickUp.
• 404 Not Found: The list_id does not exist, is already deleted, or is not visible to the authenticated user.

Always capture and log errors from the ClickUp API so you can troubleshoot quickly in production environments.

Where to find official ClickUp API documentation

The official reference for deleting a List is maintained in the ClickUp developer docs. You can review all parameters, response details, and any updates here:

Official ClickUp delete List endpoint documentation

Consult this page regularly to stay aligned with the latest behavior and any changes introduced by the ClickUp team.

Optimizing your workflow with ClickUp integrations

Once you understand how to delete Lists via API, you can integrate this operation into broader lifecycle automation. For example, you can:

• Clean up temporary project Lists after a milestone completes
• Archive data externally, then remove old Lists in ClickUp to keep Spaces tidy
• Link your internal project system to automatically maintain Lists based on status changes

For strategic guidance on integrating the ClickUp API into complex workflows, you can explore consulting and automation services from partners such as Consultevo.

Summary: safely delete Lists with the ClickUp API

To delete a List in ClickUp through the API, use a DELETE request to /api/v2/list/{list_id} with a valid authorization token. Confirm the List ID, apply proper safeguards in your application, and monitor responses from the ClickUp endpoint for errors. With these steps, you can manage Lists programmatically while keeping your Workspace organized and secure.

Need Help With ClickUp?

If you want expert help building, automating, or scaling your ClickUp workspace, work with ConsultEvo — trusted ClickUp Solution Partners.

Get Help

“`