# 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 Maintenance API
  version: 1.0.0
extends: openapi/dotcms-maintenance-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: 26
- target: $.paths['/api/v1/maintenance/_contentlets'].delete
  update:
    x-apievangelist-phrasing:
      intent: Permanently bulk delete contentlets by identifier
      effect: destructive
      questions:
      - How do I permanently destroy a batch of contentlets without sending them to the trash?
      - Does bulk deleting a contentlet also remove its other language versions?
      - If one contentlet in a bulk delete fails, do the rest still get destroyed?
      instructions:
      - text: Permanently destroy the contentlets with identifiers {identifiers}, bypassing the trash.
        slots:
          identifiers: requestBody.identifiers
      - text: Bulk delete contentlets {identifiers} and all of their language siblings for good.
        slots:
          identifiers: requestBody.identifiers
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/maintenance/_pushedAssets'].delete
  update:
    x-apievangelist-phrasing:
      intent: Clear all push publishing history records
      effect: destructive
      questions:
      - How can I wipe the pushed assets table so everything looks never pushed?
      - Can I reset push publishing history across all endpoints at once?
      instructions:
      - text: Delete every pushed assets record so all assets appear never pushed.
      - text: Clear the whole push publishing history table.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/maintenance/_systemJobs/{group}/{name}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a Quartz scheduler job by group and name
      effect: destructive
      questions:
      - How do I remove an orphaned Quartz scheduler job that errored after an upgrade?
      - Does removing a Quartz job also delete its triggers?
      instructions:
      - text: Remove the Quartz job {name} in group {group} along with its triggers.
        slots:
          name: path.name
          group: path.group
      - text: Clean up the errored scheduler job {name} from job group {group}.
        slots:
          name: path.name
          group: path.group
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/maintenance/_downloadAssets'].get
  update:
    x-apievangelist-phrasing:
      intent: Download a zip of the site's asset files
      effect: read
      questions:
      - Can I download just the assets folder from my dotCMS instance as an archive?
      - Is there a way to include old asset versions when downloading the assets?
      instructions:
      - text: Download the assets archive only, without the database.
      - text: Download the assets archive with old versions set to {oldAssets} and a max file size of {maxSize}.
        slots:
          oldAssets: query.oldAssets
          maxSize: query.maxSize
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/maintenance/_downloadClusterLog/{fileName}'].get
  update:
    x-apievangelist-phrasing:
      intent: Download a log file collected from the cluster
      effect: read
      questions:
      - How do I pull a log file gathered from all cluster nodes?
      - Can I fetch a cluster-wide log bundle by file name?
      instructions:
      - text: Download the cluster log file {fileName}.
        slots:
          fileName: path.fileName
      - text: Grab {fileName} from the cluster logs so I can inspect it.
        slots:
          fileName: path.fileName
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/maintenance/_downloadDb'].get
  update:
    x-apievangelist-phrasing:
      intent: Download a database dump
      effect: read
      questions:
      - How do I download a full dump of the dotCMS database?
      - Can I get a database backup file straight from the maintenance API?
      instructions:
      - text: Download a dump of the database.
      - text: Export the database as a backup file for me.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/maintenance/_downloadLog/{fileName}'].get
  update:
    x-apievangelist-phrasing:
      intent: Download a single server log file
      effect: read
      questions:
      - How can I download one of this server's log files by its name?
      - Can I fetch dotcms.log from the local node without shell access?
      instructions:
      - text: Download the log file {fileName} from this server.
        slots:
          fileName: path.fileName
      - text: Fetch the local node's {fileName} log.
        slots:
          fileName: path.fileName
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/maintenance/_downloadStarter'].get
  update:
    x-apievangelist-phrasing:
      intent: Download a starter site without assets
      effect: read
      questions:
      - How do I export a starter package that contains data but no asset files?
      - Can I cap the file size when generating a starter without assets?
      instructions:
      - text: Download a starter package without assets.
      - text: Build a data-only starter limited to files of {maxSize}.
        slots:
          maxSize: query.maxSize
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/maintenance/_downloadStarterWithAssets'].get
  update:
    x-apievangelist-phrasing:
      intent: Download a starter site including assets
      effect: read
      questions:
      - How do I export a complete starter that bundles the data together with the asset files?
      - Can a starter with assets also include old asset versions?
      instructions:
      - text: Download a starter that includes both data and assets.
      - text: Generate a starter with assets, old versions {oldAssets}, max file size {maxSize}.
        slots:
          oldAssets: query.oldAssets
          maxSize: query.maxSize
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/maintenance/_oldVersions'].delete
  update:
    x-apievangelist-phrasing:
      intent: Drop content and asset versions older than a date
      effect: destructive
      questions:
      - How do I purge old versions of contentlets, templates and containers older than a certain date?
      - What gets removed when I drop old asset versions, and how long can it take?
      instructions:
      - text: Drop all versions of versionable objects older than {date}.
        slots:
          date: query.date
      - text: Purge old content, template and workflow history versions from before {date}.
        slots:
          date: query.date
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/maintenance/assets/_clean'].get
  update:
    x-apievangelist-phrasing:
      intent: Check the latest clean-assets job
      effect: read
      questions:
      - Is an orphan asset cleanup currently running, and what was its last result?
      - Has a clean-assets job ever run on this cluster?
      instructions:
      - text: Show me the status of the most recent clean-assets job.
      - text: Check whether the orphan asset cleanup has finished.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/maintenance/assets/_clean'].post
  update:
    x-apievangelist-phrasing:
      intent: Start a job that cleans orphaned assets
      effect: destructive
      questions:
      - How do I kick off a cleanup of orphaned asset files on the cluster?
      - What happens if I request an orphan asset cleanup while one is already running?
      instructions:
      - text: Queue a clean-assets job to remove orphaned asset files.
      - text: Start the orphan asset cleanup and give me the job id.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/maintenance/assets/_fix'].get
  update:
    x-apievangelist-phrasing:
      intent: Check the latest fix-assets job
      effect: read
      questions:
      - What was the outcome of the last asset inconsistency fix run?
      - Is a fix-assets job active right now?
      instructions:
      - text: Show me the most recent fix-assets job and its status.
      - text: Check how the latest asset inconsistency fix went.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/maintenance/assets/_fix'].post
  update:
    x-apievangelist-phrasing:
      intent: Start a job that fixes asset inconsistencies
      effect: write
      questions:
      - How do I trigger a repair of asset inconsistencies across the cluster?
      - Why would requesting a fix-assets job return a 409 conflict?
      instructions:
      - text: Queue a fix-assets job to repair asset inconsistencies.
      - text: Start the asset inconsistency repair and return its status URL.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/maintenance/_threads'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a full JVM thread dump
      effect: read
      questions:
      - How do I get a JVM thread dump with stack traces to diagnose a hung server?
      - Can the thread dump detect deadlocks and filter to only dotCMS threads?
      instructions:
      - text: Take a full JVM thread dump with stack traces and deadlock detection.
      - text: Dump JVM threads with system threads hidden set to {hideSystem}.
        slots:
          hideSystem: query.hideSystem
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/maintenance/_threads/info'].get
  update:
    x-apievangelist-phrasing:
      intent: Get JVM uptime and thread count summary
      effect: read
      questions:
      - How long has the JVM been up and what is its peak thread count?
      - Is there a lightweight way to see current thread count without a full dump?
      instructions:
      - text: Show the JVM start time, uptime and current versus peak thread count.
      - text: Give me a quick thread-count summary for the server.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/maintenance/_pgDumpAvailable'].get
  update:
    x-apievangelist-phrasing:
      intent: Check whether pg_dump is available
      effect: read
      questions:
      - Can this server produce a PostgreSQL dump, i.e. is pg_dump installed?
      - Why might the database download not be available on my instance?
      instructions:
      - text: Check if pg_dump is available on the server.
      - text: Tell me whether database dumps can be generated here.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/maintenance/_sessions'].get
  update:
    x-apievangelist-phrasing:
      intent: List active HTTP sessions
      effect: read
      questions:
      - Who is currently logged in, i.e. which HTTP sessions are active?
      - How do I get the token needed to kill a specific user session?
      instructions:
      - text: List every active HTTP session with its session token.
      - text: Show me who has an open session right now.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/maintenance/_sessions'].delete
  update:
    x-apievangelist-phrasing:
      intent: Log out every session except mine
      effect: destructive
      questions:
      - How do I force everyone else to log out of dotCMS at once?
      - Will invalidating all sessions also end my own session?
      instructions:
      - text: Invalidate all active sessions except my own.
      - text: Kick every other user out and tell me how many sessions were ended.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/maintenance/_sessions/{token}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Invalidate one user session
      effect: destructive
      questions:
      - How do I end one specific user's session without logging out everyone?
      - Why does killing a session return 403 after fifteen minutes?
      instructions:
      - text: Invalidate the session with token {token}.
        slots:
          token: path.token
      - text: Log out the single session identified by {token}.
        slots:
          token: path.token
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/maintenance/_systemJobs'].get
  update:
    x-apievangelist-phrasing:
      intent: List Quartz scheduler jobs
      effect: read
      questions:
      - Which Quartz scheduler jobs exist and when will they fire next?
      - How can I find scheduler jobs that errored after an upgrade?
      instructions:
      - text: List all Quartz scheduler jobs with their triggers and running status.
      - text: Show me any scheduler jobs flagged with an error.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/maintenance/_searchAndReplace'].post
  update:
    x-apievangelist-phrasing:
      intent: Find and replace text across the whole database
      effect: destructive
      questions:
      - How do I replace a string everywhere in content, templates, containers and links?
      - Can a database-wide search and replace be undone?
      instructions:
      - text: Replace every occurrence of {searchString} with {replaceString} across all content.
        slots:
          searchString: requestBody.searchString
          replaceString: requestBody.replaceString
      - text: Swap the old domain {searchString} for {replaceString} in all working and live versions.
        slots:
          searchString: requestBody.searchString
          replaceString: requestBody.replaceString
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/maintenance/_shutdown'].delete
  update:
    x-apievangelist-phrasing:
      intent: Shut down this server node
      effect: destructive
      questions:
      - How do I shut down the dotCMS instance I'm connected to?
      - Can I stop a single node remotely through the maintenance API?
      instructions:
      - text: Shut down this dotCMS server.
      - text: Stop the current node only.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/maintenance/_shutdownCluster'].delete
  update:
    x-apievangelist-phrasing:
      intent: Shut down every node in the cluster
      effect: destructive
      questions:
      - How do I shut down all nodes in the cluster at once?
      - Can I stagger a cluster shutdown with a rolling delay between nodes?
      instructions:
      - text: Shut down the entire cluster.
      - text: Do a rolling cluster shutdown with a {rollingDelay} delay between nodes.
        slots:
          rollingDelay: query.rollingDelay
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/upgradetask'].post
  update:
    x-apievangelist-phrasing:
      intent: Run a specific upgrade task
      effect: write
      questions:
      - How do I manually re-run a single upgrade task by class name?
      - Can I execute a specific database upgrade task that was skipped?
      instructions:
      - text: Run the upgrade task {upgradeTaskClass}.
        slots:
          upgradeTaskClass: requestBody.upgradeTaskClass
      - text: Execute upgrade class {upgradeTaskClass} now.
        slots:
          upgradeTaskClass: requestBody.upgradeTaskClass
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/caches/menucache'].delete
  update:
    x-apievangelist-phrasing:
      intent: Flush the navigation menu cache
      effect: destructive
      questions:
      - My site navigation is stale, how do I clear the menu cache?
      - Can I flush only the menu cache without touching other caches?
      instructions:
      - text: Clear the menu cache.
      - text: Flush the navigation menu cache so menus rebuild.
      method: generated
      generated: '2026-09-26'