API Evangelist conversational phrasing for dotCMS REST Rules Engine 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 Rules Engine API
  version: 1.0.0
extends: openapi/dotcms-rules-engine-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/rulesengine/layout/{params}'].get
  update:
    x-apievangelist-phrasing:
      intent: Load the rules engine portlet layout
      effect: read
      questions:
      - Where does the dotCMS admin UI get the layout for the rules engine screen?
      - Can I fetch the rules engine portlet layout definition over REST?
      instructions:
      - text: Load the rules engine layout using parameters {params}.
        slots:
          params: path.params
      - text: Fetch the layout definition for the rules engine portlet with {params}.
        slots:
          params: path.params
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/sites/{siteId}/ruleengine/rules'].get
  update:
    x-apievangelist-phrasing:
      intent: List the rules defined on a site
      effect: read
      questions:
      - Which personalization rules are configured on one of my sites?
      - How do I see every rule the rules engine runs for a given site?
      instructions:
      - text: List all rules configured on site {siteId}.
        slots:
          siteId: path.siteId
      - text: Show me every rules engine rule for site {siteId} with their fire-on settings.
        slots:
          siteId: path.siteId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/sites/{siteId}/ruleengine/rules'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a new rule on a site
      effect: write
      questions:
      - Can I create a rule that fires on every page request for a site?
      - What do I send to add a new rule with its condition groups and actions?
      instructions:
      - text: Create a rule named {name} on site {siteId} that fires {fireOn}.
        slots:
          name: requestBody.name
          siteId: path.siteId
          fireOn: requestBody.fireOn
      - text: Add a rule called {name} to site {siteId} with priority {priority}.
        slots:
          name: requestBody.name
          siteId: path.siteId
          priority: requestBody.priority
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/sites/{siteId}/ruleengine/rules/{ruleId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a single rule by ID
      effect: read
      questions:
      - How can I look up one specific rule and its settings on a site?
      - Can I check whether a particular rule is enabled?
      instructions:
      - text: Get rule {ruleId} on site {siteId}.
        slots:
          ruleId: path.ruleId
          siteId: path.siteId
      - text: Show the name, priority and fire-on setting of rule {ruleId} for site {siteId}.
        slots:
          ruleId: path.ruleId
          siteId: path.siteId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/sites/{siteId}/ruleengine/rules/{ruleId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update an existing rule
      effect: write
      questions:
      - Can I rename or re-prioritize a rule that already exists?
      - How do I turn off short-circuit evaluation on an existing rule?
      instructions:
      - text: Rename rule {ruleId} on site {siteId} to {name}.
        slots:
          ruleId: path.ruleId
          siteId: path.siteId
          name: requestBody.name
      - text: Set enabled to {enabled} on existing rule {ruleId} for site {siteId}.
        slots:
          enabled: requestBody.enabled
          ruleId: path.ruleId
          siteId: path.siteId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/sites/{siteId}/ruleengine/rules/{ruleId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a rule from a site
      effect: destructive
      questions:
      - How do I permanently remove a rule from the rules engine?
      - Can I delete a whole rule rather than just one of its actions?
      instructions:
      - text: Delete rule {ruleId} from site {siteId}.
        slots:
          ruleId: path.ruleId
          siteId: path.siteId
      - text: Remove the entire rule {ruleId} from site {siteId}, not just one of its actions.
        slots:
          ruleId: path.ruleId
          siteId: path.siteId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/sites/{siteId}/ruleengine/actions'].post
  update:
    x-apievangelist-phrasing:
      intent: Add an action to a rule
      effect: write
      questions:
      - How do I attach an actionlet to a rule so it does something when it fires?
      - Can I set the priority of a new rule action?
      instructions:
      - text: Add actionlet {actionlet} as a new action on rule {owningRule} for site {siteId}.
        slots:
          actionlet: requestBody.actionlet
          owningRule: requestBody.owningRule
          siteId: path.siteId
      - text: Create a rule action on rule {owningRule} in site {siteId} with priority {priority}.
        slots:
          owningRule: requestBody.owningRule
          siteId: path.siteId
          priority: requestBody.priority
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/sites/{siteId}/ruleengine/actions/{actionId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a rule action by ID
      effect: read
      questions:
      - Which actionlet and parameters does a given rule action use?
      - Can I inspect a single rule action on its own?
      instructions:
      - text: Get rule action {actionId} on site {siteId}.
        slots:
          actionId: path.actionId
          siteId: path.siteId
      - text: Show the actionlet and parameters configured for action {actionId} in site {siteId}.
        slots:
          actionId: path.actionId
          siteId: path.siteId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/sites/{siteId}/ruleengine/actions/{actionId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a rule action
      effect: write
      questions:
      - Can I change the parameters of an action a rule already has?
      - How do I swap the actionlet used by an existing rule action?
      instructions:
      - text: Change existing action {actionId} on site {siteId} to use actionlet {actionlet} under rule {owningRule}.
        slots:
          actionId: path.actionId
          siteId: path.siteId
          actionlet: requestBody.actionlet
          owningRule: requestBody.owningRule
      - text: Update the parameters of rule action {actionId} in site {siteId} to {parameters}, keeping rule {owningRule}.
        slots:
          actionId: path.actionId
          siteId: path.siteId
          parameters: requestBody.parameters
          owningRule: requestBody.owningRule
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/sites/{siteId}/ruleengine/actions/{actionId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an action from a rule
      effect: destructive
      questions:
      - How do I remove one action from a rule without deleting the rule?
      - Can I delete a rule action I no longer need?
      instructions:
      - text: Delete rule action {actionId} on site {siteId}.
        slots:
          actionId: path.actionId
          siteId: path.siteId
      - text: Remove action {actionId} from its rule in site {siteId}, leaving the rule itself in place.
        slots:
          actionId: path.actionId
          siteId: path.siteId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/sites/{siteId}/ruleengine/rules/{ruleId}/conditionGroups'].get
  update:
    x-apievangelist-phrasing:
      intent: List a rule's condition groups
      effect: read
      questions:
      - Which condition groups make up a particular rule?
      - Can I see how a rule's conditions are grouped with AND/OR operators?
      instructions:
      - text: List the condition groups on rule {ruleId} for site {siteId}.
        slots:
          ruleId: path.ruleId
          siteId: path.siteId
      - text: Show every condition group and its operator for rule {ruleId} in site {siteId}.
        slots:
          ruleId: path.ruleId
          siteId: path.siteId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/sites/{siteId}/ruleengine/rules/{ruleId}/conditionGroups'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a condition group to a rule
      effect: write
      questions:
      - How do I add a new group of conditions to a rule?
      - Can a new condition group be joined to the others with OR instead of AND?
      instructions:
      - text: Add a condition group with operator {operator} to rule {ruleId} on site {siteId}.
        slots:
          operator: requestBody.operator
          ruleId: path.ruleId
          siteId: path.siteId
      - text: Create a new condition group on rule {ruleId} in site {siteId} using {operator} at priority {priority}.
        slots:
          ruleId: path.ruleId
          siteId: path.siteId
          operator: requestBody.operator
          priority: requestBody.priority
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/sites/{siteId}/ruleengine/rules/{ruleId}/conditionGroups/{conditionGroupId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a condition group from a rule
      effect: destructive
      questions:
      - How do I drop a whole condition group from a rule?
      - Can I delete one group of conditions while keeping the rest of the rule?
      instructions:
      - text: Delete condition group {conditionGroupId} from rule {ruleId} on site {siteId}.
        slots:
          conditionGroupId: path.conditionGroupId
          ruleId: path.ruleId
          siteId: path.siteId
      - text: Remove group {conditionGroupId} and its conditions from rule {ruleId} in site {siteId}.
        slots:
          conditionGroupId: path.conditionGroupId
          ruleId: path.ruleId
          siteId: path.siteId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/sites/{siteId}/ruleengine/rules/{ruleId}/conditionGroups/{groupId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a single condition group
      effect: read
      questions:
      - What conditions and operator does one specific condition group hold?
      - Can I fetch a single condition group of a rule by its ID?
      instructions:
      - text: Get condition group {groupId} of rule {ruleId} on site {siteId}.
        slots:
          groupId: path.groupId
          ruleId: path.ruleId
          siteId: path.siteId
      - text: Show the operator and conditions inside group {groupId} for rule {ruleId} in site {siteId}.
        slots:
          groupId: path.groupId
          ruleId: path.ruleId
          siteId: path.siteId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/sites/{siteId}/ruleengine/rules/{ruleId}/conditionGroups/{groupId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a condition group
      effect: write
      questions:
      - Can I switch an existing condition group from AND to OR?
      - How do I reorder the priority of a condition group that already exists?
      instructions:
      - text: Change the operator of condition group {groupId} on rule {ruleId} in site {siteId} to {operator}.
        slots:
          groupId: path.groupId
          ruleId: path.ruleId
          siteId: path.siteId
          operator: requestBody.operator
      - text: Update existing group {groupId} of rule {ruleId} on site {siteId} to operator {operator} and priority {priority}.
        slots:
          groupId: path.groupId
          ruleId: path.ruleId
          siteId: path.siteId
          operator: requestBody.operator
          priority: requestBody.priority
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/sites/{siteId}/ruleengine/conditions'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a condition to a condition group
      effect: write
      questions:
      - How do I add a visitor condition, like a browser or geolocation check, to a rule?
      - Which conditionlet do I pick when adding a new condition to a group?
      instructions:
      - text: Put a single {conditionlet} check using {operator} into existing group {owningGroup} of site {siteId}.
        slots:
          conditionlet: requestBody.conditionlet
          operator: requestBody.operator
          owningGroup: requestBody.owningGroup
          siteId: path.siteId
      - text: Create a new condition in group {owningGroup} for site {siteId} using conditionlet {conditionlet}, operator {operator} and values {values}.
        slots:
          owningGroup: requestBody.owningGroup
          siteId: path.siteId
          conditionlet: requestBody.conditionlet
          operator: requestBody.operator
          values: requestBody.values
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/sites/{siteId}/ruleengine/conditions/{conditionId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a single rule condition
      effect: read
      questions:
      - Which conditionlet and operator does a particular condition use?
      - Can I look up one condition by its ID?
      instructions:
      - text: Get condition {conditionId} on site {siteId}.
        slots:
          conditionId: path.conditionId
          siteId: path.siteId
      - text: Show the conditionlet, operator and group of condition {conditionId} in site {siteId}.
        slots:
          conditionId: path.conditionId
          siteId: path.siteId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/sites/{siteId}/ruleengine/conditions/{conditionId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a rule condition
      effect: write
      questions:
      - Can I change the comparison operator on a condition I already created?
      - How do I move an existing condition into a different condition group?
      instructions:
      - text: Update condition {conditionId} on site {siteId} to conditionlet {conditionlet} with operator {operator} in group {owningGroup}.
        slots:
          conditionId: path.conditionId
          siteId: path.siteId
          conditionlet: requestBody.conditionlet
          operator: requestBody.operator
          owningGroup: requestBody.owningGroup
      - text: Move existing condition {conditionId} in site {siteId} to group {owningGroup}, keeping conditionlet {conditionlet} and operator {operator}.
        slots:
          conditionId: path.conditionId
          siteId: path.siteId
          owningGroup: requestBody.owningGroup
          conditionlet: requestBody.conditionlet
          operator: requestBody.operator
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/sites/{siteId}/ruleengine/conditions/{conditionId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a rule condition
      effect: destructive
      questions:
      - How do I delete one condition from a condition group?
      - Can I remove a single condition without touching the rest of its group?
      instructions:
      - text: Delete condition {conditionId} on site {siteId}.
        slots:
          conditionId: path.conditionId
          siteId: path.siteId
      - text: Remove condition {conditionId} from its group in site {siteId}.
        slots:
          conditionId: path.conditionId
          siteId: path.siteId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/sites/{siteId}/ruleengine/conditions/{conditionId}/conditionValues'].get
  update:
    x-apievangelist-phrasing:
      intent: List the values of a condition
      effect: read
      questions:
      - What key/value inputs are stored on a particular condition?
      - Can I list all the comparison values a condition checks against?
      instructions:
      - text: List the values of condition {conditionId} on site {siteId}.
        slots:
          conditionId: path.conditionId
          siteId: path.siteId
      - text: Show every key and value stored on condition {conditionId} in site {siteId}.
        slots:
          conditionId: path.conditionId
          siteId: path.siteId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/sites/{siteId}/ruleengine/conditions/{conditionId}/conditionValues'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a value to a condition
      effect: write
      questions:
      - How do I add another comparison value to an existing condition?
      - Can I give a new condition value a key and a priority?
      instructions:
      - text: Add value {value} under key {key} to condition {conditionId} on site {siteId}.
        slots:
          value: requestBody.value
          key: requestBody.key
          conditionId: path.conditionId
          siteId: path.siteId
      - text: Create a condition value with key {key} on condition {conditionId} in site {siteId}.
        slots:
          key: requestBody.key
          conditionId: path.conditionId
          siteId: path.siteId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/sites/{siteId}/ruleengine/conditions/{conditionId}/conditionValues/{valueId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a single condition value
      effect: read
      questions:
      - What is stored in one specific condition value?
      - Can I fetch a condition value by its own ID?
      instructions:
      - text: Get value {valueId} of condition {conditionId} on site {siteId}.
        slots:
          valueId: path.valueId
          conditionId: path.conditionId
          siteId: path.siteId
      - text: Show the key and value of condition value {valueId} under condition {conditionId} in site {siteId}.
        slots:
          valueId: path.valueId
          conditionId: path.conditionId
          siteId: path.siteId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/sites/{siteId}/ruleengine/conditions/{conditionId}/conditionValues/{valueId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a condition value
      effect: write
      questions:
      - Can I change the value a condition compares against without recreating it?
      - How do I edit the key of an existing condition value?
      instructions:
      - text: Set condition value {valueId} on condition {conditionId} in site {siteId} to key {key} and value {value}.
        slots:
          valueId: path.valueId
          conditionId: path.conditionId
          siteId: path.siteId
          key: requestBody.key
          value: requestBody.value
      - text: Change the existing value {valueId} of condition {conditionId} on site {siteId}, keeping key {key}.
        slots:
          valueId: path.valueId
          conditionId: path.conditionId
          siteId: path.siteId
          key: requestBody.key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/sites/{siteId}/ruleengine/conditions/{conditionId}/conditionValues/{valueId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a condition value
      effect: destructive
      questions:
      - How do I remove one comparison value from a condition?
      - Can I delete a single condition value but keep the condition?
      instructions:
      - text: Delete value {valueId} from condition {conditionId} on site {siteId}.
        slots:
          valueId: path.valueId
          conditionId: path.conditionId
          siteId: path.siteId
      - text: Remove condition value {valueId} under condition {conditionId} in site {siteId}.
        slots:
          valueId: path.valueId
          conditionId: path.conditionId
          siteId: path.siteId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/system/ruleengine/actionlets'].get
  update:
    x-apievangelist-phrasing:
      intent: List available rule actionlets
      effect: read
      questions:
      - What kinds of actions can a dotCMS rule perform?
      - Which actionlets are installed and available to the rules engine?
      instructions:
      - text: List every actionlet available to the rules engine.
      - text: Show me the action types I can attach to a rule.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/system/ruleengine/conditionlets'].get
  update:
    x-apievangelist-phrasing:
      intent: List available rule conditionlets
      effect: read
      questions:
      - What visitor conditions can a rule check, such as browser, location or referrer?
      - Which conditionlets does the rules engine support?
      instructions:
      - text: List every conditionlet available to the rules engine.
      - text: Show me the condition types I can use when building a rule.
      method: generated
      generated: '2026-09-26'