Create Folders with ClickUp API

/ ClickUp / By

How to Create Folders with the ClickUp API

The ClickUp API lets you programmatically create folders inside a space so you can organize tasks, automate workspace setup, and integrate ClickUp with other systems.

This guide walks you through the endpoint, required parameters, and request body needed to create a folder using the ClickUp REST API.

Overview of the ClickUp Create Folder Endpoint

The ClickUp API provides a dedicated endpoint to create a folder within a specific space. The request is sent over HTTPS using POST and requires authentication through an API token.

When you create a folder, you define at least a name and the space where it will be stored. You can optionally set access settings and parent relationships depending on your plan and configuration.

ClickUp Create Folder Endpoint URL

The base endpoint for creating a folder in ClickUp is:

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

Replace {space_id} with the numeric ID of the space where you want the new folder to be created.

ClickUp Space ID Requirement

The space_id path parameter is required. You can obtain it by listing spaces via the API or from your workspace configuration. Without a valid space ID, ClickUp cannot determine where to place the new folder and the request will fail.

Authentication for the ClickUp Folder Endpoint

All calls to the ClickUp API must be authenticated. The create folder endpoint uses a personal token or app-level token supplied as an HTTP header.

Required Authorization Header

Add the following header to every request:

  • Authorization: <your_clickup_token>

Your ClickUp token authorizes the request and determines which workspace, spaces, and folders you can access or modify. Make sure you keep this token secure and never expose it in public code repositories.

Required Headers for ClickUp Requests

Along with the authorization header, you should specify the content type of the request body.

  • Content-Type: application/json

This tells ClickUp that the request body is formatted as JSON, which is required for the create folder endpoint.

ClickUp Create Folder Request Body Schema

The create folder endpoint expects a JSON body. The core property is the folder name. Additional properties may be available depending on current API features and workspace settings.

Essential JSON Fields for ClickUp Folder Creation

A minimal request body to create a folder in ClickUp includes:

  • name (string, required): The display name of the new folder.

Example JSON body:

{
  "name": "Development Roadmap"
}

Refer to the official reference to see the full body schema and any optional properties that might be supported for your ClickUp workspace.

Step-by-Step: Create a Folder in ClickUp via API

Follow these steps to send a valid create folder request to ClickUp.

1. Gather Required ClickUp Information

Before you send the request, collect:

  • Your ClickUp API token.
  • The space_id where the folder will be created.
  • The name you want for the new folder.

2. Build the ClickUp Endpoint URL

Insert your space ID into the endpoint template:

https://api.clickup.com/api/v2/space/123456/folder

Replace 123456 with your actual ClickUp space ID.

3. Configure Headers for Your ClickUp Request

Set at least these headers:

  • Authorization: <your_clickup_token>
  • Content-Type: application/json

4. Define the ClickUp Folder Body

Create a JSON object for the body, including the folder name:

{
  "name": "Product Backlog"
}

You can adapt the name to match your project structure inside ClickUp.

5. Send the Request to the ClickUp API

Use your preferred HTTP client or language. Below is a generic example in curl form:

curl -X POST 
  -H "Authorization: <your_clickup_token>" 
  -H "Content-Type: application/json" 
  -d '{"name": "Product Backlog"}' 
  https://api.clickup.com/api/v2/space/123456/folder

When the ClickUp API processes the request successfully, it returns JSON describing the new folder, including its ID, name, and associated space.

Understanding the ClickUp Create Folder Response

The response body includes data about the folder that was created. Typical fields include:

  • Folder ID.
  • Folder name.
  • Space ID and related objects.
  • Timestamps for creation and update.

Store the folder ID if you plan to create lists inside this folder or modify it later through other ClickUp endpoints.

Handling Errors from the ClickUp API

If the folder creation fails, the ClickUp API will return an HTTP error status code and an error message. Common causes include:

  • Missing or invalid authorization token.
  • Invalid or missing space_id.
  • Missing required name field in the JSON body.
  • Insufficient permissions in the ClickUp workspace.

Review the error message and verify that headers, path parameters, and JSON body all comply with the API documentation.

Best Practices When Using the ClickUp Folder Endpoint

To keep your workspace organized and API usage efficient, apply these practices:

  • Use clear, consistent folder names to mirror your project structure in ClickUp.
  • Store space IDs and folder IDs securely for reuse.
  • Avoid creating duplicate folders with identical names in the same space.
  • Implement logging for all ClickUp API calls in your automation or integration.

Testing Your ClickUp Integration

Before using the create folder endpoint in production, test it in a non-critical space. Validate that:

  • The folder is created in the correct ClickUp space.
  • Downstream automations or list creation steps behave as expected.
  • Error handling is robust for invalid input or missing permissions.

Where to Find Official ClickUp API Documentation

For the most accurate and up-to-date information about parameters, body schema, and response fields, always consult the official API reference:

Official ClickUp create folder API reference

If you need broader strategy or implementation help connecting your systems with project management tools, you can also review expert resources at Consultevo.

By following the steps above and referring to the official ClickUp documentation, you can reliably create folders via the API and integrate workspace organization 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.

Get Help

“`

Verified by MonsterInsights