# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Clickup Lists API
  version: 1.0.0
extends: openapi/clickup-lists-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/folder/{folder_id}/list'].get
  update:
    x-apievangelist-phrasing:
      intent: List the Lists in a Folder (v2)
      effect: read
      questions:
      - What Lists are inside a given ClickUp Folder?
      - Can I include archived Lists when I read a Folder's contents through v2?
      instructions:
      - text: Show the Lists in Folder {folder_id} via v2.
        slots:
          folder_id: path.folder_id
      - text: List Folder {folder_id}'s Lists with archived set to {archived}.
        slots:
          folder_id: path.folder_id
          archived: query.archived
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/folder/{folder_id}/list'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a List in a Folder (v2)
      effect: write
      questions:
      - Can I create a List in a Folder with a markdown description and due date using v2?
      - Is it possible to assign an owner and priority to a List as I create it inside a Folder?
      instructions:
      - text: Using v2, add a List named {name} to Folder {folder_id}.
        slots:
          name: requestBody.name
          folder_id: path.folder_id
      - text: Make a v2 List {name} in Folder {folder_id} due {due_date}, priority {priority}, owned by {assignee}.
        slots:
          name: requestBody.name
          folder_id: path.folder_id
          due_date: requestBody.due_date
          priority: requestBody.priority
          assignee: requestBody.assignee
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/space/{space_id}/list'].get
  update:
    x-apievangelist-phrasing:
      intent: List Lists not in a Folder (v2)
      effect: read
      questions:
      - Which Lists sit directly in a Space outside of any Folder?
      - Does v2 let me include archived folderless Lists?
      instructions:
      - text: Show Space {space_id}'s Lists that aren't in a Folder, via v2.
        slots:
          space_id: path.space_id
      - text: 'Include archived ones when listing folderless Lists in Space {space_id}: {archived}.'
        slots:
          space_id: path.space_id
          archived: query.archived
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/space/{space_id}/list'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a List directly in a Space (v2)
      effect: write
      questions:
      - Can I add a List to a Space without putting it in a Folder, using v2?
      - What fields can I set when creating a folderless List in v2?
      instructions:
      - text: Using v2, create a folderless List {name} in Space {space_id}.
        slots:
          name: requestBody.name
          space_id: path.space_id
      - text: Add List {name} straight under Space {space_id} with status {status} and markdown description {markdown_content}.
        slots:
          name: requestBody.name
          space_id: path.space_id
          status: requestBody.status
          markdown_content: requestBody.markdown_content
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/list/{list_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve a List's details (v2)
      effect: read
      questions:
      - What information does ClickUp's v2 API return about a single List?
      - Can I look up one List by its ID?
      instructions:
      - text: Get the v2 details for List {list_id}.
        slots:
          list_id: path.list_id
      - text: Show me everything about List {list_id} from the v2 endpoint.
        slots:
          list_id: path.list_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/list/{list_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Edit a List's settings (v2)
      effect: write
      questions:
      - Can I remove a List's color while renaming it through v2?
      - Is it possible to change a List's due date and priority in v2?
      instructions:
      - text: Using v2, rename List {list_id} to {name}.
        slots:
          list_id: path.list_id
          name: requestBody.name
      - text: 'Set v2 List {list_id} (named {name}) to due {due_date} with priority {priority}, clearing its color: {unset_status}.'
        slots:
          list_id: path.list_id
          name: requestBody.name
          due_date: requestBody.due_date
          priority: requestBody.priority
          unset_status: requestBody.unset_status
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/list/{list_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a List (v2)
      effect: destructive
      questions:
      - How can I delete a List from my Workspace with v2?
      - What gets removed when a List is deleted via the v2 endpoint?
      instructions:
      - text: Delete List {list_id} via v2.
        slots:
          list_id: path.list_id
      - text: Remove the v2 List {list_id} from my Workspace.
        slots:
          list_id: path.list_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/list/{list_id}/task/{task_id}'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a task to an additional List
      effect: write
      questions:
      - Can one task live in more than one List at the same time?
      - Which ClickApp must be enabled to put a task in a second List?
      instructions:
      - text: Add task {task_id} to List {list_id} as an additional List.
        slots:
          task_id: path.task_id
          list_id: path.list_id
      - text: Also show task {task_id} in List {list_id} without moving it from its home.
        slots:
          task_id: path.task_id
          list_id: path.list_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/list/{list_id}/task/{task_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a task from an additional List
      effect: destructive
      questions:
      - Can I take a task out of a secondary List while keeping it in its home List?
      - Why can't a task be removed from its home List?
      instructions:
      - text: Remove task {task_id} from the additional List {list_id}.
        slots:
          task_id: path.task_id
          list_id: path.list_id
      - text: Stop showing task {task_id} in secondary List {list_id}.
        slots:
          task_id: path.task_id
          list_id: path.list_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/folder/{folder_id}/list_template/{template_id}'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a List from a template in a Folder
      effect: write
      questions:
      - Can I spin up a new List in a Folder from one of my List templates?
      - Do public templates need to be added to my Workspace before I use them for a Folder List?
      instructions:
      - text: Create List {name} in Folder {folder_id} from template {template_id}.
        slots:
          name: requestBody.name
          folder_id: path.folder_id
          template_id: path.template_id
      - text: Use List template {template_id} to build {name} inside Folder {folder_id} with options {options}.
        slots:
          template_id: path.template_id
          name: requestBody.name
          folder_id: path.folder_id
          options: requestBody.options
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/space/{space_id}/list_template/{template_id}'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a List from a template in a Space
      effect: write
      questions:
      - Can a List template be applied directly in a Space, outside any Folder?
      - What options can I pass when generating a Space List from a template?
      instructions:
      - text: Create List {name} in Space {space_id} from template {template_id}.
        slots:
          name: requestBody.name
          space_id: path.space_id
          template_id: path.template_id
      - text: Apply List template {template_id} at the Space level of {space_id} as {name}.
        slots:
          template_id: path.template_id
          space_id: path.space_id
          name: requestBody.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/folder/{folder_id}/list'].get
  update:
    x-apievangelist-phrasing:
      intent: List a Folder's Lists (legacy path)
      effect: read
      questions:
      - On the older unversioned path, how do I fetch every List under a Folder?
      - Does the legacy Folder lists endpoint return archived ones too?
      instructions:
      - text: On the legacy path, fetch all Lists under Folder {folder_id}.
        slots:
          folder_id: path.folder_id
      - text: 'Using the older endpoint, pull Folder {folder_id}''s Lists including archived: {archived}.'
        slots:
          folder_id: path.folder_id
          archived: query.archived
      method: generated
      generated: '2026-09-26'
- target: $.paths['/folder/{folder_id}/list'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a List in a Folder (legacy path)
      effect: write
      questions:
      - Does the legacy unversioned API create Lists under a Folder?
      - On the older path, can a new Folder List get a content description?
      instructions:
      - text: On the legacy path, make List {name} under Folder {folder_id}.
        slots:
          name: requestBody.name
          folder_id: path.folder_id
      - text: Using the older endpoint, set up List {name} in {folder_id} with content {content}.
        slots:
          name: requestBody.name
          folder_id: path.folder_id
          content: requestBody.content
      method: generated
      generated: '2026-09-26'
- target: $.paths['/space/{space_id}/list'].get
  update:
    x-apievangelist-phrasing:
      intent: List folderless Lists (legacy path)
      effect: read
      questions:
      - On the older unversioned API, where are Lists that sit directly under a Space?
      - Can the legacy path return archived folderless Lists?
      instructions:
      - text: On the legacy path, fetch Lists sitting directly under Space {space_id}.
        slots:
          space_id: path.space_id
      - text: 'Using the older endpoint, pull Space-level Lists for {space_id}, archived: {archived}.'
        slots:
          space_id: path.space_id
          archived: query.archived
      method: generated
      generated: '2026-09-26'
- target: $.paths['/space/{space_id}/list'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a folderless List (legacy path)
      effect: write
      questions:
      - Can the older unversioned endpoint make a List right under a Space?
      - On the legacy path, can a Space-level List get a due date?
      instructions:
      - text: On the legacy path, make Space-level List {name} in {space_id}.
        slots:
          name: requestBody.name
          space_id: path.space_id
      - text: Using the older endpoint, set up List {name} under Space {space_id} due {due_date}.
        slots:
          name: requestBody.name
          space_id: path.space_id
          due_date: requestBody.due_date
      method: generated
      generated: '2026-09-26'
- target: $.paths['/list/{list_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve a List (legacy path)
      effect: read
      questions:
      - Does the legacy unversioned List lookup include its statuses?
      - On the older path, how do I read one List's configuration?
      instructions:
      - text: On the legacy path, read List {list_id} with its statuses.
        slots:
          list_id: path.list_id
      - text: Using the older endpoint, describe the configuration of List {list_id}.
        slots:
          list_id: path.list_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/list/{list_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Edit a List (legacy path)
      effect: write
      questions:
      - Can the older unversioned endpoint change a List's assignee only?
      - On the legacy path, is the List name optional when editing?
      instructions:
      - text: On the legacy path, reassign List {list_id} to {assignee}.
        slots:
          list_id: path.list_id
          assignee: requestBody.assignee
      - text: Using the older endpoint, retitle List {list_id} as {name} and rewrite its content as {content}.
        slots:
          list_id: path.list_id
          name: requestBody.name
          content: requestBody.content
      method: generated
      generated: '2026-09-26'
- target: $.paths['/list/{list_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a List and its tasks (legacy path)
      effect: destructive
      questions:
      - Does erasing a List on the older unversioned path also destroy all its tasks?
      - Can a List removed through the legacy endpoint be undone?
      instructions:
      - text: Permanently erase List {list_id} and every task in it on the legacy path.
        slots:
          list_id: path.list_id
      - text: Using the older endpoint, wipe out List {list_id}.
        slots:
          list_id: path.list_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/list/{list_id}/member'].get
  update:
    x-apievangelist-phrasing:
      intent: List who has access to a List
      effect: read
      questions:
      - Who can see a particular List?
      - Which people have been given access to one List?
      instructions:
      - text: Show the members with access to List {list_id}.
        slots:
          list_id: path.list_id
      - text: List everyone who can open List {list_id}.
        slots:
          list_id: path.list_id
      method: generated
      generated: '2026-09-26'