# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Kibana Security Entity Analytics API
  version: 1.0.0
extends: openapi/elk-stack-security-entity-analytics-api-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: 29
- target: $.paths['/api/asset_criticality'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an entity's asset criticality record
      effect: read
      questions:
      - What asset criticality level is assigned to a particular host or user?
      - Can I look up the criticality record for one entity by its host.name or user.name?
      instructions:
      - text: Get the asset criticality record for {id_field} {id_value}.
        slots:
          id_field: query.id_field
          id_value: query.id_value
      - text: Show how critical host {id_value} is rated, matching on {id_field}.
        slots:
          id_value: query.id_value
          id_field: query.id_field
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/asset_criticality'].post
  update:
    x-apievangelist-phrasing:
      intent: Set asset criticality for a single entity
      effect: write
      questions:
      - How do I mark one host as high impact so its risk score is weighted more?
      - Does setting criticality on an entity that already has a record overwrite the old value?
      instructions:
      - text: Set the asset criticality for this one entity, overwriting any existing record.
      - text: Upsert a single asset criticality record and refresh with {refresh} so it is searchable immediately.
        slots:
          refresh: requestBody.refresh
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/asset_criticality'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove an entity's asset criticality record
      effect: destructive
      questions:
      - How can I clear the criticality level I assigned to a user?
      - What happens to an entity's risk weighting when its asset criticality record is deleted?
      instructions:
      - text: Delete the asset criticality record for {id_field} {id_value}.
        slots:
          id_field: query.id_field
          id_value: query.id_value
      - text: Unassign asset criticality from entity {id_value}, identified by {id_field}.
        slots:
          id_value: query.id_value
          id_field: query.id_field
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/asset_criticality/bulk'].post
  update:
    x-apievangelist-phrasing:
      intent: Bulk set asset criticality for many entities
      effect: write
      questions:
      - Can I assign criticality levels to hundreds of hosts and users in one call?
      - What is the maximum number of asset criticality records I can bulk upsert at once?
      instructions:
      - text: 'Bulk upsert these asset criticality records: {records}.'
        slots:
          records: requestBody.records
      - text: Assign criticality to all the entities in {records} in a single batch.
        slots:
          records: requestBody.records
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/asset_criticality/list'].get
  update:
    x-apievangelist-phrasing:
      intent: List asset criticality records
      effect: read
      questions:
      - Which entities have been given an asset criticality level?
      - Can I filter the criticality records with KQL and sort them by criticality level?
      instructions:
      - text: List asset criticality records matching {kuery}.
        slots:
          kuery: query.kuery
      - text: Page through asset criticality records sorted by {sort_field}, {per_page} per page.
        slots:
          sort_field: query.sort_field
          per_page: query.per_page
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/entity_analytics/monitoring/engine/delete'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete the Privilege Monitoring Engine
      effect: destructive
      questions:
      - How do I tear down the Privilege Monitoring Engine completely?
      - Can I delete the privilege monitoring engine and also wipe the privileged user data it collected?
      instructions:
      - text: Delete the Privilege Monitoring Engine.
      - text: Delete the Privilege Monitoring Engine and remove its user data ({data}).
        slots:
          data: query.data
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/entity_analytics/monitoring/engine/disable'].post
  update:
    x-apievangelist-phrasing:
      intent: Disable the Privilege Monitoring Engine
      effect: write
      questions:
      - Can I pause privileged user monitoring without losing the data it has collected?
      - What stops all Privilege Monitoring activity but keeps the monitored users?
      instructions:
      - text: Disable the Privilege Monitoring Engine but keep its data.
      - text: Stop privileged user monitoring for now.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/entity_analytics/monitoring/engine/init'].post
  update:
    x-apievangelist-phrasing:
      intent: Initialize the Privilege Monitoring Engine
      effect: write
      questions:
      - How do I turn on Privilege Monitoring for the first time?
      - What sets up the resources the privileged user monitoring engine needs?
      instructions:
      - text: Initialize and start the Privilege Monitoring Engine.
      - text: Set up privileged user monitoring in this space.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/entity_analytics/monitoring/engine/schedule_now'].post
  update:
    x-apievangelist-phrasing:
      intent: Run a Privilege Monitoring cycle now
      effect: write
      questions:
      - Can I force the Privilege Monitoring Engine to run immediately instead of waiting for its schedule?
      - Is there a way to trigger an immediate privileged user monitoring cycle?
      instructions:
      - text: Run the Privilege Monitoring Engine as soon as possible.
      - text: Trigger an immediate privileged user monitoring cycle.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/entity_analytics/monitoring/privileges/health'].get
  update:
    x-apievangelist-phrasing:
      intent: Check Privilege Monitoring engine health
      effect: read
      questions:
      - Is the Privilege Monitoring Engine running, and has it hit any errors?
      - How many users is privilege monitoring currently tracking according to its health status?
      instructions:
      - text: Check the health of the Privilege Monitoring Engine.
      - text: Report the privileged user monitoring engine status and error details.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/entity_analytics/monitoring/privileges/privileges'].get
  update:
    x-apievangelist-phrasing:
      intent: Check my permissions for Privilege Monitoring
      effect: read
      questions:
      - Do I have all the permissions required to use Privilege Monitoring?
      - Which privileges am I missing for privileged user monitoring?
      instructions:
      - text: Check whether my user has the permissions Privilege Monitoring needs.
      - text: Run a privileges check for privileged user monitoring.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/entity_analytics/monitoring/users'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a privileged user to monitoring
      effect: write
      questions:
      - How do I add a single admin account to privileged user monitoring?
      - Can I start monitoring one privileged user without uploading a CSV?
      instructions:
      - text: Start monitoring the privileged user {user}.
        slots:
          user: requestBody.user
      - text: Add {user} as a new monitored privileged user.
        slots:
          user: requestBody.user
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/entity_analytics/monitoring/users/_csv'].post
  update:
    x-apievangelist-phrasing:
      intent: Bulk upload monitored users from a CSV
      effect: write
      questions:
      - Can I upload a CSV of privileged accounts to monitor them all at once?
      - Does the monitored-user CSV upload tell me which rows failed?
      instructions:
      - text: Upload {file} to upsert the privileged users it lists.
        slots:
          file: requestBody.file
      - text: Bulk add monitored privileged users from CSV {file}.
        slots:
          file: requestBody.file
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/entity_analytics/monitoring/users/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a monitored privileged user
      effect: write
      questions:
      - How do I change the labels on a user I'm already monitoring for privileged access?
      - Can I edit a monitored user's details by their document ID?
      instructions:
      - text: Update monitored user {id} with labels {labels}.
        slots:
          id: path.id
          labels: requestBody.labels
      - text: Edit the details of the monitored privileged user with document ID {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/entity_analytics/monitoring/users/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Stop monitoring a privileged user
      effect: destructive
      questions:
      - How do I remove someone from privileged user monitoring?
      - Can I delete a monitored user record by its document ID?
      instructions:
      - text: Remove monitored user {id} from privilege monitoring.
        slots:
          id: path.id
      - text: Delete the monitored privileged user record {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/entity_analytics/monitoring/users/list'].get
  update:
    x-apievangelist-phrasing:
      intent: List monitored privileged users
      effect: read
      questions:
      - Which privileged users are currently being monitored?
      - Can I filter the list of monitored users with a KQL query?
      instructions:
      - text: List all monitored privileged users.
      - text: Show the monitored users that match {kql}.
        slots:
          kql: query.kql
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/entity_analytics/privileged_user_monitoring/pad/install'].post
  update:
    x-apievangelist-phrasing:
      intent: Install the privileged access detection package
      effect: write
      questions:
      - How do I install the privileged access detection integration and its ML modules?
      - What sets up the machine learning jobs behind privileged user monitoring?
      instructions:
      - text: Install the privileged access detection package.
      - text: Set up the privileged access detection ML modules for Entity Analytics.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/entity_analytics/privileged_user_monitoring/pad/status'].get
  update:
    x-apievangelist-phrasing:
      intent: Check privileged access detection package status
      effect: read
      questions:
      - Is the privileged access detection package installed, and are its ML jobs running?
      - What state is each privileged access detection ML job in?
      instructions:
      - text: Show the install status of the privileged access detection package.
      - text: Report the state of each privileged access detection ML job.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/entity_analytics/watchlists'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an entity watchlist
      effect: write
      questions:
      - How do I create a watchlist that raises the risk score of entities on it?
      - Can I attach entity sources when I create a new watchlist?
      instructions:
      - text: Create a watchlist called {name} with risk modifier {riskModifier}.
        slots:
          name: requestBody.name
          riskModifier: requestBody.riskModifier
      - text: Make a new watchlist {name} described as {description} with risk modifier {riskModifier}.
        slots:
          name: requestBody.name
          description: requestBody.description
          riskModifier: requestBody.riskModifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/entity_analytics/watchlists/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a watchlist's details
      effect: read
      questions:
      - What risk modifier and description does a particular watchlist have?
      - Can I fetch one entity analytics watchlist by its ID?
      instructions:
      - text: Show me watchlist {id}.
        slots:
          id: path.id
      - text: Get the details of entity watchlist {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/entity_analytics/watchlists/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update an existing watchlist
      effect: write
      questions:
      - Can I change the risk modifier on a watchlist I already created?
      - How do I rename an existing watchlist?
      instructions:
      - text: Rename watchlist {id} to {name} and set its risk modifier to {riskModifier}.
        slots:
          id: path.id
          name: requestBody.name
          riskModifier: requestBody.riskModifier
      - text: Update the description of watchlist {id} to {description}.
        slots:
          id: path.id
          description: requestBody.description
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/entity_analytics/watchlists/{watchlist_id}/csv_upload'].post
  update:
    x-apievangelist-phrasing:
      intent: Add entities to a watchlist from a CSV
      effect: write
      questions:
      - Can I add a list of users and hosts to a watchlist by uploading a CSV?
      - What columns does the watchlist CSV need, like type and user.name?
      instructions:
      - text: Upload {file} to add its entities to watchlist {watchlist_id}.
        slots:
          file: requestBody.file
          watchlist_id: path.watchlist_id
      - text: Populate watchlist {watchlist_id} from CSV {file}.
        slots:
          watchlist_id: path.watchlist_id
          file: requestBody.file
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/entity_analytics/watchlists/{watchlist_id}/entities/assign'].post
  update:
    x-apievangelist-phrasing:
      intent: Manually assign entities to a watchlist
      effect: write
      questions:
      - How do I put specific entities from the entity store onto a watchlist by hand?
      - What happens if I manually assign an entity that is already on the watchlist?
      instructions:
      - text: Manually add entities {euids} to watchlist {watchlist_id}.
        slots:
          euids: requestBody.euids
          watchlist_id: path.watchlist_id
      - text: Assign {euids} to watchlist {watchlist_id} with a manual source label.
        slots:
          euids: requestBody.euids
          watchlist_id: path.watchlist_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/entity_analytics/watchlists/{watchlist_id}/entities/unassign'].post
  update:
    x-apievangelist-phrasing:
      intent: Manually remove entities from a watchlist
      effect: write
      questions:
      - Can I take an entity off a watchlist that I added manually?
      - Will unassigning an entity remove it if it was also added through an index or integration source?
      instructions:
      - text: Remove the manual assignment of {euids} from watchlist {watchlist_id}.
        slots:
          euids: requestBody.euids
          watchlist_id: path.watchlist_id
      - text: Unassign entities {euids} from watchlist {watchlist_id}.
        slots:
          euids: requestBody.euids
          watchlist_id: path.watchlist_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/entity_analytics/watchlists/list'].get
  update:
    x-apievangelist-phrasing:
      intent: List all entity watchlists
      effect: read
      questions:
      - What watchlists have been set up in entity analytics?
      - Which watchlists exist in this space?
      instructions:
      - text: List all my entity analytics watchlists.
      - text: Show every watchlist in this space.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/risk_score/engine/dangerously_delete_data'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete all Risk Engine data and resources
      effect: destructive
      questions:
      - How do I completely remove the risk scoring engine, including its indices and transforms?
      - Is there a way to wipe all risk score data and start over?
      instructions:
      - text: Clean up the Risk Engine by deleting its indices, mappings and transforms.
      - text: Permanently remove all risk scoring engine data.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/risk_score/engine/saved_object/configure'].patch
  update:
    x-apievangelist-phrasing:
      intent: Configure the risk scoring engine
      effect: write
      questions:
      - Can I exclude closed alerts or certain alert tags from risk score calculations?
      - How do I change the time range the risk engine looks back over?
      - Can risk scores be reset to zero for entities with no recent alerts?
      instructions:
      - text: Configure the risk engine to ignore alerts with statuses {exclude_alert_statuses}.
        slots:
          exclude_alert_statuses: requestBody.exclude_alert_statuses
      - text: Set the risk engine lookback range to {range}.
        slots:
          range: requestBody.range
      - text: Exclude alerts tagged {exclude_alert_tags} from risk scoring.
        slots:
          exclude_alert_tags: requestBody.exclude_alert_tags
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/risk_score/engine/schedule_now'].post
  update:
    x-apievangelist-phrasing:
      intent: Run the risk scoring engine now
      effect: write
      questions:
      - Can I recalculate entity risk scores right after changing asset criticality?
      - How do I trigger the risk scoring engine immediately?
      instructions:
      - text: Run the risk scoring engine as soon as possible.
      - text: Recalculate entity risk scores now.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/risk_score/history'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an entity's risk score history
      effect: read
      questions:
      - How has a user's risk score changed over the past month?
      - Can I see which alerts contributed to each historical risk score for a host?
      instructions:
      - text: Show the risk score history for {entity_type} {entity_id}.
        slots:
          entity_type: query.entity_type
          entity_id: query.entity_id
      - text: Get risk scores for {entity_type} {entity_id} from {from} to {to} with contributions.
        slots:
          entity_type: query.entity_type
          entity_id: query.entity_id
          from: query.from
          to: query.to
      method: generated
      generated: '2026-09-26'