# 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 Apps API
  version: 1.0.0
extends: openapi/dotcms-apps-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['/api/v1/apps'].get
  update:
    x-apievangelist-phrasing:
      intent: List available app integrations
      effect: read
      questions:
      - Which third-party app integrations are available in dotCMS?
      - Can I filter the list of apps by name?
      instructions:
      - text: List all available apps.
      - text: Show apps matching {filter}.
        slots:
          filter: query.filter
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/apps'].post
  update:
    x-apievangelist-phrasing:
      intent: Upload a new app descriptor
      effect: write
      questions:
      - How do I add a new app integration by uploading its YAML descriptor?
      - Can I register a custom app definition in dotCMS?
      instructions:
      - text: Upload this app descriptor file to create a new app.
      - text: Register a custom app from the attached YAML descriptor.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/apps'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete specific secrets of an app on a site
      effect: destructive
      questions:
      - How do I remove just one secret from an app's configuration on a site?
      - Can I delete individual app parameters without wiping the whole configuration?
      instructions:
      - text: Delete secrets {params} from app {key} on site {siteId}.
        slots:
          params: requestBody.params
          key: requestBody.key
          siteId: requestBody.siteId
      - text: Remove only the {params} entries of app {key} for site {siteId}.
        slots:
          params: requestBody.params
          key: requestBody.key
          siteId: requestBody.siteId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/apps/{key}/{siteId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an app's configuration on a site
      effect: read
      questions:
      - How is a particular app configured for one of my sites?
      - Which secrets are set for an app on a specific site?
      instructions:
      - text: Show the configuration of app {key} on site {siteId}.
        slots:
          key: path.key
          siteId: path.siteId
      - text: Get app {key}'s secrets for site {siteId}.
        slots:
          key: path.key
          siteId: path.siteId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/apps/{key}/{siteId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update one secret of an app on a site
      effect: write
      questions:
      - How do I change a single secret value for an app on a site?
      - Can I update one app parameter without resending the others?
      instructions:
      - text: Update a single secret of app {key} on site {siteId}.
        slots:
          key: path.key
          siteId: path.siteId
      - text: Change one parameter value for app {key} on {siteId}.
        slots:
          key: path.key
          siteId: path.siteId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/apps/{key}/{siteId}'].post
  update:
    x-apievangelist-phrasing:
      intent: Save an app's full set of secrets on a site
      effect: write
      questions:
      - How do I configure an app for a site by saving all its secrets?
      - Can I set up an app integration on a specific site for the first time?
      instructions:
      - text: Save the full secret configuration for app {key} on site {siteId}.
        slots:
          key: path.key
          siteId: path.siteId
      - text: Configure app {key} on site {siteId} with these secrets.
        slots:
          key: path.key
          siteId: path.siteId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/apps/{key}/{siteId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove all of an app's secrets from a site
      effect: destructive
      questions:
      - How do I wipe an app's entire configuration from one site?
      - Can I unconfigure an app on a single site but keep it elsewhere?
      instructions:
      - text: Delete every secret for app {key} on site {siteId}.
        slots:
          key: path.key
          siteId: path.siteId
      - text: Unconfigure app {key} from site {siteId}.
        slots:
          key: path.key
          siteId: path.siteId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/apps/{key}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an app and the sites it's configured on
      effect: read
      questions:
      - Which sites have a given app configured?
      - How do I look up an app by its key?
      instructions:
      - text: Get app {key} and its site configurations.
        slots:
          key: path.key
      - text: Show which sites use app {key}.
        slots:
          key: path.key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/apps/{key}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an app and its configurations
      effect: destructive
      questions:
      - How do I remove an app integration entirely?
      - Can I delete an app's descriptor file along with its configuration?
      instructions:
      - text: Delete app {key}.
        slots:
          key: path.key
      - text: Remove app {key} and set descriptor removal to {removeDescriptor}.
        slots:
          key: path.key
          removeDescriptor: query.removeDescriptor
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/apps/export'].post
  update:
    x-apievangelist-phrasing:
      intent: Export app secrets to an encrypted file
      effect: read
      questions:
      - How do I export my app secrets so I can move them to another environment?
      - Can I export secrets for only certain apps and sites, protected by a password?
      instructions:
      - text: Export all app secrets encrypted with password {password}.
        slots:
          password: requestBody.password
      - text: Export secrets for {appKeysBySite} with password {password}, export all set to {exportAll}.
        slots:
          appKeysBySite: requestBody.appKeysBySite
          password: requestBody.password
          exportAll: requestBody.exportAll
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/apps/import'].post
  update:
    x-apievangelist-phrasing:
      intent: Import app secrets from an exported file
      effect: write
      questions:
      - How do I load app secrets exported from another dotCMS environment?
      - Can I restore app configurations from a secrets export file?
      instructions:
      - text: Import app secrets from this exported file.
      - text: Restore app configurations from the uploaded secrets export.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/ema'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the Edit Mode Anywhere configuration
      effect: read
      questions:
      - Is Edit Mode Anywhere configured for the current site?
      - What EMA settings are in place for editing a headless front end?
      instructions:
      - text: Show the Edit Mode Anywhere configuration.
      - text: Get the EMA app details for the current site.
      method: generated
      generated: '2026-09-26'