How to Use the ClickUp Spaces API

The ClickUp Spaces API lets you programmatically list and configure spaces in a workspace so you can sync data, automate setup, and build custom integrations.

This how-to guide walks you through every part of the Get Spaces endpoint, including path and query parameters, response fields, and practical usage tips based strictly on the official API reference.

Understanding the ClickUp Spaces Endpoint

The Get Spaces endpoint returns all spaces for a specific team (also called a workspace). You can filter to public or private spaces and control which configuration details are included in the response.

The HTTP method and base path are:

• Method: GET
• Path: /api/v2/team/{team_id}/space

This endpoint requires authentication with a valid API token and a known team ID.

Preparing to Call the ClickUp Spaces API

Before you can retrieve space data, you need the following:

• A ClickUp account with access to the target team
• An API token with permission to view the spaces you want to query
• The numeric team_id for the workspace

Confirm that your token is added to your request headers according to the standard authentication requirements for the platform.

ClickUp Spaces API Endpoint Structure

The key element in the endpoint path is the team identifier. Replace the placeholder in the URL with your actual team ID.

ClickUp team path parameter

The endpoint path includes one required parameter:

• team_id (path, required): the unique ID of the team (workspace) whose spaces you want to retrieve.

Example structure:

GET /api/v2/team/{team_id}/space

When you send a request, the placeholder must be replaced with a real integer value for your workspace.

Using ClickUp Spaces Query Parameters

The Get Spaces endpoint supports multiple query parameters that allow you to control privacy filters, archived status, and configuration detail in the response.

Privacy and archived filters in ClickUp

These filters help you restrict which spaces are returned:

• archived (optional): filter spaces by archived status. The value is typically boolean-like and determines whether archived spaces are included.
• space_ids[] (optional, array): limit results to one or more specific spaces by ID.
• include_closed (optional): include or exclude closed spaces, if applicable.

Check your implementation language to ensure arrays such as space_ids[] are encoded according to your HTTP client rules.

Including ClickUp space settings in responses

The endpoint lets you choose which configuration details to return for each space. These flags can reduce payload size when you do not need all settings.

• include_archived: when enabled, spaces that are archived can be included in the response.
• include_inherited: when enabled, inherited settings may be included.
• include_members: when enabled, member information for each space can be returned.

The reference page also includes a payload field describing additional internal behavior for configuration options returned alongside each space.

Calling the ClickUp Spaces API Step by Step

Use the following process to call the endpoint and retrieve data in a consistent way.

1. Build your ClickUp request URL

1. Start with the base path for your environment.
2. Append /team/{team_id}/space.
3. Add query parameters for privacy, archived, and configuration details as needed.

Example pattern:

/api/v2/team/123456/space?archived=false&include_members=true

2. Add authentication headers

1. Generate or locate your API token.
2. Set the authorization header as required by the standard ClickUp API authentication scheme.
3. Confirm that the token has workspace access to the specified team.

3. Send the HTTP request

1. Use your preferred HTTP client (CLI tool, HTTP library, or API platform).
2. Send a GET request to the constructed URL with the authentication header.
3. Capture the HTTP status code and JSON body in your integration or script.

4. Handle the ClickUp Spaces response

On success, the API returns a JSON object that includes:

• An array of space objects
• Configuration details based on the options requested
• Fields describing privacy, visibility, and feature flags for each space

Your code should parse the JSON result and map each space to your application’s data model.

Interpreting ClickUp Space Response Fields

The response describes each space with IDs, names, and optional configuration properties. Typical fields include:

• A unique ID for the space
• The name of the space
• Privacy indicators
• Flags for workspace features enabled in that space

The attached payload object on various fields in the reference indicates that some values represent configuration options rather than simple strings or numbers.

Validating ClickUp configuration options

When you design an integration, validate configuration data returned from the endpoint:

• Check for null or missing values where options are not set.
• Confirm that feature flags match supported values in your environment.
• Handle unexpected fields gracefully so your integration is resilient to future changes.

Working With ClickUp Spaces in Integrations

Once you have reliable access to spaces, you can use the returned data to drive additional API calls or automation logic.

Common workflows include:

• Listing all spaces to generate a configuration dashboard
• Filtering by privacy to show only accessible workspaces for a given user
• Using space IDs to query folders, lists, and tasks in follow-up calls

For a broader consulting perspective on integration planning and automation architecture, you can review services at Consultevo.

ClickUp API Reference and Next Steps

This how-to has focused on calling the Get Spaces endpoint, configuring query parameters, and correctly handling responses. To view the full, authoritative specification for this endpoint, consult the official documentation.

You can read the complete reference for the endpoint, including additional parameter details and examples, at the ClickUp API reference.

Use that reference alongside this guide when you implement your code so that your integration stays aligned with the latest platform behavior.

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

“`