# 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 Detections API
  version: 1.0.0
extends: openapi/elk-stack-security-detections-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/detection_engine/attacks/assignees'].post
  update:
    x-apievangelist-phrasing:
      intent: Assign users to attack discovery alerts
      effect: write
      questions:
      - How do I assign an analyst to an attack discovery?
      - Can assigning an attack discovery also assign its related detection alerts?
      instructions:
      - text: Assign {assignees} to attack discovery alerts {ids}.
        slots:
          assignees: requestBody.assignees
          ids: requestBody.ids
      - text: Update assignees on attacks {ids} to {assignees} and cascade to their related alerts {update_related_alerts}.
        slots:
          ids: requestBody.ids
          assignees: requestBody.assignees
          update_related_alerts: requestBody.update_related_alerts
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/detection_engine/attacks/search'].post
  update:
    x-apievangelist-phrasing:
      intent: Search and aggregate attack discoveries
      effect: read
      questions:
      - Which attack discoveries in this space match my query?
      - Can I aggregate attack discovery alerts, for example counting them by status?
      instructions:
      - text: Search attack discovery alerts matching {query}.
        slots:
          query: requestBody.query
      - text: Aggregate attack discoveries using {aggs} and return {size} hits.
        slots:
          aggs: requestBody.aggs
          size: requestBody.size
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/detection_engine/attacks/status'].post
  update:
    x-apievangelist-phrasing:
      intent: Change the workflow status of attack discoveries
      effect: write
      questions:
      - How do I mark an attack discovery as acknowledged or closed?
      - Can closing an attack discovery also close the detection alerts behind it?
      instructions:
      - text: Close the attack discovery alerts I've finished investigating.
      - text: Mark these attack discoveries as acknowledged and cascade the status to their related alerts.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/detection_engine/attacks/tags'].post
  update:
    x-apievangelist-phrasing:
      intent: Tag or untag attack discoveries
      effect: write
      questions:
      - Can I add and remove tags on attack discoveries in a single request?
      - Will tagging an attack discovery also tag its related detection alerts?
      instructions:
      - text: Apply tag changes {tags} to attack discoveries {ids}.
        slots:
          tags: requestBody.tags
          ids: requestBody.ids
      - text: Tag attacks {ids} with {tags} and propagate to related alerts {update_related_alerts}.
        slots:
          ids: requestBody.ids
          tags: requestBody.tags
          update_related_alerts: requestBody.update_related_alerts
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/detection_engine/index'].get
  update:
    x-apievangelist-phrasing:
      intent: Check the security alerts index
      effect: read
      questions:
      - Which Elasticsearch index backs Elastic Security detection alerts in my space?
      - Is my alerts index mapping outdated?
      instructions:
      - text: Show the name of the detection alerts index in this space.
      - text: Check whether the security alerts index exists and if its mapping is out of date.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/detection_engine/index'].post
  update:
    x-apievangelist-phrasing:
      intent: Create the security alerts index
      effect: write
      questions:
      - Do I need to create an alerts index before detection rules can generate alerts?
      - How do I provision the Elastic Security alerts index for a space?
      instructions:
      - text: Create the Elastic Security alerts index for this space.
      - text: Provision the detection alerts backing index now.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/detection_engine/index'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete the security alerts index
      effect: destructive
      questions:
      - What happens to stored alerts if I delete the alerts backing index?
      - Can I wipe the detection alerts index for one space?
      instructions:
      - text: Delete the security alerts backing index and all alerts in it.
      - text: Permanently remove this space's detection alerts index.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/detection_engine/privileges'].get
  update:
    x-apievangelist-phrasing:
      intent: Check my security detection privileges
      effect: read
      questions:
      - Do I have the index privileges needed to create the security alerts index?
      - What Kibana space and index privileges does my user have for detections?
      instructions:
      - text: Show my authentication status and detection engine privileges.
      - text: Check whether I can create the alerts index in this space.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/detection_engine/rules'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a detection rule
      effect: read
      questions:
      - How do I look up one detection rule by its rule_id?
      - What's the difference between a rule's id and rule_id when fetching it?
      instructions:
      - text: Get detection rule with rule_id {rule_id}.
        slots:
          rule_id: query.rule_id
      - text: Fetch the detection rule whose id is {id}.
        slots:
          id: query.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/detection_engine/rules'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a detection rule
      effect: write
      questions:
      - Does a full rule update delete the fields I leave out?
      - Can I overwrite an entire detection rule definition in one call?
      instructions:
      - text: Replace the whole definition of an existing detection rule with my new version.
      - text: Overwrite this detection rule completely, dropping any fields I don't specify.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/detection_engine/rules'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a detection rule
      effect: write
      questions:
      - How do I create a new custom detection rule in Elastic Security?
      - Does creating a rule with an API key tie that key to the rule?
      instructions:
      - text: Create a new query detection rule for suspicious PowerShell activity.
      - text: Add a new detection rule from this definition.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/detection_engine/rules'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a detection rule
      effect: destructive
      questions:
      - Can I remove a detection rule using its rule_id instead of its id?
      - What happens when I delete a detection rule?
      instructions:
      - text: Delete the detection rule with rule_id {rule_id}.
        slots:
          rule_id: query.rule_id
      - text: Remove detection rule {id}.
        slots:
          id: query.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/detection_engine/rules'].patch
  update:
    x-apievangelist-phrasing:
      intent: Change specific fields of a detection rule
      effect: write
      questions:
      - Can I change just a rule's severity without resending the whole rule?
      - What's the way to partially update a detection rule?
      instructions:
      - text: Patch only the severity and risk score of an existing detection rule.
      - text: Disable one detection rule by changing just its enabled field.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/detection_engine/rules/_bulk_action'].post
  update:
    x-apievangelist-phrasing:
      intent: Bulk edit, duplicate or delete detection rules
      effect: destructive
      questions:
      - Can I enable, duplicate or delete many detection rules at once?
      - Is there a dry run to see which rules a bulk action would affect?
      instructions:
      - text: Apply a bulk edit to all detection rules matching my query.
      - text: Dry-run a bulk delete of these rules first ({dry_run}).
        slots:
          dry_run: query.dry_run
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/detection_engine/rules/_export'].post
  update:
    x-apievangelist-phrasing:
      intent: Export detection rules to NDJSON
      effect: read
      questions:
      - How do I back up detection rules to an .ndjson file?
      - Are exception lists and actions included when I export rules?
      instructions:
      - text: Export detection rules {objects} to an ndjson file.
        slots:
          objects: requestBody.objects
      - text: Export rules {objects} as file {file_name} without export details.
        slots:
          objects: requestBody.objects
          file_name: query.file_name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/detection_engine/rules/_find'].get
  update:
    x-apievangelist-phrasing:
      intent: List and filter detection rules
      effect: read
      questions:
      - Which detection rules do I have, 20 per page by default?
      - Can I filter detection rules by a KQL query and sort them?
      - Which rules have execution gaps in a given time range?
      instructions:
      - text: List all my detection rules.
      - text: Find detection rules matching {filter}, sorted by {sort_field}.
        slots:
          filter: query.filter
          sort_field: query.sort_field
      - text: Show page {page} of detection rules with {per_page} per page.
        slots:
          page: query.page
          per_page: query.per_page
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/detection_engine/rules/_import'].post
  update:
    x-apievangelist-phrasing:
      intent: Import detection rules from NDJSON
      effect: write
      questions:
      - Can I import detection rules from an .ndjson export file?
      - Will importing overwrite rules that already exist with the same rule_id?
      instructions:
      - text: Import detection rules from file {file}.
        slots:
          file: requestBody.file
      - text: Import rules from {file} and overwrite existing ones ({overwrite}).
        slots:
          file: requestBody.file
          overwrite: query.overwrite
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/detection_engine/rules/prepackaged'].put
  update:
    x-apievangelist-phrasing:
      intent: Install Elastic prebuilt rules and Timelines
      effect: write
      questions:
      - How do I install all of Elastic's prebuilt detection rules?
      - Does this also update prebuilt Timeline templates?
      instructions:
      - text: Install and update all Elastic prebuilt detection rules and Timelines.
      - text: Bring my prebuilt rules and Timeline templates up to date.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/detection_engine/rules/prepackaged/_status'].get
  update:
    x-apievangelist-phrasing:
      intent: Check prebuilt rule and Timeline status
      effect: read
      questions:
      - How many prebuilt detection rules are installed versus available to update?
      - Are there any Elastic prebuilt Timelines I haven't installed yet?
      instructions:
      - text: Show the install status of Elastic prebuilt rules and Timelines.
      - text: Count my custom rules, installed prebuilt rules, and outdated prebuilt rules.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/detection_engine/rules/preview'].post
  update:
    x-apievangelist-phrasing:
      intent: Preview a detection rule's alerts
      effect: read
      questions:
      - Can I test a detection rule query to see what alerts it would produce without saving it?
      - Is there a way to validate a rule over a short time window before creating it?
      instructions:
      - text: Preview the alerts this draft rule would generate over the last hour.
      - text: Simulate this rule and include the logged Elasticsearch requests ({enable_logged_requests}).
        slots:
          enable_logged_requests: query.enable_logged_requests
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/detection_engine/signals/assignees'].post
  update:
    x-apievangelist-phrasing:
      intent: Assign users to detection alerts
      effect: write
      questions:
      - How do I assign a detection alert to someone on my team?
      - Can I add and remove the same assignee in one request?
      instructions:
      - text: Assign {assignees} to detection alerts {ids}.
        slots:
          assignees: requestBody.assignees
          ids: requestBody.ids
      - text: Change the assigned users on alerts {ids} to {assignees}.
        slots:
          ids: requestBody.ids
          assignees: requestBody.assignees
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/detection_engine/signals/finalize_migration'].post
  update:
    x-apievangelist-phrasing:
      intent: Finalize a legacy alert index migration
      effect: destructive
      questions:
      - How do I complete a legacy .siem-signals migration once it has finished?
      - What does finalizing an alert migration do to the read aliases?
      instructions:
      - text: Finalize alert migrations {migration_ids}.
        slots:
          migration_ids: requestBody.migration_ids
      - text: Swap read aliases to complete migrations {migration_ids}.
        slots:
          migration_ids: requestBody.migration_ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/detection_engine/signals/migration'].post
  update:
    x-apievangelist-phrasing:
      intent: Start a legacy alert index migration
      effect: write
      questions:
      - Can I reindex an old .siem-signals alert index to the new mapping?
      - How do I throttle a legacy alert reindex with requests per second?
      instructions:
      - text: Start a migration of alert index {index}.
        slots:
          index: requestBody.index
      - text: Migrate legacy alert indices {index} at {requests_per_second} requests per second.
        slots:
          index: requestBody.index
          requests_per_second: requestBody.requests_per_second
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/detection_engine/signals/migration'].delete
  update:
    x-apievangelist-phrasing:
      intent: Clean up legacy alert migrations
      effect: destructive
      questions:
      - How do I clean up old artifacts left from a signals index migration?
      - Does migration cleanup schedule the source index for deletion?
      instructions:
      - text: Clean up alert migrations {migration_ids}.
        slots:
          migration_ids: requestBody.migration_ids
      - text: Schedule deletion of the source indices for migrations {migration_ids}.
        slots:
          migration_ids: requestBody.migration_ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/detection_engine/signals/migration_status'].get
  update:
    x-apievangelist-phrasing:
      intent: Check legacy alert migration status
      effect: read
      questions:
      - Which old .siem-signals indices still need migrating?
      - What's the status of alert index migrations since a given date?
      instructions:
      - text: Show alert migration status for indices with alerts since {from}.
        slots:
          from: query.from
      - text: Check which legacy signal indices are outdated starting from {from}.
        slots:
          from: query.from
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/detection_engine/signals/search'].post
  update:
    x-apievangelist-phrasing:
      intent: Search and aggregate detection alerts
      effect: read
      questions:
      - Which detection alerts match a query I write in Elasticsearch DSL?
      - Can I aggregate detection alerts by rule name or severity?
      instructions:
      - text: Search detection alerts matching {query}.
        slots:
          query: requestBody.query
      - text: Aggregate detection alerts using {aggs}.
        slots:
          aggs: requestBody.aggs
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/detection_engine/signals/status'].post
  update:
    x-apievangelist-phrasing:
      intent: Open, acknowledge or close detection alerts
      effect: write
      questions:
      - How do I close a batch of detection alerts?
      - Can I set detection alerts back to open after acknowledging them?
      instructions:
      - text: Close the detection alerts I've triaged.
      - text: Mark these detection alerts as acknowledged.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/detection_engine/signals/tags'].post
  update:
    x-apievangelist-phrasing:
      intent: Tag or untag detection alerts
      effect: write
      questions:
      - Can I add and remove tags on detection alerts in one call?
      - Is it possible to tag detection alerts that match a query instead of by id?
      instructions:
      - text: Update tags on detection alerts {ids} with {tags}.
        slots:
          ids: requestBody.ids
          tags: requestBody.tags
      - text: Add and remove the tag changes {tags} on alerts {ids}.
        slots:
          tags: requestBody.tags
          ids: requestBody.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/detection_engine/tags'].get
  update:
    x-apievangelist-phrasing:
      intent: List detection rule tags
      effect: read
      questions:
      - What tags are in use across all my detection rules?
      - Can I get the unique list of rule tags?
      instructions:
      - text: List all unique detection rule tags.
      - text: Show every tag used by my detection rules.
      method: generated
      generated: '2026-09-26'