API Evangelist conversational phrasing for Clickup Folders 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 Folders API
  version: 1.0.0
extends: openapi/clickup-folders-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: 12
- target: $.paths['/v2/space/{space_id}/folder'].get
  update:
    x-apievangelist-phrasing:
      intent: List the Folders in a Space (v2)
      effect: read
      questions:
      - What Folders and subfolders are in a ClickUp Space?
      - How can I tell which Folder a subfolder is nested inside when listing a Space's Folders via v2?
      - Can I include archived Folders in the v2 listing?
      instructions:
      - text: List the Folders and subfolders in Space {space_id} via v2.
        slots:
          space_id: path.space_id
      - text: Show Space {space_id}'s Folders with archived set to {archived}.
        slots:
          space_id: path.space_id
          archived: query.archived
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/space/{space_id}/folder'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a Folder or subfolder (v2)
      effect: write
      questions:
      - Can I create a subfolder inside an existing Folder with the v2 API?
      - What do I need to add a new Folder to a Space through v2?
      instructions:
      - text: Using v2, create Folder {name} in Space {space_id}.
        slots:
          name: requestBody.name
          space_id: path.space_id
      - text: Create subfolder {name} under Folder {parent_folder_id} in Space {space_id}.
        slots:
          name: requestBody.name
          parent_folder_id: requestBody.parent_folder_id
          space_id: path.space_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/folder/{folder_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve a Folder and its Lists (v2)
      effect: read
      questions:
      - Can I see a Folder's Lists together with its nested subfolders via v2?
      - How do I tell if a Folder is itself a subfolder?
      instructions:
      - text: Get v2 Folder {folder_id} with its Lists.
        slots:
          folder_id: path.folder_id
      - text: 'Show Folder {folder_id} including subfolders: {include_subfolders}.'
        slots:
          folder_id: path.folder_id
          include_subfolders: query.include_subfolders
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/folder/{folder_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Rename a Folder (v2)
      effect: write
      questions:
      - Does renaming a subfolder in v2 keep it nested under its parent?
      - Can the v2 rename call also move a Folder somewhere else?
      instructions:
      - text: Using v2, rename Folder {folder_id} to {name}.
        slots:
          folder_id: path.folder_id
          name: requestBody.name
      - text: Give v2 subfolder {folder_id} the new title {name} without moving it.
        slots:
          folder_id: path.folder_id
          name: requestBody.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/folder/{folder_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a Folder (v2)
      effect: destructive
      questions:
      - How do I delete a Folder from my Workspace with v2?
      - Is there a v2 call to get rid of an empty Folder?
      instructions:
      - text: Delete v2 Folder {folder_id}.
        slots:
          folder_id: path.folder_id
      - text: Remove Folder {folder_id} from my Workspace through v2.
        slots:
          folder_id: path.folder_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/folder/{folder_id}/position'].put
  update:
    x-apievangelist-phrasing:
      intent: Move or nest a Folder
      effect: write
      questions:
      - Can I nest one Folder inside another as a subfolder?
      - What happens to custom task types when I move a Folder to a different Space?
      instructions:
      - text: Nest Folder {folder_id} inside Folder {parent_folder_id}.
        slots:
          folder_id: path.folder_id
          parent_folder_id: requestBody.parent_folder_id
      - text: Move Folder {folder_id} to Space {space_id} as a top-level Folder at position {position}.
        slots:
          folder_id: path.folder_id
          space_id: requestBody.space_id
          position: requestBody.position
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/space/{space_id}/folder_template/{template_id}'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a Folder from a template
      effect: write
      questions:
      - Can I build a whole Folder with its Lists and tasks from a saved template?
      - Is it possible to place a templated Folder under a parent Folder?
      instructions:
      - text: Create Folder {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 Folder template {template_id} in Space {space_id} as {name} under parent {parent_folder_id}.
        slots:
          template_id: path.template_id
          space_id: path.space_id
          name: requestBody.name
          parent_folder_id: requestBody.parent_folder_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/space/{space_id}/folder'].get
  update:
    x-apievangelist-phrasing:
      intent: List a Space's Folders (legacy path)
      effect: read
      questions:
      - On the older unversioned path, how do I fetch every Folder in a Space?
      - Can the legacy endpoint return archived Folders?
      instructions:
      - text: On the legacy path, fetch all Folders in Space {space_id}.
        slots:
          space_id: path.space_id
      - text: 'Using the older endpoint, pull Space {space_id}''s Folders, archived: {archived}.'
        slots:
          space_id: path.space_id
          archived: query.archived
      method: generated
      generated: '2026-09-26'
- target: $.paths['/space/{space_id}/folder'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a Folder (legacy path)
      effect: write
      questions:
      - Does the older unversioned API make new Folders in a Space?
      - On the legacy path, is a name all a new Folder needs?
      instructions:
      - text: On the legacy path, make Folder {name} in Space {space_id}.
        slots:
          name: requestBody.name
          space_id: path.space_id
      - text: Using the older endpoint, set up a Folder titled {name} under {space_id}.
        slots:
          name: requestBody.name
          space_id: path.space_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/folder/{folder_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve a Folder (legacy path)
      effect: read
      questions:
      - On the older unversioned path, how do I read a Folder's configuration?
      - Does the legacy Folder lookup include its Lists?
      instructions:
      - text: On the legacy path, read Folder {folder_id} and its Lists.
        slots:
          folder_id: path.folder_id
      - text: Using the older endpoint, describe Folder {folder_id}.
        slots:
          folder_id: path.folder_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/folder/{folder_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a Folder (legacy path)
      effect: write
      questions:
      - Can the older unversioned endpoint edit a Folder's properties?
      - On the legacy path, how is a Folder retitled?
      instructions:
      - text: On the legacy path, retitle Folder {folder_id} as {name}.
        slots:
          folder_id: path.folder_id
          name: requestBody.name
      - text: Using the older endpoint, edit the properties of Folder {folder_id}.
        slots:
          folder_id: path.folder_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/folder/{folder_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a Folder and contents (legacy path)
      effect: destructive
      questions:
      - Does erasing a Folder on the older unversioned path also destroy its Lists and tasks?
      - Can a Folder wiped through the legacy endpoint be recovered?
      instructions:
      - text: Permanently erase Folder {folder_id} with all its Lists and tasks on the legacy path.
        slots:
          folder_id: path.folder_id
      - text: Using the older endpoint, wipe out Folder {folder_id}.
        slots:
          folder_id: path.folder_id
      method: generated
      generated: '2026-09-26'