The ClickUp Teams API provides access to Workspace-level information and membership. In the ClickUp API, Teams correspond to Workspaces, which are the top-level organizational unit. The API allows developers to retrieve a list of Workspaces the authenticated user belongs to, along with member details and roles. This is typically the starting point for navigating the ClickUp hierarchy.
openapi: 3.1.0
info:
title: ClickUp Teams (Workspaces) API
description: >-
The ClickUp Teams API provides access to Workspace-level information
and membership. In the ClickUp API, Teams correspond to Workspaces,
which are the top-level organizational unit. The API allows developers
to retrieve a list of Workspaces the authenticated user belongs to,
along with member details and roles. This is typically the starting
point for navigating the ClickUp hierarchy.
version: '2.0'
contact:
name: ClickUp Support
url: https://help.clickup.com
termsOfService: https://clickup.com/terms
externalDocs:
description: ClickUp Teams API Documentation
url: https://developer.clickup.com/reference/get-teams
servers:
- url: https://api.clickup.com/api/v2
description: ClickUp API v2 Production Server
tags:
- name: Teams
description: >-
Operations for retrieving Workspace (team) information and membership.
security:
- bearerAuth: []
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:
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
schemas:
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.
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.