How to Use the ClickUp Get Folders API

The ClickUp Get Folders API lets you list all folders in a specific space so you can manage workspaces programmatically, integrate with internal tools, and automate reporting workflows.

This guide explains how to call the endpoint, which parameters you must send, how authentication works, and what to expect in the response based strictly on the official reference.

Understanding the ClickUp Get Folders endpoint

The Get Folders operation returns the folders that belong to a single space in your workspace. It is a read-only HTTP GET endpoint designed for listing and querying folder data, not for creating or updating it.

You can use it to:

• Fetch all folders for one space to sync with another system.
• Audit folder names and statuses programmatically.
• Build custom dashboards that display folder structures.

ClickUp endpoint URL structure

The request is sent as an HTTP GET to a URL that includes the space identifier. The generic structure is:

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

Replace {space_id} with the numeric or string identifier of the space whose folders you want to retrieve. You can obtain this ID from other API calls or from your workspace configuration.

Base requirements for ClickUp API calls

All requests to this endpoint must follow these basic requirements:

• Use the HTTPS protocol.
• Include a valid API token in the request headers.
• Provide the correct path parameter for the space.

Requests that are missing authentication or contain invalid parameters will fail with an error status code, so confirm every part of the request before running it in production.

Preparing authentication for ClickUp folder requests

The Get Folders endpoint uses token-based authentication. Your token associates the request with your workspace and permissions.

Setting the ClickUp authorization header

To authenticate, add an Authorization header to your request. The value of this header must be your personal or app API token.

Example header:

Authorization: YOUR_CLICKUP_API_TOKEN

Ensure the token is stored securely. Do not embed it directly in client-side code or public repositories.

Additional recommended headers

Although the endpoint uses GET, you should explicitly set the Content-Type and, if needed, Accept headers:

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

These headers help guarantee that your integration treats all data as JSON, which simplifies parsing and validation.

Path and query parameters for ClickUp folders

The core parameter for the Get Folders endpoint is the space identifier. Depending on your use case, you might also use optional query parameters when available in the official reference.

Required path parameter

• space_id: This value identifies the space whose folders you want to list. It is placed directly in the URL path.

You cannot call the endpoint without the space identifier. If you do, the API will respond with an error because the server cannot determine which space you are targeting.

Optional query parameters

The official reference may document optional query parameters that adjust what the endpoint returns, for example toggling archived content or applying filters. Always verify the current list of supported parameters in the live documentation at the source URL.

• Only use parameters that are listed and supported.
• Omit any experimental or undocumented parameters.

Sending unsupported parameters will typically not break the request, but it may produce unexpected results or be blocked in future API versions.

Step-by-step: Call the ClickUp Get Folders API

Use the following high-level process to retrieve folders from a space.

1. Locate your ClickUp space ID

You need the space identifier before you run the request. You can obtain it from:

• Other API endpoints that list spaces.
• Internal documentation or configuration files.
• Administrative tools that expose workspace metadata.

2. Build the request URL

Insert the space ID into the endpoint path. For example:

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

Replace 12345 with the correct value for your environment, such as production, staging, or a test workspace.

3. Add the required headers

Prepare your HTTP client with these headers:

• Authorization: YOUR_CLICKUP_API_TOKEN
• Content-Type: application/json
• Accept: application/json

Confirm that the token has permission to access the target space and its folders.

4. Send the HTTP GET request

Use your preferred tool or library:

• Command line tools such as curl.
• API clients like Postman or Insomnia.
• Server-side code written in languages such as JavaScript, Python, or Java.

Always test the request in a non-production environment first to validate headers, URLs, and parameters.

5. Inspect the JSON response

On success, the endpoint returns structured JSON. The response typically includes:

• An array of folder objects.
• Properties such as ID, name, and configuration details.
• Associated metadata used by the workspace.

Use this information to populate your internal systems, build navigation structures, or trigger automation based on folder properties.

Handling ClickUp responses and errors

Robust integrations must handle both successful and failed responses gracefully. Review items such as status codes, response body, and headers on every call.

Successful responses

When the request is valid and authorized, the API returns a 2xx status code along with JSON data. In most client libraries, you should:

• Check the status code before attempting to parse the body.
• Parse the JSON into typed objects where possible.
• Validate that the expected properties, such as folder IDs and names, are present.

Error responses from the ClickUp API

If the endpoint returns a 4xx or 5xx status code, use the body to understand what went wrong. Typical causes include:

• Missing or invalid authentication token.
• Incorrect space ID value.
• Insufficient permissions for the specified space.

Log the full error response in a secure location while avoiding storage of sensitive tokens. Implement retry logic only when appropriate and never retry requests that fail due to invalid configuration or credentials.

Best practices for ClickUp folder integrations

When building production-grade integrations with the Get Folders endpoint, follow these recommendations for reliability and maintainability.

Limit request frequency

Even if the API supports high throughput, requesting the same data too often is unnecessary. Consider strategies such as:

• Caching folder data for a fixed interval.
• Refreshing only when users perform specific actions.
• Staggering calls across multiple spaces.

Respect ClickUp API changes

The official reference may evolve. To keep your integration aligned with the latest behavior:

• Monitor the API documentation for updates.
• Review new fields or deprecated properties regularly.
• Version your own integration code to handle future changes.

Secure your implementation

Treat your API token as a secret. Store it in environment variables, secret managers, or similar secure storage. Avoid:

• Checking tokens into version control.
• Embedding tokens directly in client-side code.
• Sharing tokens across unrelated environments.

Where to learn more about ClickUp APIs

For the complete and most up-to-date reference for the Get Folders operation, always consult the official documentation at the ClickUp Get Folders API page. It includes the current list of parameters, response fields, and sample requests.

If you need broader guidance on API strategy, automation design, or systems integration around this platform, you can also review expert resources and consulting services such as Consultevo, which focus on modern productivity and workflow tooling.

By combining the official reference with the structured approach in this guide, you can confidently integrate the folder structure of your workspace into custom applications, reporting pipelines, and automation workflows powered by the ClickUp platform.

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

“`