clickup Spaces API

openapi: 3.1.0
info:
  title: ClickUp Comments Authorization Spaces API
  description: The ClickUp Comments API provides endpoints for creating and retrieving comments on tasks, views, and lists. Comments support rich text formatting, mentions, and attachments. Developers can use this API to build integrations that synchronize discussions between ClickUp and other collaboration tools, or to programmatically add status updates and notes to tasks.
  version: '2.0'
  contact:
    name: ClickUp Support
    url: https://help.clickup.com
  termsOfService: https://clickup.com/terms
servers:
- url: https://api.clickup.com/api/v2
  description: ClickUp API v2 Production Server
security:
- bearerAuth: []
tags:
- name: Spaces
  description: Operations for managing Spaces within a ClickUp Workspace.
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:
  schemas:
    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.
    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
    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.
  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
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: ClickUp personal API token or OAuth access token.
externalDocs:
  description: ClickUp Comments API Documentation
  url: https://developer.clickup.com/reference/get-task-comments