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.