×

Delete Task Links in ClickUp

/ ClickUp / By

Delete Task Links in ClickUp via API

Managing relationships between tasks in ClickUp is essential for keeping large projects organized. Sometimes you need to remove a task-to-task relationship programmatically. This how-to guide walks you through deleting a task link using the official ClickUp API endpoint for removing a connection between two tasks.

Understanding the ClickUp task link delete endpoint

The ClickUp API provides a dedicated endpoint to delete the relationship between two existing tasks. This does not remove the tasks themselves. Instead, it deletes only the link object that represents the connection between those tasks.

According to the official API reference at the ClickUp delete task link documentation, you must send an authenticated DELETE request with the correct path parameters and authentication header.

What this ClickUp endpoint does

The delete task link endpoint:

  • Removes the association between two tasks.
  • Requires the link ID of the relationship to be removed.
  • Requires the parent task ID that owns the link.
  • Leaves both tasks and their other data intact.

Use this operation whenever a previous dependency or relationship between tasks is no longer valid in your ClickUp workspace.

Required permissions and scopes in ClickUp

Before calling the endpoint, you must ensure that your ClickUp API token or OAuth app has the correct permissions.

Scopes needed for ClickUp API access

The delete task link endpoint requires at least one of the following OAuth scopes:

  • tasks:write
  • tasks:write:own

These scopes allow your integration to modify task data in ClickUp, including managing links between tasks.

Authentication header in ClickUp requests

You must include your API token or OAuth access token using the Authorization header:

Authorization: Bearer <your_token_here>

Without this header, ClickUp will reject the request with an authentication error.

Endpoint overview for ClickUp task link deletion

The HTTP method and path for this operation are defined in the ClickUp API reference.

HTTP method and request URL

  • Method: DELETE
  • Path: /api/v2/task/{task_id}/link/{link_id}

You must replace the path parameters with actual IDs from your ClickUp workspace.

Path parameters

  • task_id: The ID of the task that owns the link you want to delete.
  • link_id: The ID of the link object that connects one task to another.

These values are required. If either is missing or invalid, ClickUp will return an error response instead of deleting the link.

Step-by-step: delete a task link in ClickUp

Follow these steps to remove a task link using the API.

1. Collect required data from ClickUp

Gather the following values:

  1. Task ID of the parent task.
  2. Link ID of the task relationship to delete.
  3. Access token with the required scopes in ClickUp.

You can obtain the link ID from earlier API responses that created or listed task links.

2. Build the ClickUp DELETE request

Create your request using the base endpoint format:

DELETE https://api.clickup.com/api/v2/task/{task_id}/link/{link_id}

Then add the authorization header. Here is an example using curl:

curl -X DELETE 
  "https://api.clickup.com/api/v2/task/<TASK_ID>/link/<LINK_ID>" 
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>"

Replace <TASK_ID>, <LINK_ID>, and <YOUR_ACCESS_TOKEN> with real values from your ClickUp environment.

3. Send the request to ClickUp

Run the request in your preferred tool or library, such as:

  • cURL in the terminal.
  • Postman or another REST client.
  • Your backend code using a standard HTTP library.

Ensure the request uses HTTPS and sends the correct header.

4. Interpret the ClickUp response

The endpoint does not return a complex response body. On success, you can expect a status code indicating that the task link was removed. If there is an error, ClickUp will return an appropriate HTTP status code and an error message describing what went wrong, such as invalid IDs, missing scopes, or an unauthorized token.

Error handling for ClickUp task link deletions

When automating task management, robust error handling is important. The ClickUp API will respond with different status codes depending on the issue.

Common issues in ClickUp API calls

  • 401 Unauthorized: Missing or invalid Authorization header.
  • 403 Forbidden: Token does not have the required scopes to modify tasks.
  • 404 Not Found: The specified task or link ID does not exist in the ClickUp workspace.
  • 429 Too Many Requests: Rate limit exceeded; you should retry after a delay.

Check the error message returned by ClickUp and adjust your request or permissions accordingly.

Best practices for using the ClickUp task link endpoint

To keep your workflows reliable, follow these guidelines whenever you delete task links in ClickUp.

Validate ClickUp IDs before sending requests

Before calling the delete endpoint, confirm that both the task ID and link ID are current and correct. You can verify them by listing task links or retrieving the task data from ClickUp.

Log ClickUp API actions

Maintain logs whenever you delete a link so you can audit changes later. Log information such as:

  • Task ID and link ID.
  • User or service that initiated the deletion.
  • Timestamp of the operation.
  • HTTP status code from the ClickUp API.

This helps you track automation behavior and troubleshoot problems quickly.

Handle ClickUp rate limits gracefully

If your integration performs many operations in a short time, implement backoff and retries when the ClickUp API returns rate limit errors. Respecting these limits ensures stable performance and prevents disruptions.

Integrating ClickUp task link deletion into your workflow

You can incorporate the delete task link endpoint into larger automation systems that manage dependencies, project templates, or cleanup jobs in ClickUp.

  • Remove outdated dependencies when projects move to a new phase.
  • Clean up links from archived tasks as part of regular maintenance.
  • Adjust relationships when cloning task structures in ClickUp.

For broader strategy around process automation and API integration with modern tools, you can review guides and consulting resources at Consultevo, then apply those patterns to your ClickUp setup.

Where to learn more about the ClickUp API

To explore advanced options and stay up to date with any changes, always refer to the official ClickUp API documentation. The most accurate and current details for deleting task links are available at the delete task link reference page.

By following the steps in this guide and the official documentation, you can confidently remove task relationships in ClickUp programmatically, keeping your workspace clean, accurate, and aligned with your evolving project structure.

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

“`

Verified by MonsterInsights