# 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 Exceptions API
  version: 1.0.0
extends: openapi/elk-stack-security-exceptions-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: 16
- target: $.paths['/api/detection_engine/rules/{id}/exceptions'].post
  update:
    x-apievangelist-phrasing:
      intent: Add exception items to a detection rule
      effect: write
      questions:
      - How do I add an exception directly to one detection rule so it stops alerting on known-good activity?
      - Can I attach several exception items to a rule in one request?
      instructions:
      - text: Add exception items {items} to detection rule {id}.
        slots:
          id: path.id
          items: requestBody.items
      - text: Create rule exceptions {items} on rule {id} to suppress false positives.
        slots:
          id: path.id
          items: requestBody.items
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/exception_lists'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an exception list's details
      effect: read
      questions:
      - What are the details of a specific exception list?
      - Can I look up an exception list by its human-readable list_id?
      instructions:
      - text: Get exception list {list_id}.
        slots:
          list_id: query.list_id
      - text: Show the details of exception list with id {id} in namespace {namespace_type}.
        slots:
          id: query.id
          namespace_type: query.namespace_type
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/exception_lists'].put
  update:
    x-apievangelist-phrasing:
      intent: Update an exception list
      effect: write
      questions:
      - How do I rename an existing exception list or change its description?
      - Can I change the OS types or tags on an exception list I already made?
      instructions:
      - text: Update exception list {list_id} with name {name}, description {description} and type {type}.
        slots:
          list_id: requestBody.list_id
          name: requestBody.name
          description: requestBody.description
          type: requestBody.type
      - text: Retag existing exception list {list_id} with {tags}, keeping name {name}, description {description}, type {type}.
        slots:
          list_id: requestBody.list_id
          tags: requestBody.tags
          name: requestBody.name
          description: requestBody.description
          type: requestBody.type
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/exception_lists'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an exception list
      effect: write
      questions:
      - How do I create a new exception list for my detection rules?
      - Can I make an exception list that applies only to Windows endpoints?
      instructions:
      - text: Create an exception list named {name} of type {type} described as {description}.
        slots:
          name: requestBody.name
          type: requestBody.type
          description: requestBody.description
      - text: Create exception list {list_id} called {name}, type {type}, description {description}, for OS types {os_types}.
        slots:
          list_id: requestBody.list_id
          name: requestBody.name
          type: requestBody.type
          description: requestBody.description
          os_types: requestBody.os_types
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/exception_lists'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an exception list
      effect: destructive
      questions:
      - How do I permanently delete an exception list?
      - Does deleting an exception list remove it from the rules that use it?
      instructions:
      - text: Delete exception list {list_id}.
        slots:
          list_id: query.list_id
      - text: Delete the exception list with id {id} in namespace {namespace_type}.
        slots:
          id: query.id
          namespace_type: query.namespace_type
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/exception_lists/_duplicate'].post
  update:
    x-apievangelist-phrasing:
      intent: Duplicate an exception list
      effect: write
      questions:
      - Can I make a copy of an existing exception list?
      - Is it possible to leave out expired exceptions when copying a list?
      instructions:
      - text: 'Duplicate exception list {list_id} in namespace {namespace_type}, including expired items: {include_expired_exceptions}.'
        slots:
          list_id: query.list_id
          namespace_type: query.namespace_type
          include_expired_exceptions: query.include_expired_exceptions
      - text: Copy list {list_id} ({namespace_type}) and include_expired_exceptions {include_expired_exceptions}.
        slots:
          list_id: query.list_id
          namespace_type: query.namespace_type
          include_expired_exceptions: query.include_expired_exceptions
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/exception_lists/_export'].post
  update:
    x-apievangelist-phrasing:
      intent: Export an exception list to a file
      effect: read
      questions:
      - How do I export an exception list and its items as NDJSON?
      - Can I back up an exception list without its expired items?
      instructions:
      - text: Export exception list {list_id} with id {id} in namespace {namespace_type}, include expired {include_expired_exceptions}.
        slots:
          list_id: query.list_id
          id: query.id
          namespace_type: query.namespace_type
          include_expired_exceptions: query.include_expired_exceptions
      - text: Download list {list_id} (id {id}, {namespace_type}) as a file, expired items {include_expired_exceptions}.
        slots:
          list_id: query.list_id
          id: query.id
          namespace_type: query.namespace_type
          include_expired_exceptions: query.include_expired_exceptions
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/exception_lists/_find'].get
  update:
    x-apievangelist-phrasing:
      intent: Search and list exception lists
      effect: read
      questions:
      - Which exception lists exist in my Kibana space?
      - Can I filter and sort exception lists and page through them?
      instructions:
      - text: List all exception lists.
      - text: Find exception lists matching {filter}, {per_page} per page.
        slots:
          filter: query.filter
          per_page: query.per_page
      - text: List exception lists sorted by {sort_field} in {sort_order} order.
        slots:
          sort_field: query.sort_field
          sort_order: query.sort_order
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/exception_lists/_import'].post
  update:
    x-apievangelist-phrasing:
      intent: Import an exception list from a file
      effect: write
      questions:
      - How do I import exception lists from an exported NDJSON file?
      - Can I import a list as a new copy rather than overwriting the existing one?
      instructions:
      - text: Import exception lists from file {file}.
        slots:
          file: requestBody.file
      - text: Import {file} and overwrite existing lists when overwrite is {overwrite}.
        slots:
          file: requestBody.file
          overwrite: query.overwrite
      - text: Import {file} as a new list with as_new_list {as_new_list}.
        slots:
          file: requestBody.file
          as_new_list: query.as_new_list
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/exception_lists/items'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an exception list item
      effect: read
      questions:
      - What does a single exception item contain?
      - Can I look up an exception item by its item_id?
      instructions:
      - text: Get exception item {item_id}.
        slots:
          item_id: query.item_id
      - text: Show exception list item with id {id} in namespace {namespace_type}.
        slots:
          id: query.id
          namespace_type: query.namespace_type
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/exception_lists/items'].put
  update:
    x-apievangelist-phrasing:
      intent: Update an exception list item
      effect: write
      questions:
      - How do I change the conditions on an existing exception item?
      - Can I edit an exception item I already added to a list?
      instructions:
      - text: Update an existing exception list item.
      - text: Edit the entries of an exception item that's already in a list.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/exception_lists/items'].post
  update:
    x-apievangelist-phrasing:
      intent: Add an item to an exception list
      effect: write
      questions:
      - How do I add a new exception item to a shared exception list?
      - Can I add an entry to an existing list rather than to one rule?
      instructions:
      - text: Create a new item in an exception list.
      - text: Add an exception entry to a shared list.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/exception_lists/items'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an exception list item
      effect: destructive
      questions:
      - How do I remove one exception item from a list?
      - Can I delete an exception item using its item_id?
      instructions:
      - text: Delete exception item {item_id}.
        slots:
          item_id: query.item_id
      - text: Remove the exception list item with id {id} in namespace {namespace_type}.
        slots:
          id: query.id
          namespace_type: query.namespace_type
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/exception_lists/items/_find'].get
  update:
    x-apievangelist-phrasing:
      intent: List the items in an exception list
      effect: read
      questions:
      - What exceptions are inside a particular exception list?
      - Can I search within one list's exception items and page the results?
      instructions:
      - text: List the items in exception list {list_id}.
        slots:
          list_id: query.list_id
      - text: Search exception list {list_id} items for {search}.
        slots:
          list_id: query.list_id
          search: query.search
      - text: List items of {list_id} sorted by {sort_field}, {per_page} per page.
        slots:
          list_id: query.list_id
          sort_field: query.sort_field
          per_page: query.per_page
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/exception_lists/summary'].get
  update:
    x-apievangelist-phrasing:
      intent: Summarize an exception list by OS
      effect: read
      questions:
      - How many exception items in a list apply to Windows, Linux or macOS?
      - Can I get item counts per operating system for an exception list?
      instructions:
      - text: Summarize exception list {list_id}.
        slots:
          list_id: query.list_id
      - text: Give me the per-OS item counts for list {list_id} filtered by {filter}.
        slots:
          list_id: query.list_id
          filter: query.filter
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/exceptions/shared'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a shared exception list
      effect: write
      questions:
      - How do I create a shared exception list that many rules can reference?
      - What do I need to provide to set up a shared exception list?
      instructions:
      - text: Create a shared exception list named {name} described as {description}.
        slots:
          name: requestBody.name
          description: requestBody.description
      - text: Set up shared list {name} for reuse across rules, description {description}.
        slots:
          name: requestBody.name
          description: requestBody.description
      method: generated
      generated: '2026-09-26'