The ClickUp Spaces API provides endpoints for managing Spaces, which are the top-level organizational containers within a ClickUp Workspace. Spaces contain Folders and Lists that organize tasks into logical groupings. Developers can create, update, and delete Spaces, as well as retrieve Space details and configure Space-level settings such as enabled features and statuses.
openapi: 3.1.0
info:
title: ClickUp Spaces API
description: >-
The ClickUp Spaces API provides endpoints for managing Spaces, which
are the top-level organizational containers within a ClickUp Workspace.
Spaces contain Folders and Lists that organize tasks into logical
groupings. Developers can create, update, and delete Spaces, as well
as retrieve Space details and configure Space-level settings such as
enabled features and statuses.
version: '2.0'
contact:
name: ClickUp Support
url: https://help.clickup.com
termsOfService: https://clickup.com/terms
externalDocs:
description: ClickUp Spaces API Documentation
url: https://developer.clickup.com/reference/get-spaces
servers:
- url: https://api.clickup.com/api/v2
description: ClickUp API v2 Production Server
tags:
- name: Spaces
description: >-
Operations for managing Spaces within a ClickUp Workspace.
security:
- bearerAuth: []
paths:
/team/{team_id}/space:
get:
operationId: getSpaces
summary: Get spaces
description: >-
Retrieves all Spaces within a Workspace. Optionally includes
archived Spaces in the response.
tags:
- Spaces
parameters:
- $ref: '#/components/parameters/teamId'
- name: archived
in: query
description: >-
Include archived Spaces in the response.
schema:
type: boolean
default: false
responses:
'200':
description: Successfully retrieved spaces
content:
application/json:
schema:
type: object
properties:
spaces:
type: array
items:
$ref: '#/components/schemas/Space'
'401':
description: Unauthorized
post:
operationId: createSpace
summary: Create a space
description: >-
Creates a new Space within a Workspace. The Space can be configured
with specific features, statuses, and multiple assignee settings.
tags:
- Spaces
parameters:
- $ref: '#/components/parameters/teamId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSpaceRequest'
responses:
'200':
description: Space created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Space'
'400':
description: Bad request
'401':
description: Unauthorized
/space/{space_id}:
get:
operationId: getSpace
summary: Get a space
description: >-
Retrieves details of a specific Space, including its features,
statuses, and configuration.
tags:
- Spaces
parameters:
- $ref: '#/components/parameters/spaceId'
responses:
'200':
description: Successfully retrieved space
content:
application/json:
schema:
$ref: '#/components/schemas/Space'
'401':
description: Unauthorized
'404':
description: Space not found
put:
operationId: updateSpace
summary: Update a space
description: >-
Updates the properties of an existing Space, including its name,
color, privacy settings, and enabled features.
tags:
- Spaces
parameters:
- $ref: '#/components/parameters/spaceId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateSpaceRequest'
responses:
'200':
description: Space updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Space'
'400':
description: Bad request
'401':
description: Unauthorized
'404':
description: Space not found
delete:
operationId: deleteSpace
summary: Delete a space
description: >-
Permanently deletes a Space and all of its contents including
Folders, Lists, and Tasks. This action cannot be undone.
tags:
- Spaces
parameters:
- $ref: '#/components/parameters/spaceId'
responses:
'200':
description: Space deleted successfully
'401':
description: Unauthorized
'404':
description: Space not found
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
ClickUp personal API token or OAuth access token.
parameters:
teamId:
name: team_id
in: path
required: true
description: >-
The unique identifier of the Workspace (team).
schema:
type: integer
spaceId:
name: space_id
in: path
required: true
description: >-
The unique identifier of the Space.
schema:
type: integer
schemas:
Space:
type: object
description: >-
A Space object representing a top-level organizational container
within a ClickUp Workspace.
properties:
id:
type: string
description: >-
The unique identifier of the Space.
name:
type: string
description: >-
The name of the Space.
private:
type: boolean
description: >-
Whether the Space is private.
color:
type: string
nullable: true
description: >-
The hex color code of the Space.
avatar:
type: string
nullable: true
description: >-
The avatar URL or emoji for the Space.
admin_can_manage:
type: boolean
description: >-
Whether admins can manage the Space.
archived:
type: boolean
description: >-
Whether the Space is archived.
members:
type: array
items:
type: object
properties:
user:
type: object
properties:
id:
type: integer
description: >-
The user ID.
username:
type: string
description: >-
The username.
email:
type: string
format: email
description: >-
The email address.
color:
type: string
description: >-
The user color.
profilePicture:
type: string
format: uri
nullable: true
description: >-
URL of the profile picture.
initials:
type: string
description: >-
The user initials.
description: >-
Members of the Space.
statuses:
type: array
items:
type: object
properties:
id:
type: string
description: >-
The status ID.
status:
type: string
description: >-
The status name.
type:
type: string
description: >-
The status type.
orderindex:
type: integer
description: >-
The order index.
color:
type: string
description: >-
The hex color code.
description: >-
Available statuses in the Space.
multiple_assignees:
type: boolean
description: >-
Whether multiple assignees are enabled.
features:
type: object
description: >-
Enabled features for the Space.
properties:
due_dates:
type: object
properties:
enabled:
type: boolean
description: >-
Whether due dates are enabled.
start_date:
type: boolean
description: >-
Whether start dates are enabled.
remap_due_dates:
type: boolean
description: >-
Whether due date remapping is enabled.
remap_closed_due_date:
type: boolean
description: >-
Whether closed due date remapping is enabled.
time_tracking:
type: object
properties:
enabled:
type: boolean
description: >-
Whether time tracking is enabled.
tags:
type: object
properties:
enabled:
type: boolean
description: >-
Whether tags are enabled.
time_estimates:
type: object
properties:
enabled:
type: boolean
description: >-
Whether time estimates are enabled.
checklists:
type: object
properties:
enabled:
type: boolean
description: >-
Whether checklists are enabled.
custom_fields:
type: object
properties:
enabled:
type: boolean
description: >-
Whether custom fields are enabled.
remap_dependencies:
type: object
properties:
enabled:
type: boolean
description: >-
Whether dependency remapping is enabled.
dependency_warning:
type: object
properties:
enabled:
type: boolean
description: >-
Whether dependency warnings are enabled.
portfolios:
type: object
properties:
enabled:
type: boolean
description: >-
Whether portfolios are enabled.
CreateSpaceRequest:
type: object
required:
- name
description: >-
Request body for creating a new Space.
properties:
name:
type: string
description: >-
The name of the Space.
multiple_assignees:
type: boolean
description: >-
Whether to enable multiple assignees.
features:
type: object
description: >-
Features to enable for the Space.
properties:
due_dates:
type: object
properties:
enabled:
type: boolean
start_date:
type: boolean
remap_due_dates:
type: boolean
remap_closed_due_date:
type: boolean
time_tracking:
type: object
properties:
enabled:
type: boolean
tags:
type: object
properties:
enabled:
type: boolean
time_estimates:
type: object
properties:
enabled:
type: boolean
checklists:
type: object
properties:
enabled:
type: boolean
custom_fields:
type: object
properties:
enabled:
type: boolean
UpdateSpaceRequest:
type: object
description: >-
Request body for updating an existing Space.
properties:
name:
type: string
description: >-
The updated name of the Space.
color:
type: string
description: >-
The updated hex color code.
private:
type: boolean
description: >-
Whether the Space should be private.
admin_can_manage:
type: boolean
description: >-
Whether admins can manage the Space.
multiple_assignees:
type: boolean
description: >-
Whether to enable multiple assignees.
features:
type: object
description: >-
Updated features configuration.