# 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 System Configuration API
  version: 1.0.0
extends: openapi/dotcms-system-configuration-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: 23
- target: $.paths['/api/config/deleteEndpoint'].post
  update:
    x-apievangelist-phrasing:
      intent: Delete a push publishing endpoint (legacy)
      effect: destructive
      questions:
      - How do I remove a push publishing endpoint through the older config API?
      - Can I delete a receiving server endpoint I no longer publish to?
      instructions:
      - text: Delete push publishing endpoint {endPoint} using the legacy config API.
        slots:
          endPoint: requestBody.endPoint
      - text: Remove endpoint {endPoint} as admin {user} with password {password}.
        slots:
          endPoint: requestBody.endPoint
          user: requestBody.user
          password: requestBody.password
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/config/deleteEnvironment'].post
  update:
    x-apievangelist-phrasing:
      intent: Delete a publishing environment (legacy)
      effect: destructive
      questions:
      - Can I delete a whole push publishing environment?
      - Which older config endpoint removes a publishing environment by name?
      instructions:
      - text: Delete publishing environment {environment} using the legacy config API.
        slots:
          environment: requestBody.environment
      - text: Remove environment {environment} as admin {user} with password {password}.
        slots:
          environment: requestBody.environment
          user: requestBody.user
          password: requestBody.password
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/config/regenerateKey'].post
  update:
    x-apievangelist-phrasing:
      intent: Regenerate the company key (legacy endpoint)
      effect: destructive
      questions:
      - Is there an older config endpoint for rotating the company security key?
      - Can I regenerate the company key without the v1 configuration API?
      instructions:
      - text: Regenerate the company security key through the legacy config endpoint.
      - text: Rotate the company key using the old /api/config route.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/config/saveCompanyAuthTypeInfo'].post
  update:
    x-apievangelist-phrasing:
      intent: Set the login auth type (legacy)
      effect: write
      questions:
      - Can the older config API switch logins between email address and user ID?
      - Which legacy call changes the company authentication type?
      instructions:
      - text: Set the company login auth type to {authType} with the legacy config API.
        slots:
          authType: requestBody.authType
      - text: As admin {user} with password {password}, change the login method to {authType} via the old config route.
        slots:
          user: requestBody.user
          password: requestBody.password
          authType: requestBody.authType
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/config/saveCompanyBasicInfo'].post
  update:
    x-apievangelist-phrasing:
      intent: Save company basic info (legacy)
      effect: write
      questions:
      - Can I update the company's street address and city through the older config API?
      - Which legacy call saves the portal URL, mail domain and company email?
      instructions:
      - text: Set the company portal URL to {portalURL} and email to {emailAddress} using the legacy config API.
        slots:
          portalURL: requestBody.portalURL
          emailAddress: requestBody.emailAddress
      - text: Update the company address to {street}, {city}, {state} through the old config route.
        slots:
          street: requestBody.street
          city: requestBody.city
          state: requestBody.state
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/config/saveCompanyLocaleInfo'].post
  update:
    x-apievangelist-phrasing:
      intent: Save company language and time zone (legacy)
      effect: write
      questions:
      - Can the legacy config API change the system's default time zone?
      - Which older endpoint sets the company default language?
      instructions:
      - text: Set the company time zone to {timeZoneId} with the legacy config API.
        slots:
          timeZoneId: requestBody.timeZoneId
      - text: Change the company language to {languageId} and time zone to {timeZoneId} through the old config route.
        slots:
          languageId: requestBody.languageId
          timeZoneId: requestBody.timeZoneId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/config/saveCompanyLogo'].post
  update:
    x-apievangelist-phrasing:
      intent: Upload the company logo (legacy)
      effect: write
      questions:
      - How do I upload a new company logo file?
      - Can I replace the portal logo with an image file through the older config API?
      instructions:
      - text: Upload {logoFile} as the company logo.
        slots:
          logoFile: requestBody.logoFile
      - text: As admin {user} with password {password}, replace the company logo with {logoFile}.
        slots:
          user: requestBody.user
          password: requestBody.password
          logoFile: requestBody.logoFile
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/configuration/branding'].get
  update:
    x-apievangelist-phrasing:
      intent: Get company branding and settings
      effect: read
      questions:
      - What branding colors and logos is my dotCMS instance currently using?
      - Can I read the full company configuration, including authentication settings, in one call?
      instructions:
      - text: Get the company configuration with branding and authentication settings.
      - text: Show me the current portal URL, logos and brand colors.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/configuration/branding'].put
  update:
    x-apievangelist-phrasing:
      intent: Update company branding and basic info
      effect: write
      questions:
      - How do I change the primary and secondary brand colors of the admin UI?
      - Does setting a navigation bar logo need an Enterprise license?
      instructions:
      - text: Set the brand colors to primary {primaryColor} and secondary {secondaryColor}, portal URL {portalURL}, email {emailAddress}.
        slots:
          primaryColor: requestBody.primaryColor
          secondaryColor: requestBody.secondaryColor
          portalURL: requestBody.portalURL
          emailAddress: requestBody.emailAddress
      - text: Use {loginScreenLogo} as the login screen logo, keeping portal {portalURL}, email {emailAddress} and colors {primaryColor}/{secondaryColor}.
        slots:
          loginScreenLogo: requestBody.loginScreenLogo
          portalURL: requestBody.portalURL
          emailAddress: requestBody.emailAddress
          primaryColor: requestBody.primaryColor
          secondaryColor: requestBody.secondaryColor
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/configuration/_regenerateKey'].post
  update:
    x-apievangelist-phrasing:
      intent: Regenerate the company security key
      effect: destructive
      questions:
      - Can I rotate the company security key and get the SHA-256 digest of the new one?
      - Is regenerating the company key reversible?
      instructions:
      - text: Regenerate the company security key and return its SHA-256 digest.
      - text: Rotate the company key via the v1 configuration API.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/configuration/authentication'].put
  update:
    x-apievangelist-phrasing:
      intent: Set how users log in
      effect: write
      questions:
      - Can users sign in with their email address instead of a user ID?
      - Which login methods can the company authentication type be set to?
      instructions:
      - text: Set the company authentication type to {authType}.
        slots:
          authType: requestBody.authType
      - text: Switch user login to use {authType} as the identifier.
        slots:
          authType: requestBody.authType
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/configuration/locale'].put
  update:
    x-apievangelist-phrasing:
      intent: Set the default language and time zone
      effect: write
      questions:
      - How do I change the system's default time zone?
      - Can I set the default language for the whole company?
      instructions:
      - text: Set the default language to {languageId} and time zone to {timeZoneId}.
        slots:
          languageId: requestBody.languageId
          timeZoneId: requestBody.timeZoneId
      - text: Change the system locale to time zone {timeZoneId} with language {languageId}.
        slots:
          timeZoneId: requestBody.timeZoneId
          languageId: requestBody.languageId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/appconfiguration'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the app configuration for the UI
      effect: read
      questions:
      - What app-level configuration does the admin UI load at startup?
      - Can I fetch the application configuration bundle in one request?
      instructions:
      - text: Get the application configuration.
      - text: Load the app configuration the admin UI uses.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/configuration/config'].get
  update:
    x-apievangelist-phrasing:
      intent: Read whitelisted configuration values
      effect: read
      questions:
      - Can I read specific configuration keys, like feature flags, by name?
      - Why are some config keys missing from the response when I request them?
      instructions:
      - text: Get the whitelisted configuration values for keys {keys}.
        slots:
          keys: query.keys
      - text: Check which of the feature flags {keys} are turned on.
        slots:
          keys: query.keys
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/configuration'].get
  update:
    x-apievangelist-phrasing:
      intent: List system configuration settings
      effect: read
      questions:
      - Which system configuration settings are currently in effect?
      - Can I dump the whole configuration map the configuration resource exposes?
      instructions:
      - text: List the system configuration settings.
      - text: Show me every configuration entry from the configuration resource.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/configuration'].put
  update:
    x-apievangelist-phrasing:
      intent: Save system configuration settings
      effect: write
      questions:
      - Can I write back a set of configuration settings in one request?
      - Which call saves changes to the general configuration map?
      instructions:
      - text: Save my changes to the system configuration settings.
      - text: Write the updated configuration map back to the server.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/configuration/_validateCompanyEmail'].post
  update:
    x-apievangelist-phrasing:
      intent: Validate the company sender email
      effect: write
      questions:
      - How can I check that the company sender address works before saving it?
      - Can I validate a 'Name <email>' sender string for outgoing mail?
      instructions:
      - text: Validate {senderAndEmail} as the company sender email.
        slots:
          senderAndEmail: requestBody.senderAndEmail
      - text: Test whether sender {senderAndEmail} can be used for system mail.
        slots:
          senderAndEmail: requestBody.senderAndEmail
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/system-table/{key}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a system table entry
      effect: read
      questions:
      - What value is stored under a given key in the system table?
      - Can I read one system table setting by its key?
      instructions:
      - text: Get the system table value for key {key}.
        slots:
          key: path.key
      - text: Look up system table entry {key}.
        slots:
          key: path.key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/system-table/{key}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a system table entry by path key
      effect: destructive
      questions:
      - How do I remove a key from the system table when the key is URL-safe?
      - Can I delete one system table entry by putting its key in the URL?
      instructions:
      - text: Delete system table key {key}.
        slots:
          key: path.key
      - text: Remove entry {key} from the system table using the key in the path.
        slots:
          key: path.key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/system-table/_delete'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a system table entry via _delete
      effect: destructive
      questions:
      - Is there a system table delete route that doesn't take the key in the URL path?
      - Which endpoint deletes a system table entry with the key sent in the request body?
      instructions:
      - text: Delete a system table entry through the _delete endpoint, sending the key in the body.
      - text: Remove a system table key using the _delete route rather than a key in the path.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/system-table'].get
  update:
    x-apievangelist-phrasing:
      intent: List all system table entries
      effect: read
      questions:
      - What keys and values are stored in the system table?
      - Can I see every system table entry at once?
      instructions:
      - text: List every entry in the system table.
      - text: Dump all system table keys with their values.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/system-table'].put
  update:
    x-apievangelist-phrasing:
      intent: Update an existing system table entry
      effect: write
      questions:
      - Does updating a system table key fail if the key doesn't exist yet?
      - Is a system table update applied across every node in the cluster?
      instructions:
      - text: Update existing system table key {key} to {value}.
        slots:
          key: requestBody.key
          value: requestBody.value
      - text: Change the value of system table entry {key} to {value} cluster wide, failing if it is missing.
        slots:
          key: requestBody.key
          value: requestBody.value
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/system-table'].post
  update:
    x-apievangelist-phrasing:
      intent: Save or create a system table entry
      effect: write
      questions:
      - How do I add a new key to the system table?
      - Can I upsert a system table value so it's created if missing?
      instructions:
      - text: Save system table key {key} with value {value}, creating it if needed.
        slots:
          key: requestBody.key
          value: requestBody.value
      - text: Upsert {value} under system table key {key}.
        slots:
          value: requestBody.value
          key: requestBody.key
      method: generated
      generated: '2026-09-26'