How to Add Tags to Tasks with the ClickUp API

Using the ClickUp REST API, you can programmatically add tags to tasks to streamline organization, automation, and integrations. This how-to guide explains the exact endpoint, required headers, URL parameters, and JSON payload you need to successfully attach tags to a task.

Understanding the ClickUp Tag Endpoint

To add a tag to a task, the ClickUp API exposes a dedicated endpoint that accepts a POST request. This endpoint is designed for scenarios where you want to apply a single tag to a specific task by its ID.

The core details are:

Method: POST
Endpoint path: /api/v2/task/{task_id}/tag/{tag_name}
Authentication: Personal token in the Authorization header
Content type: JSON

Every request must be authenticated and targeted to a specific task, so having the correct task ID and tag name is essential.

Prerequisites for Using the ClickUp API

Before calling the endpoint, make sure the following requirements are met in your ClickUp workspace and development environment:

A valid ClickUp account with API access enabled
A personal API token generated from your user settings
The ID of the task you want to modify
The workspace ID where the task belongs
An HTTPS client or tool (such as cURL, Postman, or your own code)

If you need broader consulting or implementation support around work management and automation, you can explore services from Consultevo.

Required Headers for ClickUp Requests

Every request to the ClickUp task tag endpoint must include specific HTTP headers. Without them, the request will fail or be rejected.

Authorization Header for ClickUp

The Authorization header carries your personal token. This token authenticates you with the ClickUp API and should be kept secret.

Header name: Authorization
Header value: your personal API token as a string

Example:

Authorization: <your_clickup_token>

Content-Type and Accept Headers in ClickUp

The ClickUp API uses JSON for both incoming and outgoing data. To ensure proper communication, add the following headers:

Content-Type: application/json
Accept: application/json

These headers tell the ClickUp service that you are sending JSON and expect JSON in the response.

ClickUp Endpoint URL Structure

The base path for this operation is:

POST https://api.clickup.com/api/v2/task/{task_id}/tag/{tag_name}

Two path parameters must be replaced with your actual values.

Task ID Parameter in ClickUp

The {task_id} segment identifies the task that will receive the tag.

Type: string
Location: path parameter
Required: yes

You can obtain a task ID from the task’s URL in the ClickUp web app or via other API endpoints that list tasks.

Tag Name Parameter in ClickUp

The {tag_name} segment is the exact name of the tag you want to apply.

Type: string
Location: path parameter
Required: yes

The tag name must match an existing tag in the workspace, including case and spacing.

Request Body Fields for ClickUp Tagging

The POST request body is a JSON object that currently requires the workspace ID. Even though the tag name is in the URL, the workspace context clarifies where the operation occurs.

Workspace ID in ClickUp Request Body

The JSON payload has one required field:

workspace_id — a string representing the workspace where the task and tag exist.

Example minimal request body:

{
  "workspace_id": "12345678"
}

Make sure the workspace ID is valid and associated with the authenticated user, or the ClickUp API will return an error.

Complete Example: Add a Tag to a Task in ClickUp

The following example shows how to combine headers, URL, and body to add a tag to a task using ClickUp.

cURL Example for ClickUp

curl -X POST 
  "https://api.clickup.com/api/v2/task/abc123/tag/high-priority" 
  -H "Authorization: <your_clickup_token>" 
  -H "Content-Type: application/json" 
  -H "Accept: application/json" 
  -d '{
    "workspace_id": "12345678"
  }'

Replace abc123 with your actual task ID, high-priority with your chosen tag name, and update both the token and workspace ID with real values from your ClickUp environment.

Handling ClickUp API Responses

When you send a correctly formatted request, the ClickUp API responds with JSON describing the updated task or operation status. While the exact fields may vary, watch for:

HTTP status code in the 2xx range, indicating success
A representation of the task that now includes the new tag
Error codes and messages if something went wrong

If the response indicates validation or permission errors, verify that your token, workspace ID, and task ID all match the same ClickUp workspace.

Troubleshooting Common ClickUp Tag Issues

When adding tags to tasks with the ClickUp API, you may encounter common problems. Below are frequent issues and how to resolve them.

Invalid Authentication in ClickUp

If you receive an unauthorized error, check the following:

The Authorization header is set and not empty.
Your personal token is active and has not been revoked.
The token belongs to a user who can access the target workspace and task.

Incorrect Task or Workspace in ClickUp

Not found or validation errors usually point to incorrect IDs. Confirm that:

The task_id in the URL exists in the same workspace as the token owner.
The workspace_id in the body matches the workspace of the task.
The tag_name exists as a tag in that workspace.

Request Format Errors in ClickUp

If you see errors related to JSON or content type, verify that:

Content-Type is set to application/json.
Your JSON body is properly formatted and escaped.
The request is made with POST and not another HTTP method.

Where to Find the Official ClickUp Reference

For the most accurate, up-to-date details on parameters, examples, and potential future extensions of this endpoint, consult the official documentation. You can access it directly here: ClickUp Add Tag to Task API reference.

Always rely on the official ClickUp reference if you notice discrepancies, new features, or deprecations, especially when maintaining production integrations.

Next Steps for Automating Tags in ClickUp

Once you understand how to add a tag to a single task with the ClickUp API, you can build more advanced workflows:

Loop through a list of tasks and apply a tag based on status or due date.
Connect webhook events to tagging operations for real-time reactions.
Integrate ClickUp with external systems that trigger tagging based on business rules.

By applying these patterns, you can transform simple tag operations into powerful automation across your ClickUp workspace.

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

“`

Add Tags to Tasks in ClickUp