Create Space Tags in ClickUp with the API

This guide explains how to create Space-level tags in ClickUp using the public REST API endpoint. You will learn which URL to call, what headers you need, how to format the JSON body, and how to interpret the response so you can automate consistent tagging across your workspaces.

Understanding ClickUp Space tags

Before calling the endpoint, it helps to understand what a Space tag is. In ClickUp, a Space tag is a reusable label you define at the Space level. Once created, the tag can be applied to tasks within Lists and Folders that belong to that Space, helping you categorize, filter, and report on work.

Creating Space tags with the API is ideal when you want to:

Standardize naming conventions across multiple Spaces.
Bulk-create labels before importing tasks.
Integrate ClickUp with external systems that manage tags centrally.

ClickUp API endpoint for creating Space tags

The official REST endpoint for creating a Space tag in ClickUp is POST /api/v2/space/{space_id}/tag. This endpoint is documented on the ClickUp Developer reference site.

You can view the original documentation here: Create Space Tag endpoint.

Base URL for ClickUp API requests

All calls to this endpoint are made against the API base URL:

https://api.clickup.com/api/v2/space/{space_id}/tag

Replace {space_id} with the numeric identifier of the Space where you want the tag to be available.

Authentication for ClickUp API calls

Every request to create a Space tag must be authenticated. The ClickUp API uses a personal or app-level token for authorization.

Required request headers in ClickUp

Set these headers for the POST call:

Authorization: Your ClickUp API token as a string, for example Authorization: pk_1234567890.
Content-Type: application/json.

Without the Authorization header, the request will fail with an authentication error.

Request body for creating a ClickUp Space tag

The POST body must be valid JSON and include the properties accepted by the endpoint. The core fields are:

name (string, required): The label that will appear as the tag name inside the Space.
tag_bg (string, optional): Background color of the tag in hex format, for example #0000ff.
tag_fg (string, optional): Foreground color (text color) of the tag in hex format, for example #ffffff.

A minimal JSON body must at least specify the tag name. Adding colors makes the label visually distinct in the ClickUp UI.

Example JSON payload for a ClickUp Space tag

{
  "name": "High Priority",
  "tag_bg": "#ff0000",
  "tag_fg": "#ffffff"
}

In this example, the Space tag will show as “High Priority” with a red background and white text in ClickUp.

Step-by-step: create a ClickUp Space tag

Follow these steps to perform the API call from any HTTP client or integration platform:

1. Get your ClickUp Space ID

You need the Space ID for the Space where the tag should be available. You can obtain this by:

Using a Spaces endpoint from the API to list Spaces in your Workspace.
Inspecting the URL when viewing the Space in the ClickUp web app (the Space ID appears in the path).

2. Prepare the endpoint URL

Insert your Space ID into the path:

POST https://api.clickup.com/api/v2/space/123456/tag

Replace 123456 with your actual Space ID.

3. Add required ClickUp headers

Configure your HTTP client with these headers:

Authorization: <your_clickup_api_token>
Content-Type: application/json

Make sure your token has permission to modify the target Space.

4. Build the JSON body

Create the tag definition, for example:

{
  "name": "Customer Bug",
  "tag_bg": "#ff9900",
  "tag_fg": "#000000"
}

You can re-use color schemes across Spaces to keep your ClickUp account visually consistent.

5. Send the POST request

Submit the request from your preferred tool:

REST client such as Postman or Insomnia.
Command line tools such as curl.
Server-side code in Node.js, Python, or another language that calls the ClickUp API.

Example ClickUp API request with curl

This example demonstrates how to create a Space tag using curl from the command line:

curl -X POST "https://api.clickup.com/api/v2/space/123456/tag" 
  -H "Authorization: pk_your_clickup_token" 
  -H "Content-Type: application/json" 
  -d '{
    "name": "Release Candidate",
    "tag_bg": "#1e90ff",
    "tag_fg": "#ffffff"
  }'

Update the Space ID, token, and tag details to match your own ClickUp setup.

Understanding the ClickUp response

On success, the endpoint returns a JSON representation of the created tag. Typical fields in the response include:

name: The name of the tag.
tag_bg: The background color used.
tag_fg: The foreground (text) color.
creator or related identifiers, depending on the structure returned.

Use the response to confirm that the tag name and colors match your expectations before applying the tag to tasks elsewhere in ClickUp.

Error handling when using the ClickUp API

If the request fails, the API will return an HTTP error code and an error message. Common issues include:

401 Unauthorized: Missing or invalid Authorization header.
403 Forbidden: Token does not have access to the Space.
404 Not Found: Space ID does not exist, or is not available to the token.
4xx Validation errors: Invalid or missing JSON fields such as an empty tag name.

Review the response body for details, fix the configuration, and resend the request.

Best practices for managing tags in ClickUp

To keep your environment organized, apply some simple standards for Space tags created via the API:

Use consistent naming, such as Priority: High, Priority: Medium, Priority: Low.
Define a limited color palette so ClickUp boards remain readable.
Avoid creating duplicates with slightly different spellings.
Document allowed tags so teammates and automation stay aligned.

Centralized management of tags via the ClickUp API helps avoid clutter and supports clean reporting.

Next steps beyond Space tags in ClickUp

After you are comfortable creating Space tags through the API, you can expand your automation by:

Applying created tags to tasks as they are imported from other systems.
Syncing labels between a CRM and ClickUp tickets.
Running scheduled scripts that ensure every Space has the same baseline tag set.

If you want expert help designing scalable workflows and API integrations around ClickUp, you can explore consulting resources at Consultevo.

By following the steps above and using the official ClickUp create Space tag endpoint, you can quickly standardize your labels, keep Spaces consistent, and integrate tags into your broader automation strategy.

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

“`