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.
openapi: 3.1.0
info:
title: ClickUp Comments 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
externalDocs:
description: ClickUp Comments API Documentation
url: https://developer.clickup.com/reference/get-task-comments
servers:
- url: https://api.clickup.com/api/v2
description: ClickUp API v2 Production Server
tags:
- name: Comments
description: >-
Operations for managing comments on tasks, views, and lists.
security:
- bearerAuth: []
paths:
/task/{task_id}/comment:
get:
operationId: getTaskComments
summary: Get task comments
description: >-
Retrieves all comments on a specific task. Comments are returned
in chronological order and include user information, timestamps,
and formatted content.
tags:
- Comments
parameters:
- $ref: '#/components/parameters/taskId'
- name: custom_task_ids
in: query
description: >-
If you want to reference a task by its custom task ID,
this value must be true.
schema:
type: boolean
- name: team_id
in: query
description: >-
Required when custom_task_ids is set to true. The Workspace ID.
schema:
type: integer
- name: start
in: query
description: >-
Unix timestamp in milliseconds to start from for pagination.
schema:
type: integer
format: int64
- name: start_id
in: query
description: >-
Comment ID to start from for pagination.
schema:
type: string
responses:
'200':
description: Successfully retrieved comments
content:
application/json:
schema:
type: object
properties:
comments:
type: array
items:
$ref: '#/components/schemas/Comment'
'401':
description: Unauthorized
'404':
description: Task not found
post:
operationId: createTaskComment
summary: Create a task comment
description: >-
Creates a new comment on a task. Comments can include plain text,
rich text formatting with mentions, and can be assigned to users
for follow-up. The assignee will be notified of the comment.
tags:
- Comments
parameters:
- $ref: '#/components/parameters/taskId'
- name: custom_task_ids
in: query
description: >-
If you want to reference a task by its custom task ID,
this value must be true.
schema:
type: boolean
- name: team_id
in: query
description: >-
Required when custom_task_ids is set to true. The Workspace ID.
schema:
type: integer
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCommentRequest'
responses:
'200':
description: Comment created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Comment'
'400':
description: Bad request
'401':
description: Unauthorized
'404':
description: Task not found
/view/{view_id}/comment:
get:
operationId: getViewComments
summary: Get view comments
description: >-
Retrieves all comments on a specific view.
tags:
- Comments
parameters:
- $ref: '#/components/parameters/viewId'
- name: start
in: query
description: >-
Unix timestamp in milliseconds to start from for pagination.
schema:
type: integer
format: int64
- name: start_id
in: query
description: >-
Comment ID to start from for pagination.
schema:
type: string
responses:
'200':
description: Successfully retrieved view comments
content:
application/json:
schema:
type: object
properties:
comments:
type: array
items:
$ref: '#/components/schemas/Comment'
'401':
description: Unauthorized
'404':
description: View not found
post:
operationId: createViewComment
summary: Create a view comment
description: >-
Creates a new comment on a view.
tags:
- Comments
parameters:
- $ref: '#/components/parameters/viewId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCommentRequest'
responses:
'200':
description: Comment created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Comment'
'400':
description: Bad request
'401':
description: Unauthorized
'404':
description: View not found
/list/{list_id}/comment:
get:
operationId: getListComments
summary: Get list comments
description: >-
Retrieves all comments on a specific list.
tags:
- Comments
parameters:
- $ref: '#/components/parameters/listId'
- name: start
in: query
description: >-
Unix timestamp in milliseconds to start from for pagination.
schema:
type: integer
format: int64
- name: start_id
in: query
description: >-
Comment ID to start from for pagination.
schema:
type: string
responses:
'200':
description: Successfully retrieved list comments
content:
application/json:
schema:
type: object
properties:
comments:
type: array
items:
$ref: '#/components/schemas/Comment'
'401':
description: Unauthorized
'404':
description: List not found
post:
operationId: createListComment
summary: Create a list comment
description: >-
Creates a new comment on a list.
tags:
- Comments
parameters:
- $ref: '#/components/parameters/listId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCommentRequest'
responses:
'200':
description: Comment created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Comment'
'400':
description: Bad request
'401':
description: Unauthorized
'404':
description: List not found
/comment/{comment_id}:
put:
operationId: updateComment
summary: Update a comment
description: >-
Updates an existing comment. The comment text and assignee can
be modified. The resolved status can also be toggled.
tags:
- Comments
parameters:
- $ref: '#/components/parameters/commentId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateCommentRequest'
responses:
'200':
description: Comment updated successfully
'400':
description: Bad request
'401':
description: Unauthorized
'404':
description: Comment not found
delete:
operationId: deleteComment
summary: Delete a comment
description: >-
Permanently deletes a comment. This action cannot be undone.
tags:
- Comments
parameters:
- $ref: '#/components/parameters/commentId'
responses:
'200':
description: Comment deleted successfully
'401':
description: Unauthorized
'404':
description: Comment not found
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
ClickUp personal API token or OAuth access token.
parameters:
taskId:
name: task_id
in: path
required: true
description: >-
The unique identifier of the task.
schema:
type: string
viewId:
name: view_id
in: path
required: true
description: >-
The unique identifier of the view.
schema:
type: string
listId:
name: list_id
in: path
required: true
description: >-
The unique identifier of the list.
schema:
type: integer
commentId:
name: comment_id
in: path
required: true
description: >-
The unique identifier of the comment.
schema:
type: integer
schemas:
Comment:
type: object
description: >-
A comment on a task, view, or list.
properties:
id:
type: string
description: >-
The unique identifier of the comment.
comment:
type: array
items:
type: object
properties:
text:
type: string
description: >-
The text content of this comment segment.
type:
type: string
description: >-
The type of comment segment (text, mention, etc.).
attributes:
type: object
description: >-
Formatting attributes for this segment.
description: >-
The comment content as an array of rich text segments.
comment_text:
type: string
description: >-
The plain text content of the comment.
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: >-
The user who created the comment.
resolved:
type: boolean
description: >-
Whether the comment has been resolved.
assignee:
type: object
nullable: true
description: >-
The user assigned to follow up on the comment.
assigned_by:
type: object
nullable: true
description: >-
The user who assigned the follow-up.
reactions:
type: array
items:
type: object
description: >-
Reactions on the comment.
date:
type: string
description: >-
Unix timestamp when the comment was created.
CreateCommentRequest:
type: object
required:
- comment_text
description: >-
Request body for creating a new comment.
properties:
comment_text:
type: string
description: >-
The plain text content of the comment.
assignee:
type: integer
description: >-
User ID to assign for follow-up.
notify_all:
type: boolean
description: >-
Notify all members who have access to the resource.
UpdateCommentRequest:
type: object
description: >-
Request body for updating an existing comment.
properties:
comment_text:
type: string
description: >-
The updated plain text content of the comment.
assignee:
type: integer
description: >-
User ID to assign for follow-up.
resolved:
type: boolean
description: >-
Whether to mark the comment as resolved.