How to Delete a Team in ClickUp Using the API
Deleting a workspace (also called a team) in ClickUp through the public API is a powerful action that should be done carefully. This how-to guide walks you through the exact steps, requirements, and best practices for sending a successful delete request to the platform.
This article is based on the official public API reference and is intended for developers and technical admins who manage workspaces programmatically.
Before You Delete a ClickUp Team
Removing a workspace is permanent and cannot be undone through the API. Before making the call, confirm that you have backed up all important information and checked with workspace owners.
Requirements for ClickUp API Access
To send a delete request for a workspace, you must:
- Use a valid personal or OAuth token for authentication
- Have owner-level access to the workspace you want to remove
- Know the correct workspace (team) ID
- Understand the impact of permanently removing a workspace
If you are new to building integrations, a specialized consultancy such as Consultevo can help you design and maintain safe automation around the ClickUp environment.
Locate the Workspace ID in ClickUp
The delete endpoint requires a numeric identifier for the workspace. Typically, you obtain this identifier by using another endpoint that lists the workspaces available to the authenticated user.
Once you have retrieved the list, choose the workspace you intend to remove and copy its identifier value for later use in the request URL.
ClickUp Delete Team Endpoint Overview
The public API exposes a dedicated endpoint to remove an entire workspace. It uses the HTTP DELETE method and must be called over HTTPS.
ClickUp API Endpoint Structure
The general structure of the endpoint is:
DELETE https://api.clickup.com/api/v2/team/<team_id>Replace <team_id> with the numeric identifier of the workspace you want to remove. Do not include angle brackets in the final request.
Authentication Header
Every request to the public API must include an authentication header. For a personal token, use:
Authorization: <your_clickup_token>Be sure to keep your token secure and never embed it in public client-side code.
Step-by-Step: Delete a ClickUp Team via API
Follow these steps to safely remove a workspace using the public interface.
1. Confirm You Really Want to Remove the Workspace
Deleting a workspace will remove its structures and related content. Before you proceed:
- Export data if you may need it later
- Verify that no active projects depend on this workspace
- Confirm with workspace owners and stakeholders
2. Gather Required ClickUp Details
Collect the following information:
- Your API token or OAuth access token
- The numeric workspace identifier
- Confirmation that the token has owner permissions on the workspace
3. Build the HTTP Request
Using a tool such as cURL, Postman, or your preferred HTTP client library, construct the request with:
- Method: DELETE
- URL: The full endpoint including the workspace identifier
- Headers: An Authorization header containing your token
- Body: No body is typically required for this operation
Example structure:
DELETE https://api.clickup.com/api/v2/team/123456
Authorization: YOUR_TOKEN_HERE4. Send the Request to ClickUp
Once the request is configured, send it to the public endpoint. The server will validate your permissions, check the workspace, and attempt to remove it.
During this process, your client should keep track of the response code and any message returned.
5. Review the Response
On success, the API returns a confirmation response. The exact body and response code come from the official specification. Check that:
- The response code indicates success (for example a 2xx status)
- The workspace is no longer present when listing teams
If the response shows an error, review the message closely to understand what went wrong.
Troubleshooting ClickUp Team Deletion
When the request fails, it is usually due to an issue with permissions, identifiers, or tokens.
Common Issues
- Invalid or missing token: Ensure the Authorization header is set and the token is active.
- Insufficient permissions: Only workspace owners can remove a workspace through the API.
- Incorrect workspace identifier: Verify the numeric value in the URL.
- Network or connectivity problems: Confirm that your client can reach the public API endpoint.
How to Verify Deletion in ClickUp
After receiving a success code, verify that the workspace no longer appears:
- Run a request that lists available workspaces
- Check that the identifier is missing from the returned list
- Confirm in the product interface that the workspace is gone
Best Practices for ClickUp Workspace Automation
Because deleting a workspace is a destructive action, it is important to build safeguards into any automation that interacts with the endpoint.
Use Environment Separation
Maintain separate tokens and workspaces for development, staging, and production. Test deletion logic in a non-production workspace before running against a live environment.
Implement Confirmation Steps
When building tools around the public API, add confirmation prompts or approval workflows before sending a deletion request. This reduces the risk of accidental removal.
Log All ClickUp API Operations
Keep structured logs of:
- The time of each delete request
- The workspace identifier targeted
- The response status code and any message
- The user or system that initiated the action
These records are helpful when auditing changes or investigating issues.
Where to Find Official ClickUp API Details
For the most accurate and up-to-date description of the delete workspace endpoint, including response formats and status codes, consult the official documentation:
Official ClickUp Delete Team API Reference
Use that reference together with this step-by-step guide to safely integrate workspace deletion into your automation workflows.
Need Help With ClickUp?
If you want expert help building, automating, or scaling your ClickUp workspace, work with ConsultEvo — trusted ClickUp Solution Partners.
“`
