How to Update Folders with the ClickUp API

The ClickUp platform provides a powerful REST API that lets you programmatically update folder details inside your Workspaces. This guide explains how to use the Update Folder endpoint step by step so you can reliably change folder settings in your spaces.

You will learn the required URL, method, headers, and supported request body fields, along with practical tips to avoid common mistakes when integrating with the ClickUp API.

Understanding the ClickUp Folder Update Endpoint

The Update Folder operation in ClickUp is a REST endpoint that lets you modify an existing folder in a given space. You can change its name, color, position, and some visibility options without recreating the folder or losing its tasks and lists.

This endpoint is especially useful when you want to:

Automate folder naming rules for projects or clients.
Standardize folder colors across a ClickUp space.
Reorder folders programmatically based on priority or date.
Toggle visibility flags such as hidden status.

Requirements Before Calling the ClickUp API

Before you send any request, ensure you meet these prerequisites for working with the ClickUp folder update endpoint.

1. Access to a ClickUp Workspace and Space

You must have access to the Workspace and Space that contain the folder you plan to update. The folder must already exist, and you need its unique identifier.

Workspace: Where your Space and folders live.
Space: The container in which your folder is created.
Folder: The object you are updating via the API.

2. Folder ID and Space Context in ClickUp

To update a folder, you need its folder_id. This ID is part of the path parameter in the endpoint URL. You can obtain it by listing folders in a space via other endpoints or from your existing database if you store ClickUp IDs.

Always verify that the folder belongs to the correct space in ClickUp so that your integration updates the intended resource.

3. Authentication for the ClickUp API

The endpoint requires an authentication token in the request header. Typically, you supply a personal token or OAuth token depending on your ClickUp app configuration.

Include an Authorization header.
Provide a valid token with permissions to edit folders.

Without valid authentication, ClickUp will reject the request with an error status code, usually in the 4xx range.

ClickUp Endpoint Details for Updating a Folder

The Update Folder endpoint uses standard REST conventions. Below are the structural details you must follow.

HTTP Method for ClickUp Folder Updates

The request uses the PUT method. This indicates that you are updating an existing resource and potentially replacing some of its fields.

Endpoint URL Structure

The general path for the folder update operation is:

PUT /api/v2/folder/{folder_id}

Replace {folder_id} with the actual ID of the folder you want to modify in ClickUp. The base domain and any versioning segments (such as /api/v2/) must match what is documented in the official reference.

You can review the official endpoint specification at ClickUp Update Folder API reference.

Required Headers

At minimum, you will need:

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

Use a valid token issued by your ClickUp app or account. Ensure your HTTP client sends the JSON content type so the server interprets your body correctly.

Request Body Parameters for ClickUp Folder Updates

The request body is a JSON object containing the fields you want to change. You only need to send the properties that you plan to update.

Core Folder Fields in ClickUp

name (string): The new folder name. Use this to rename the folder to match your current project or workflow.
hidden (boolean): Controls whether the folder is hidden. Set to true to hide it, or false to keep it visible.
override_assignees (boolean): Determines whether assignee settings are overridden according to higher-level defaults in ClickUp.

Color and Ordering Options

color (string): A color value for the folder. The API accepts color codes in the supported format listed in the reference.
orderindex (number): A numeric value controlling the folder position relative to other folders in the same space. Lower values generally appear earlier.

These properties let you control appearance and sorting within a ClickUp Space, which is useful if you want consistent visual cues across many automated folders.

Example JSON Body

Below is a conceptual example of a JSON body you might send. Adjust keys and values to your needs and ensure they match the official ClickUp schema:

{ "name": "Q2 Marketing", "color": "#FFAA00", "hidden": false, "orderindex": 2 }

Always refer back to the official reference to confirm which fields are currently allowed, as ClickUp may extend the schema over time.

Step-by-Step: Updating a Folder in ClickUp

Follow these steps to perform the update operation reliably.

Step 1: Collect Required IDs

Identify the target Workspace and Space where your folder resides.
Use your existing data or a listing endpoint to obtain the folder ID in ClickUp.
Verify the folder is not archived or deleted before you update it.

Step 2: Prepare the Request

Construct the URL using the folder ID: /api/v2/folder/{folder_id}.
Set the HTTP method to PUT.
Add the Authorization header with your ClickUp token.
Set Content-Type to application/json.

Step 3: Build the JSON Body

Decide which attributes of the folder you want to change.
Include only those properties in the body, such as name, color, hidden, or orderindex.
Validate your JSON format and ensure keys match the official ClickUp documentation.

Step 4: Send the Request

Use your preferred HTTP client or library (such as fetch, axios, or cURL).
Submit the PUT request to the ClickUp API.
Monitor the response code and handle errors or success data appropriately.

Step 5: Validate the Update in ClickUp

Check the response body for the updated folder object.
Confirm that the new values are present.
Optionally, open the ClickUp web or desktop app to visually confirm the changes.

Handling Responses and Errors from ClickUp

The API returns structured responses so you can confirm whether your folder update succeeded or failed.

Successful Response

On success, ClickUp typically returns:

An HTTP 2xx status code.
A JSON object representing the updated folder, including its current attributes.

Store or log this object if you need to track folder metadata or synchronize with your own database.

Error Response

If there is a problem, ClickUp returns an error status code and an explanatory message. Common error causes include:

Missing or invalid Authorization header.
Nonexistent folder ID.
Insufficient permissions to edit the folder.
Invalid or unsupported JSON fields in the request body.

Always log the error code and message so you can diagnose issues quickly.

Best Practices for Using the ClickUp Folder API

To get the most from this feature, follow these integration patterns.

Use stable IDs: Store ClickUp folder IDs in your own system so you do not rely on names that may change.
Limit unnecessary calls: Only send updates when a real change is needed to reduce API usage.
Validate input: Sanitize and validate any user input before sending it to ClickUp to prevent malformed requests.
Test in a sandbox space: Try new automation logic in a dedicated ClickUp Space before applying it to production work.

Next Steps and Further ClickUp Resources

Now that you understand how to update a folder via the ClickUp API, you can integrate this operation into broader workflows such as project provisioning, client onboarding, or reporting automation.

For advanced consulting, implementation help, or custom integration design beyond this guide, you can explore services from Consultevo, which focuses on workflow optimization and automation.

To stay aligned with the latest behavior, always reference the official ClickUp Update Folder documentation for any updates to available fields, authentication methods, or error formats.

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

“`

Update Folders with ClickUp API