API Evangelist conversational phrasing for Clickup Tasks 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 Tasks API
  version: 1.0.0
extends: openapi/clickup-tasks-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: 24
- target: $.paths['/v2/list/{list_id}/task'].get
  update:
    x-apievangelist-phrasing:
      intent: List the tasks in a List (v2)
      effect: read
      questions:
      - How do I pull every task in one ClickUp List through the v2 API, 100 per page?
      - Can the v2 List task listing filter by watchers or by the date a task was done?
      - Does the v2 list of tasks include tasks that live in multiple Lists?
      instructions:
      - text: Using the v2 endpoint, list the tasks in List {list_id}.
        slots:
          list_id: path.list_id
      - text: Via v2, show tasks in List {list_id} watched by {watchers}, including tasks in multiple lists.
        slots:
          list_id: path.list_id
          watchers: query.watchers
      - text: Get v2 page {page} of tasks in List {list_id} completed after {date_done_gt}.
        slots:
          page: query.page
          list_id: path.list_id
          date_done_gt: query.date_done_gt
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/list/{list_id}/task'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a task in a List (v2)
      effect: write
      questions:
      - What do I need to send to add a new task to a List using the v2 endpoint?
      - Can I create a task with a custom task type and story points in one v2 call?
      - Is it possible to make a task that enforces required Custom Fields on creation through v2?
      instructions:
      - text: Through the v2 API, create a task named {name} in List {list_id}.
        slots:
          name: requestBody.name
          list_id: path.list_id
      - text: Via v2, add task {name} to List {list_id} worth {points} sprint points.
        slots:
          name: requestBody.name
          list_id: path.list_id
          points: requestBody.points
      - text: Using v2, create task {name} in List {list_id} as custom task type {custom_item_id}.
        slots:
          name: requestBody.name
          list_id: path.list_id
          custom_item_id: requestBody.custom_item_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/task/{task_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a task's details (v2)
      effect: read
      questions:
      - How do I look up a single task's details and attachments with the v2 endpoint?
      - Can the v2 task lookup return the task's Custom Field values and subtasks?
      - Why don't Docs attached to a task show up when I fetch it through v2?
      instructions:
      - text: Fetch task {task_id} using the v2 endpoint.
        slots:
          task_id: path.task_id
      - text: Via v2, get task {task_id} with its subtasks and markdown description.
        slots:
          task_id: path.task_id
      - text: Look up task by custom ID {task_id} in Workspace {team_id} through v2.
        slots:
          task_id: path.task_id
          team_id: query.team_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/task/{task_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a task's fields (v2)
      effect: write
      questions:
      - How can I change a task's status or priority through the v2 update endpoint?
      - Can I add watchers or group assignees when updating a task in v2?
      - Is it possible to change a task's custom task type after it has been created?
      instructions:
      - text: Via v2, set the status of task {task_id} to {status}.
        slots:
          task_id: path.task_id
          status: requestBody.status
      - text: Using the v2 endpoint, update watchers on task {task_id} to {watchers}.
        slots:
          task_id: path.task_id
          watchers: requestBody.watchers
      - text: Through v2, change task {task_id} to custom task type {custom_item_id}.
        slots:
          task_id: path.task_id
          custom_item_id: requestBody.custom_item_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/task/{task_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a task (v2)
      effect: destructive
      questions:
      - How do I remove a task from my Workspace with the v2 endpoint?
      - Can I delete a task by its custom task ID through v2?
      instructions:
      - text: Delete task {task_id} using the v2 endpoint.
        slots:
          task_id: path.task_id
      - text: Via v2, delete the task with custom ID {task_id} in Workspace {team_id}.
        slots:
          task_id: path.task_id
          team_id: query.team_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/team/{team_Id}/task'].get
  update:
    x-apievangelist-phrasing:
      intent: Filter tasks across a Workspace (v2)
      effect: read
      questions:
      - How do I find tasks across my whole Workspace that match certain filters using v2?
      - Can the v2 Workspace task filter narrow results to subtasks of one parent task?
      - Which v2 filter lets me search Workspace tasks by custom task type?
      instructions:
      - text: Via v2, list tasks across Workspace {team_Id} assigned to {assignees}.
        slots:
          team_Id: path.team_Id
          assignees: query.assignees[]
      - text: Using v2, find Workspace {team_Id} tasks under parent task {parent}.
        slots:
          team_Id: path.team_Id
          parent: query.parent
      - text: Through v2, get Workspace {team_Id} tasks of custom task type {custom_items}.
        slots:
          team_Id: path.team_Id
          custom_items: query.custom_items[]
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/task/{task_id}/merge'].post
  update:
    x-apievangelist-phrasing:
      intent: Merge several tasks into one target task
      effect: destructive
      questions:
      - Can I merge duplicate tasks into a single task?
      - What happens to source tasks when they are merged into a target task?
      - Does task merging work with custom task IDs?
      instructions:
      - text: Merge tasks {source_task_ids} into task {task_id}.
        slots:
          source_task_ids: requestBody.source_task_ids
          task_id: path.task_id
      - text: Combine the duplicate tasks {source_task_ids} into target task {task_id}.
        slots:
          source_task_ids: requestBody.source_task_ids
          task_id: path.task_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/task/{task_id}/time_in_status'].get
  update:
    x-apievangelist-phrasing:
      intent: See how long a task spent in each status (v2)
      effect: read
      questions:
      - How long has one task been sitting in each status, using the v2 endpoint?
      - Which ClickApp must be on before I can read a task's time in status?
      instructions:
      - text: Via v2, show time in status for task {task_id}.
        slots:
          task_id: path.task_id
      - text: Using v2, get the per-status durations for custom task ID {task_id} in Workspace {team_id}.
        slots:
          task_id: path.task_id
          team_id: query.team_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/task/bulk_time_in_status/task_ids'].get
  update:
    x-apievangelist-phrasing:
      intent: Get time in status for many tasks (v2)
      effect: read
      questions:
      - Can I get time-in-status numbers for several tasks in one v2 request?
      - What's the v2 way to compare how long a batch of tasks stayed in each status?
      instructions:
      - text: Via v2, get time in status for tasks {task_ids}.
        slots:
          task_ids: query.task_ids
      - text: Using the v2 bulk endpoint, compare status durations for custom task IDs {task_ids} in Workspace {team_id}.
        slots:
          task_ids: query.task_ids
          team_id: query.team_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/list/{list_id}/taskTemplate/{template_id}'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a task from a task template
      effect: write
      questions:
      - How do I spin up a new task from one of my Workspace task templates?
      - Can I use a publicly shared template to create a task?
      instructions:
      - text: Create task {name} in List {list_id} from template {template_id}.
        slots:
          name: requestBody.name
          list_id: path.list_id
          template_id: path.template_id
      - text: Use task template {template_id} to add a task called {name} to List {list_id}.
        slots:
          template_id: path.template_id
          name: requestBody.name
          list_id: path.list_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v3/workspaces/{workspace_id}/tasks/{task_id}/home_list/{list_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Move a task to a new home List
      effect: write
      questions:
      - How do I move a task to a different List?
      - Can I map old statuses to new ones when moving a task between Lists?
      - What happens to a task in multiple Lists when I move it?
      instructions:
      - text: Move task {task_id} to List {list_id} in Workspace {workspace_id}.
        slots:
          task_id: path.task_id
          list_id: path.list_id
          workspace_id: path.workspace_id
      - text: Change the home List of task {task_id} to {list_id} in Workspace {workspace_id}, using status mappings {status_mappings}.
        slots:
          task_id: path.task_id
          list_id: path.list_id
          workspace_id: path.workspace_id
          status_mappings: requestBody.status_mappings
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v3/workspaces/{workspace_id}/tasks/{task_id}/time_estimates_by_user'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace all per-user time estimates on a task
      effect: destructive
      questions:
      - How do I overwrite every per-assignee time estimate on a task at once?
      - Are existing time estimates removed if I leave them out of the replacement?
      instructions:
      - text: Replace all time estimates on task {task_id} in Workspace {workspace_id} with a new set.
        slots:
          task_id: path.task_id
          workspace_id: path.workspace_id
      - text: Wipe and reset the per-user time estimates for task {task_id} in Workspace {workspace_id}.
        slots:
          task_id: path.task_id
          workspace_id: path.workspace_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v3/workspaces/{workspace_id}/tasks/{task_id}/time_estimates_by_user'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update time estimates for specific assignees
      effect: write
      questions:
      - Can I change the time estimate for just one assignee on a task without touching the others?
      - Is there a way to set a time estimate for unassigned work on a task?
      instructions:
      - text: Update the time estimate for certain assignees on task {task_id} in Workspace {workspace_id}.
        slots:
          task_id: path.task_id
          workspace_id: path.workspace_id
      - text: Set an unassigned-work time estimate on task {task_id} in Workspace {workspace_id}, leaving other assignees as they are.
        slots:
          task_id: path.task_id
          workspace_id: path.workspace_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/list/{list_id}/task'].get
  update:
    x-apievangelist-phrasing:
      intent: List tasks in a List (unversioned path)
      effect: read
      questions:
      - What's the unversioned endpoint for listing the tasks in a List?
      - Can I order a List's tasks by due date on the non-v2 task listing path?
      instructions:
      - text: Using the unversioned path, list tasks in List {list_id}.
        slots:
          list_id: path.list_id
      - text: On the non-v2 endpoint, get tasks in List {list_id} ordered by {order_by}, including closed ones.
        slots:
          list_id: path.list_id
          order_by: query.order_by
      method: generated
      generated: '2026-09-26'
- target: $.paths['/list/{list_id}/task'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a task in a List (unversioned path)
      effect: write
      questions:
      - Which non-v2 endpoint adds a task to a List with a markdown description?
      - Can the unversioned create-task path accept a custom task ID lookup?
      instructions:
      - text: Via the unversioned path, create task {name} in List {list_id}.
        slots:
          name: requestBody.name
          list_id: path.list_id
      - text: On the non-v2 endpoint, add task {name} to List {list_id} with markdown description {markdown_description}.
        slots:
          name: requestBody.name
          list_id: path.list_id
          markdown_description: requestBody.markdown_description
      method: generated
      generated: '2026-09-26'
- target: $.paths['/task/{task_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a task by ID (unversioned path)
      effect: read
      questions:
      - Is there a non-v2 path for fetching one task with its assignees and tags?
      - Can I read a task's subtasks from the unversioned task endpoint?
      instructions:
      - text: Using the unversioned path, fetch task {task_id}.
        slots:
          task_id: path.task_id
      - text: On the non-v2 endpoint, get task {task_id} including subtasks.
        slots:
          task_id: path.task_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/task/{task_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a task (unversioned path)
      effect: write
      questions:
      - Which non-v2 endpoint updates a task while leaving omitted fields unchanged?
      - Can I archive a task through the unversioned update path?
      instructions:
      - text: Via the unversioned path, rename task {task_id} to {name}.
        slots:
          task_id: path.task_id
          name: requestBody.name
      - text: On the non-v2 endpoint, set the due date of task {task_id} to {due_date}.
        slots:
          task_id: path.task_id
          due_date: requestBody.due_date
      method: generated
      generated: '2026-09-26'
- target: $.paths['/task/{task_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Permanently delete a task (unversioned path)
      effect: destructive
      questions:
      - Is deleting a task on the non-v2 endpoint permanent?
      - What's the unversioned path for removing a task by ID?
      instructions:
      - text: Permanently delete task {task_id} via the unversioned path.
        slots:
          task_id: path.task_id
      - text: On the non-v2 endpoint, remove task {task_id} for good.
        slots:
          task_id: path.task_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/team/{team_id}/task'].get
  update:
    x-apievangelist-phrasing:
      intent: Search tasks across a Workspace (unversioned path)
      effect: read
      questions:
      - Which non-v2 endpoint searches tasks across every Space and Folder in a Workspace?
      - Can the unversioned Workspace task search filter by tags and statuses together?
      instructions:
      - text: Using the unversioned path, search Workspace {team_id} for tasks tagged {tags}.
        slots:
          team_id: path.team_id
          tags: query.tags[]
      - text: On the non-v2 endpoint, find tasks in Workspace {team_id} with status {statuses} in Spaces {space_ids}.
        slots:
          team_id: path.team_id
          statuses: query.statuses[]
          space_ids: query.space_ids[]
      method: generated
      generated: '2026-09-26'
- target: $.paths['/task/{task_id}/time_in_status'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a task's time in status (unversioned path)
      effect: read
      questions:
      - Is there a non-v2 path showing every status a task has been in and for how long?
      - Can I read one task's status history durations from the unversioned endpoint?
      instructions:
      - text: Using the unversioned path, get time in status for task {task_id}.
        slots:
          task_id: path.task_id
      - text: On the non-v2 endpoint, list how long task {task_id} sat in each status.
        slots:
          task_id: path.task_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/task/bulk_time_in_status/task_ids'].get
  update:
    x-apievangelist-phrasing:
      intent: Get bulk time in status (unversioned path)
      effect: read
      questions:
      - Which non-v2 endpoint returns time in status for multiple tasks at once?
      - Can I pass an array of task IDs to the unversioned bulk time-in-status path?
      instructions:
      - text: Using the unversioned bulk path, get time in status for tasks {task_ids}.
        slots:
          task_ids: query.task_ids[]
      - text: On the non-v2 endpoint, pull status durations for task IDs {task_ids} in one call.
        slots:
          task_ids: query.task_ids[]
      method: generated
      generated: '2026-09-26'
- target: $.paths['/list/{list_id}/task/{task_id}/member'].get
  update:
    x-apievangelist-phrasing:
      intent: List a task's assignees and watchers in a List
      effect: read
      questions:
      - Who are the assignees and watchers on a task inside a specific List?
      - Can I get a task's members by giving both its List and task ID?
      instructions:
      - text: List the assignees and watchers of task {task_id} in List {list_id}.
        slots:
          task_id: path.task_id
          list_id: path.list_id
      - text: Show who is on task {task_id} within List {list_id}.
        slots:
          task_id: path.task_id
          list_id: path.list_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/task/{task_id}/tag/{tag_name}'].post
  update:
    x-apievangelist-phrasing:
      intent: Tag a task, creating the tag if needed
      effect: write
      questions:
      - Does adding a tag to a task on the unversioned path create the tag in the Space if it's new?
      - What's the non-v2 way to tag a task?
      instructions:
      - text: Via the unversioned path, tag task {task_id} with {tag_name}, creating the tag if it doesn't exist.
        slots:
          task_id: path.task_id
          tag_name: path.tag_name
      - text: On the non-v2 endpoint, add tag {tag_name} to task {task_id}.
        slots:
          tag_name: path.tag_name
          task_id: path.task_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/task/{task_id}/tag/{tag_name}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a tag from a task (unversioned path)
      effect: destructive
      questions:
      - What's the non-v2 endpoint for untagging a task?
      - Can I strip one tag off a task through the unversioned path?
      instructions:
      - text: Via the unversioned path, remove tag {tag_name} from task {task_id}.
        slots:
          tag_name: path.tag_name
          task_id: path.task_id
      - text: On the non-v2 endpoint, untag {tag_name} from task {task_id}.
        slots:
          tag_name: path.tag_name
          task_id: path.task_id
      method: generated
      generated: '2026-09-26'