API Evangelist conversational phrasing for dotCMS REST Web Assets API

# 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 Web Assets API
  version: 1.0.0
extends: openapi/dotcms-web-assets-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/assets/_archive'].post
  update:
    x-apievangelist-phrasing:
      intent: Archive a file asset
      effect: write
      questions:
      - How do I make a file inactive without deleting it?
      - Can I archive an asset by its path and keep it in the system?
      instructions:
      - text: Archive the asset at {assetPath}.
        slots:
          assetPath: requestBody.assetPath
      - text: Make file {assetPath} inactive but keep it stored.
        slots:
          assetPath: requestBody.assetPath
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/assets/folders'].put
  update:
    x-apievangelist-phrasing:
      intent: Update or rename a folder
      effect: write
      questions:
      - How do I rename an existing folder by its path?
      - Can I change a folder's configuration details after it's created?
      instructions:
      - text: Update the folder at {assetPath} with settings {data}.
        slots:
          assetPath: requestBody.assetPath
          data: requestBody.data
      - text: Rename existing folder {assetPath} using details {data}.
        slots:
          assetPath: requestBody.assetPath
          data: requestBody.data
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/assets/folders'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a folder at a path
      effect: write
      questions:
      - How do I create a new folder at a specific site path?
      - What configuration can I set when making a new folder?
      instructions:
      - text: Create a new folder at {assetPath} with details {data}.
        slots:
          assetPath: requestBody.assetPath
          data: requestBody.data
      - text: Make folder {assetPath} using configuration {data}.
        slots:
          assetPath: requestBody.assetPath
          data: requestBody.data
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/assets/_delete'].post
  update:
    x-apievangelist-phrasing:
      intent: Permanently delete a file asset
      effect: destructive
      questions:
      - How do I permanently delete a file by its path?
      - Is deleting an asset reversible, or should I archive it instead?
      instructions:
      - text: Permanently delete the file at {assetPath}.
        slots:
          assetPath: requestBody.assetPath
      - text: Remove asset {assetPath} from the system for good.
        slots:
          assetPath: requestBody.assetPath
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/assets/folders/_delete'].post
  update:
    x-apievangelist-phrasing:
      intent: Permanently delete a folder and its contents
      effect: destructive
      questions:
      - How do I delete a folder along with everything inside it?
      - Does deleting a folder also remove the files it contains?
      instructions:
      - text: Permanently delete folder {assetPath} and all its contents.
        slots:
          assetPath: requestBody.assetPath
      - text: Remove the folder at {assetPath} with everything in it.
        slots:
          assetPath: requestBody.assetPath
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/assets/_download'].post
  update:
    x-apievangelist-phrasing:
      intent: Download a file asset
      effect: read
      questions:
      - How do I download a file's binary content by its path?
      - Can I download the working version or a specific language of an asset?
      instructions:
      - text: Download the file at {assetPath}.
        slots:
          assetPath: requestBody.assetPath
      - text: 'Download {assetPath} in language {language}, live version: {live}.'
        slots:
          assetPath: requestBody.assetPath
          language: requestBody.language
          live: requestBody.live
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/assets'].put
  update:
    x-apievangelist-phrasing:
      intent: Upload or replace a file asset
      effect: write
      questions:
      - How do I upload a new file to a specific path?
      - Can I replace an existing asset's file content by path?
      instructions:
      - text: Upload {file} to {assetPath}.
        slots:
          file: requestBody.file
          assetPath: requestBody.assetPath
      - text: Replace the file at {assetPath} with {file} and details {detail}.
        slots:
          assetPath: requestBody.assetPath
          file: requestBody.file
          detail: requestBody.detail
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/assets'].post
  update:
    x-apievangelist-phrasing:
      intent: Get a file or folder's metadata by path
      effect: read
      questions:
      - What metadata does a file or folder at a path have?
      - Can I inspect an asset's details without downloading it?
      instructions:
      - text: Get information about the asset at {assetPath}.
        slots:
          assetPath: requestBody.assetPath
      - text: Show metadata for the file or folder {assetPath}.
        slots:
          assetPath: requestBody.assetPath
      method: generated
      generated: '2026-09-26'