clickup Teams API

openapi: 3.1.0
info:
  title: ClickUp Comments Authorization Teams 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: Teams
  description: Operations for retrieving Workspace (team) information and membership.
paths:
  /team:
    get:
      operationId: getTeams
      summary: Get authorized teams (workspaces)
      description: Retrieves the Workspaces (teams) that the authenticated user has access to. Returns Workspace details including name, color, avatar, and a list of members with their roles and permissions.
      tags:
      - Teams
      responses:
        '200':
          description: Successfully retrieved teams
          content:
            application/json:
              schema:
                type: object
                properties:
                  teams:
                    type: array
                    items:
                      $ref: '#/components/schemas/Team'
        '401':
          description: Unauthorized
  /team/{team_id}/seats:
    get:
      operationId: getTeamSeats
      summary: Get workspace seats
      description: Retrieves the seat allocation information for a Workspace, including the total number of seats, filled seats, and empty seats.
      tags:
      - Teams
      parameters:
      - $ref: '#/components/parameters/teamId'
      responses:
        '200':
          description: Successfully retrieved seat information
          content:
            application/json:
              schema:
                type: object
                properties:
                  members:
                    type: object
                    properties:
                      filled_member_seats:
                        type: integer
                        description: Number of filled member seats.
                      empty_member_seats:
                        type: integer
                        description: Number of empty member seats.
                      total_member_seats:
                        type: integer
                        description: Total number of member seats.
                  guests:
                    type: object
                    properties:
                      filled_guest_seats:
                        type: integer
                        description: Number of filled guest seats.
                      empty_guest_seats:
                        type: integer
                        description: Number of empty guest seats.
                      total_guest_seats:
                        type: integer
                        description: Total number of guest seats.
        '401':
          description: Unauthorized
        '404':
          description: Team not found
  /team/{team_id}/user:
    get:
      operationId: getTeamMembers
      summary: Get team members
      description: Retrieves the members of a Workspace, including their roles and permissions. Only available to Workspace owners and admins.
      tags:
      - Teams
      parameters:
      - $ref: '#/components/parameters/teamId'
      responses:
        '200':
          description: Successfully retrieved team members
          content:
            application/json:
              schema:
                type: object
                properties:
                  members:
                    type: array
                    items:
                      $ref: '#/components/schemas/TeamMember'
        '401':
          description: Unauthorized
        '404':
          description: Team not found
components:
  schemas:
    TeamMember:
      type: object
      description: A member of a ClickUp Workspace.
      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.
            role:
              type: integer
              description: The role code. 1 is owner, 2 is admin, 3 is member, 4 is guest.
            last_active:
              type: string
              description: Unix timestamp of last activity.
            date_joined:
              type: string
              description: Unix timestamp when the user joined.
            date_invited:
              type: string
              description: Unix timestamp when the user was invited.
          description: The user details.
        invited_by:
          type: object
          nullable: true
          properties:
            id:
              type: integer
              description: The inviter user ID.
            username:
              type: string
              description: The inviter username.
            email:
              type: string
              format: email
              description: The inviter email.
            color:
              type: string
              description: The inviter color.
            profilePicture:
              type: string
              format: uri
              nullable: true
              description: URL of the inviter profile picture.
            initials:
              type: string
              description: The inviter initials.
          description: The user who invited this member.
    Team:
      type: object
      description: A Workspace (team) object in ClickUp.
      properties:
        id:
          type: string
          description: The unique identifier of the Workspace.
        name:
          type: string
          description: The name of the Workspace.
        color:
          type: string
          description: The hex color code of the Workspace.
        avatar:
          type: string
          nullable: true
          description: The avatar URL of the Workspace.
        members:
          type: array
          items:
            $ref: '#/components/schemas/TeamMember'
          description: Members of the Workspace.
  parameters:
    teamId:
      name: team_id
      in: path
      required: true
      description: The unique identifier of the Workspace (team).
      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