# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for dotCMS REST Folders API
  version: 1.0.0
extends: openapi/dotcms-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: 8
- target: $.paths['/api/v1/folder/createfolders/{siteName}'].post
  update:
    x-apievangelist-phrasing:
      intent: Create folders by path on a site
      effect: write
      questions:
      - How do I create a nested folder structure on a site in one call?
      - Will missing parent folders be created automatically?
      instructions:
      - text: Create the folder paths I list on site {siteName}.
        slots:
          siteName: path.siteName
      - text: Make folders /blog/2026 and /docs on site {siteName}, including parents.
        slots:
          siteName: path.siteName
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/folder/{siteName}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete folder paths on a site
      effect: destructive
      questions:
      - How do I delete several folders from a site by their paths?
      - What happens if a folder path I delete doesn't exist?
      instructions:
      - text: Delete the folder paths I list from site {siteName}.
        slots:
          siteName: path.siteName
      - text: Remove folders by path on site {siteName} if they exist.
        slots:
          siteName: path.siteName
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/folder/{folderId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a folder by ID
      effect: read
      questions:
      - How do I look up a folder when I only have its identifier?
      - Does a folder with this ID still exist?
      instructions:
      - text: Get folder {folderId}.
        slots:
          folderId: path.folderId
      - text: Look up folder by identifier {folderId}.
        slots:
          folderId: path.folderId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/folder/byPath'].post
  update:
    x-apievangelist-phrasing:
      intent: Find subfolders by path (deprecated)
      effect: read
      questions:
      - Is there an older endpoint that returns subfolders for a path I post?
      - What replaced the deprecated byPath subfolder lookup?
      instructions:
      - text: Use the deprecated byPath lookup to find subfolders of {path}.
        slots:
          path: requestBody.path
      - text: List up to {limit} subfolders under {path} with the legacy endpoint.
        slots:
          limit: query.limit
          path: requestBody.path
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/folder/siteId/{siteId}/path/{path}'].get
  update:
    x-apievangelist-phrasing:
      intent: Load a folder and all its subfolders
      effect: read
      questions:
      - How do I get a folder along with every subfolder beneath it?
      - Can I load a folder tree by path within a site ID?
      instructions:
      - text: Load folder {path} and its subfolders on site {siteId}.
        slots:
          path: path.path
          siteId: path.siteId
      - text: Get the folder tree under {path} for site {siteId}.
        slots:
          path: path.path
          siteId: path.siteId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/folder/sitename/{siteName}/uri/{uri}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a folder by site name and URI
      effect: read
      questions:
      - How do I find a folder from its URL path on a named site?
      - Can I resolve a folder URI like /images/banners on my site?
      instructions:
      - text: Get the folder at URI {uri} on site {siteName}.
        slots:
          uri: path.uri
          siteName: path.siteName
      - text: Resolve folder path {uri} on {siteName}.
        slots:
          uri: path.uri
          siteName: path.siteName
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/folder/search'].get
  update:
    x-apievangelist-phrasing:
      intent: Search folders on a site
      effect: read
      questions:
      - Which folders on my site have a name like this?
      - Can I search folders only under one path, non-recursively?
      - How do I include permissions in folder search results?
      instructions:
      - text: Search folders named {name} on site {siteId}.
        slots:
          name: query.name
          siteId: query.siteId
      - text: Find folders under {path} on site {siteId}.
        slots:
          path: query.path
          siteId: query.siteId
      - text: List every folder on the current site.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/folder/{id}/file-browser-selected'].put
  update:
    x-apievangelist-phrasing:
      intent: Select a folder in the file browser
      effect: write
      questions:
      - Can I set which folder is selected in my file browser session?
      - How do I make the file browser open on a specific folder?
      instructions:
      - text: Select folder {id} in the file browser.
        slots:
          id: path.id
      - text: Mark folder {id} as my current file browser folder.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'