API Evangelist conversational phrasing for Clickup Comments API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Clickup Comments API
  version: 1.0.0
extends: openapi/clickup-comments-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-26'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 19
- target: $.paths['/v2/task/{task_id}/comment'].get
  update:
    x-apievangelist-phrasing:
      intent: Read a task's comments, newest first (v2)
      effect: read
      questions:
      - How do I get the comments on a task through the v2 endpoint?
      - Does the v2 task comment listing return only the 25 most recent comments by default?
      - Can I page back through older task comments in v2 using start and start_id?
      instructions:
      - text: Via v2, list comments on task {task_id}.
        slots:
          task_id: path.task_id
      - text: Using v2, get task {task_id} comments older than {start} starting at comment {start_id}.
        slots:
          task_id: path.task_id
          start: query.start
          start_id: query.start_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/task/{task_id}/comment'].post
  update:
    x-apievangelist-phrasing:
      intent: Comment on a task (v2)
      effect: write
      questions:
      - What's the v2 endpoint for adding a comment to a task?
      - Can a v2 task comment be assigned to a user group?
      instructions:
      - text: Via v2, comment {comment_text} on task {task_id}.
        slots:
          comment_text: requestBody.comment_text
          task_id: path.task_id
      - text: Using v2, add comment {comment_text} to task {task_id} and assign it to group {group_assignee}.
        slots:
          comment_text: requestBody.comment_text
          task_id: path.task_id
          group_assignee: requestBody.group_assignee
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/view/{view_id}/comment'].get
  update:
    x-apievangelist-phrasing:
      intent: Read comments in a Chat view (v2)
      effect: read
      questions:
      - How can I read the comments posted in a Chat view with the v2 API?
      - Can I page through older Chat view comments in v2?
      instructions:
      - text: Via v2, list comments in Chat view {view_id}.
        slots:
          view_id: path.view_id
      - text: Using v2, get Chat view {view_id} comments before {start} from comment {start_id}.
        slots:
          view_id: path.view_id
          start: query.start
          start_id: query.start_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/view/{view_id}/comment'].post
  update:
    x-apievangelist-phrasing:
      intent: Post a comment in a Chat view (v2)
      effect: write
      questions:
      - How do I post a comment into a Chat view with the v2 endpoint?
      - Can I notify everyone when I add a v2 Chat view comment?
      instructions:
      - text: Via v2, post {comment_text} in Chat view {view_id}.
        slots:
          comment_text: requestBody.comment_text
          view_id: path.view_id
      - text: Using v2, add comment {comment_text} to Chat view {view_id} and notify all.
        slots:
          comment_text: requestBody.comment_text
          view_id: path.view_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/list/{list_id}/comment'].get
  update:
    x-apievangelist-phrasing:
      intent: Read the comments on a List (v2)
      effect: read
      questions:
      - What's the v2 way to see comments added to a List?
      - Can v2 List comments be fetched further back than the latest 25?
      instructions:
      - text: Via v2, list comments on List {list_id}.
        slots:
          list_id: path.list_id
      - text: Using v2, get List {list_id} comments older than {start} from comment {start_id}.
        slots:
          list_id: path.list_id
          start: query.start
          start_id: query.start_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/list/{list_id}/comment'].post
  update:
    x-apievangelist-phrasing:
      intent: Comment on a List (v2)
      effect: write
      questions:
      - How do I leave a comment on a List using v2?
      - Does a v2 List comment require an assignee?
      instructions:
      - text: Via v2, comment {comment_text} on List {list_id} assigned to {assignee}.
        slots:
          comment_text: requestBody.comment_text
          list_id: path.list_id
          assignee: requestBody.assignee
      - text: Using v2, add List {list_id} comment {comment_text} for {assignee} and notify everyone.
        slots:
          list_id: path.list_id
          comment_text: requestBody.comment_text
          assignee: requestBody.assignee
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/comment/{comment_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Edit, reassign or resolve a comment (v2)
      effect: write
      questions:
      - How do I replace the text of an existing comment via v2?
      - Can I resolve a comment or assign it to a group with the v2 update?
      instructions:
      - text: Via v2, change comment {comment_id} to {comment_text}, assigned to {assignee}, resolved {resolved}.
        slots:
          comment_id: path.comment_id
          comment_text: requestBody.comment_text
          assignee: requestBody.assignee
          resolved: requestBody.resolved
      - text: Using v2, assign comment {comment_id} to group {group_assignee}.
        slots:
          comment_id: path.comment_id
          group_assignee: requestBody.group_assignee
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/comment/{comment_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a comment (v2)
      effect: destructive
      questions:
      - What's the v2 endpoint for deleting a task comment?
      - Can I remove a comment by its ID through v2?
      instructions:
      - text: Via v2, delete comment {comment_id}.
        slots:
          comment_id: path.comment_id
      - text: Using the v2 endpoint, remove comment {comment_id}.
        slots:
          comment_id: path.comment_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/comment/{comment_id}/reply'].get
  update:
    x-apievangelist-phrasing:
      intent: Read the threaded replies to a comment
      effect: read
      questions:
      - How do I see the replies in a comment thread?
      - Is the parent comment included when I fetch its threaded replies?
      instructions:
      - text: List the threaded replies under comment {comment_id}.
        slots:
          comment_id: path.comment_id
      - text: Show the reply thread for comment {comment_id}.
        slots:
          comment_id: path.comment_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/comment/{comment_id}/reply'].post
  update:
    x-apievangelist-phrasing:
      intent: Reply in a comment thread
      effect: write
      questions:
      - Can I reply directly to a comment instead of adding a new one?
      - Is it possible to assign a threaded reply to someone?
      instructions:
      - text: Reply {comment_text} to comment {comment_id}.
        slots:
          comment_text: requestBody.comment_text
          comment_id: path.comment_id
      - text: Add threaded reply {comment_text} under comment {comment_id} and assign it to {assignee}.
        slots:
          comment_text: requestBody.comment_text
          comment_id: path.comment_id
          assignee: requestBody.assignee
      method: generated
      generated: '2026-09-26'
- target: $.paths['/task/{task_id}/comment'].get
  update:
    x-apievangelist-phrasing:
      intent: Read a task's comments (unversioned path)
      effect: read
      questions:
      - Which non-v2 endpoint returns a task's comments with user info and timestamps?
      - Can the unversioned task comments path be paged with start and start_id?
      instructions:
      - text: Using the unversioned path, get comments on task {task_id}.
        slots:
          task_id: path.task_id
      - text: On the non-v2 endpoint, read task {task_id} comments from comment {start_id}.
        slots:
          task_id: path.task_id
          start_id: query.start_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/task/{task_id}/comment'].post
  update:
    x-apievangelist-phrasing:
      intent: Comment on a task (unversioned path)
      effect: write
      questions:
      - Is there a non-v2 path for posting a task comment with mentions?
      - Does the assignee get notified when I add a task comment on the unversioned endpoint?
      instructions:
      - text: Using the unversioned path, comment {comment_text} on task {task_id}.
        slots:
          comment_text: requestBody.comment_text
          task_id: path.task_id
      - text: On the non-v2 endpoint, add comment {comment_text} to task {task_id} for follow-up by {assignee}.
        slots:
          comment_text: requestBody.comment_text
          task_id: path.task_id
          assignee: requestBody.assignee
      method: generated
      generated: '2026-09-26'
- target: $.paths['/view/{view_id}/comment'].get
  update:
    x-apievangelist-phrasing:
      intent: Read a view's comments (unversioned path)
      effect: read
      questions:
      - Which non-v2 endpoint returns all comments on a view?
      - Can I read view comments from the unversioned path?
      instructions:
      - text: Using the unversioned path, get comments on view {view_id}.
        slots:
          view_id: path.view_id
      - text: On the non-v2 endpoint, list comments for view {view_id}.
        slots:
          view_id: path.view_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/view/{view_id}/comment'].post
  update:
    x-apievangelist-phrasing:
      intent: Comment on a view (unversioned path)
      effect: write
      questions:
      - Is there a non-v2 path for adding a comment to a view?
      - Can a view comment posted through the unversioned endpoint be assigned?
      instructions:
      - text: Using the unversioned path, comment {comment_text} on view {view_id}.
        slots:
          comment_text: requestBody.comment_text
          view_id: path.view_id
      - text: On the non-v2 endpoint, post {comment_text} to view {view_id} assigned to {assignee}.
        slots:
          comment_text: requestBody.comment_text
          view_id: path.view_id
          assignee: requestBody.assignee
      method: generated
      generated: '2026-09-26'
- target: $.paths['/list/{list_id}/comment'].get
  update:
    x-apievangelist-phrasing:
      intent: Read a List's comments (unversioned path)
      effect: read
      questions:
      - Which non-v2 endpoint lists all comments on a List?
      - Can I fetch List comments from the unversioned path?
      instructions:
      - text: Using the unversioned path, get comments on List {list_id}.
        slots:
          list_id: path.list_id
      - text: On the non-v2 endpoint, read the comments for List {list_id}.
        slots:
          list_id: path.list_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/list/{list_id}/comment'].post
  update:
    x-apievangelist-phrasing:
      intent: Comment on a List (unversioned path)
      effect: write
      questions:
      - Is there a non-v2 path for leaving a comment on a List without an assignee?
      - Can I notify everyone when commenting on a List through the unversioned endpoint?
      instructions:
      - text: Using the unversioned path, comment {comment_text} on List {list_id}.
        slots:
          comment_text: requestBody.comment_text
          list_id: path.list_id
      - text: On the non-v2 endpoint, post List comment {comment_text} to {list_id} and notify all.
        slots:
          comment_text: requestBody.comment_text
          list_id: path.list_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/comment/{comment_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a comment (unversioned path)
      effect: write
      questions:
      - Which non-v2 endpoint lets me edit a comment's text or toggle it resolved?
      - Can I change just a comment's assignee on the unversioned path?
      instructions:
      - text: Using the unversioned path, update comment {comment_id} text to {comment_text}.
        slots:
          comment_id: path.comment_id
          comment_text: requestBody.comment_text
      - text: On the non-v2 endpoint, set comment {comment_id} resolved to {resolved}.
        slots:
          comment_id: path.comment_id
          resolved: requestBody.resolved
      method: generated
      generated: '2026-09-26'
- target: $.paths['/comment/{comment_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Permanently delete a comment (unversioned path)
      effect: destructive
      questions:
      - Is deleting a comment on the non-v2 endpoint reversible?
      - What's the unversioned path for removing a comment?
      instructions:
      - text: Using the unversioned path, permanently delete comment {comment_id}.
        slots:
          comment_id: path.comment_id
      - text: On the non-v2 endpoint, remove comment {comment_id} for good.
        slots:
          comment_id: path.comment_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v3/workspaces/{workspace_id}/comments/types/{comment_type}/subtypes'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the post subtype IDs for chat posts
      effect: read
      questions:
      - Where do I find the IDs for Announcement, Discussion, Idea and Update post types?
      - Which subtype ID should I pass when sending a chat message as a post?
      instructions:
      - text: Get the post subtype IDs for comment type {comment_type} in Workspace {workspace_id}.
        slots:
          comment_type: path.comment_type
          workspace_id: path.workspace_id
      - text: List the Announcement, Discussion, Idea and Update subtype IDs in Workspace {workspace_id} for type {comment_type}.
        slots:
          workspace_id: path.workspace_id
          comment_type: path.comment_type
      method: generated
      generated: '2026-09-26'