# 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 Lists API
  version: 1.0.0
extends: openapi/elk-stack-security-lists-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: 18
- target: $.paths['/api/lists'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a value list's details
      effect: read
      questions:
      - Can I look up one value list by its ID?
      - What name, type and description does a given value list have?
      instructions:
      - text: Get the value list {id}.
        slots:
          id: query.id
      - text: Show the details of security value list {id}.
        slots:
          id: query.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/lists'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a value list's name and description
      effect: write
      questions:
      - Can I fully replace a value list, knowing unspecified fields get deleted?
      - How do I overwrite a value list's name and description together?
      instructions:
      - text: Replace value list {id} with name {name} and description {description}.
        slots:
          id: requestBody.id
          name: requestBody.name
          description: requestBody.description
      - text: Overwrite the whole value list {id}, setting description to {description} and name to {name}.
        slots:
          id: requestBody.id
          description: requestBody.description
          name: requestBody.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/lists'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a value list
      effect: write
      questions:
      - How do I create a new value list of IP addresses for exceptions?
      - Which list types can a new value list use, like ip or keyword?
      instructions:
      - text: Create a {type} value list named {name} described as {description}.
        slots:
          type: requestBody.type
          name: requestBody.name
          description: requestBody.description
      - text: Make a new value list with ID {id}, name {name}, type {type} and description {description}.
        slots:
          id: requestBody.id
          name: requestBody.name
          type: requestBody.type
          description: requestBody.description
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/lists'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a value list and its items
      effect: destructive
      questions:
      - Does deleting a value list also delete all of its items?
      - How do I delete a value list even if exception items still reference it?
      instructions:
      - text: Delete value list {id}.
        slots:
          id: query.id
      - text: Delete value list {id} and remove the exception references to it.
        slots:
          id: query.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/lists'].patch
  update:
    x-apievangelist-phrasing:
      intent: Change specific fields of a value list
      effect: write
      questions:
      - Can I change just the name of a value list without replacing the rest?
      - How do I partially update an existing value list?
      instructions:
      - text: Patch value list {id} so its name is {name}.
        slots:
          id: requestBody.id
          name: requestBody.name
      - text: Change only the description of value list {id} to {description}.
        slots:
          id: requestBody.id
          description: requestBody.description
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/lists/_find'].get
  update:
    x-apievangelist-phrasing:
      intent: Browse and filter value lists
      effect: read
      questions:
      - What value lists exist in this Kibana space?
      - Can I page through value lists 20 at a time and sort them?
      instructions:
      - text: List all my value lists.
      - text: Find value lists matching filter {filter}, sorted by {sort_field}.
        slots:
          filter: query.filter
          sort_field: query.sort_field
      - text: Show page {page} of value lists with {per_page} per page.
        slots:
          page: query.page
          per_page: query.per_page
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/lists/index'].get
  update:
    x-apievangelist-phrasing:
      intent: Check that value list data streams exist
      effect: read
      questions:
      - Do the .lists and .items data streams exist in this space?
      - How can I verify value list storage is set up before importing?
      instructions:
      - text: Check the status of the value list data streams.
      - text: Verify that the .lists and .items data streams are present.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/lists/index'].post
  update:
    x-apievangelist-phrasing:
      intent: Create value list data streams (deprecated)
      effect: write
      questions:
      - Do I still need to create the .lists and .items data streams by hand?
      - Is the call that creates value list backing storage deprecated?
      instructions:
      - text: Create the .lists and .items data streams for this space.
      - text: Provision value list backing data streams with the deprecated endpoint.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/lists/index'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete the value list data streams
      effect: destructive
      questions:
      - How do I remove the .lists and .items data streams entirely?
      - Can I delete all value list storage for a space?
      instructions:
      - text: Delete the .lists and .items data streams.
      - text: Tear down value list storage in this space.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/lists/items'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a value list item
      effect: read
      questions:
      - How do I check whether a specific value is in a value list?
      - Can I fetch one list item by its ID?
      instructions:
      - text: Get value list item {id}.
        slots:
          id: query.id
      - text: Look up value {value} in value list {list_id}.
        slots:
          value: query.value
          list_id: query.list_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/lists/items'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a value list item
      effect: write
      questions:
      - Can I fully replace a list item's value, dropping fields I leave out?
      - How do I overwrite a value list item by its ID?
      instructions:
      - text: Replace list item {id} with value {value}.
        slots:
          id: requestBody.id
          value: requestBody.value
      - text: Overwrite the entire value list item {id} so it holds {value}.
        slots:
          id: requestBody.id
          value: requestBody.value
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/lists/items'].post
  update:
    x-apievangelist-phrasing:
      intent: Add an item to a value list
      effect: write
      questions:
      - How do I add an IP address to an existing value list?
      - Must every item in a value list be the same type?
      instructions:
      - text: Add {value} to value list {list_id}.
        slots:
          value: requestBody.value
          list_id: requestBody.list_id
      - text: Create a list item {value} in list {list_id} and refresh right away.
        slots:
          value: requestBody.value
          list_id: requestBody.list_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/lists/items'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove an item from a value list
      effect: destructive
      questions:
      - What call removes a single value from a value list?
      - Can I delete a list item by its value instead of its ID?
      instructions:
      - text: Delete value list item {id}.
        slots:
          id: query.id
      - text: Remove {value} from value list {list_id}.
        slots:
          value: query.value
          list_id: query.list_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/lists/items'].patch
  update:
    x-apievangelist-phrasing:
      intent: Change specific fields of a value list item
      effect: write
      questions:
      - Can I change just a list item's value without replacing its metadata?
      - How do I partially update one value list item?
      instructions:
      - text: Patch list item {id} so its value becomes {value}.
        slots:
          id: requestBody.id
          value: requestBody.value
      - text: Update only the metadata of value list item {id} to {meta}.
        slots:
          id: requestBody.id
          meta: requestBody.meta
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/lists/items/_export'].post
  update:
    x-apievangelist-phrasing:
      intent: Export the values in a value list
      effect: read
      questions:
      - How do I download all the values stored in a value list?
      - Can I export a value list's items to a file?
      instructions:
      - text: Export the items of value list {list_id}.
        slots:
          list_id: query.list_id
      - text: Download every value in list {list_id} as a file.
        slots:
          list_id: query.list_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/lists/items/_find'].get
  update:
    x-apievangelist-phrasing:
      intent: Browse the items in a value list
      effect: read
      questions:
      - What values are in a given value list?
      - Can I page and filter through the items of one list?
      instructions:
      - text: List the items in value list {list_id}.
        slots:
          list_id: query.list_id
      - text: Find items in list {list_id} matching {filter}.
        slots:
          list_id: query.list_id
          filter: query.filter
      - text: Show page {page} of list {list_id} items, {per_page} at a time.
        slots:
          page: query.page
          list_id: query.list_id
          per_page: query.per_page
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/lists/items/_import'].post
  update:
    x-apievangelist-phrasing:
      intent: Import value list items from a TXT or CSV file
      effect: write
      questions:
      - How do I bulk load IP addresses into a value list from a CSV?
      - What is the maximum file size for a value list import?
      instructions:
      - text: Import the values in {file} into value list {list_id}.
        slots:
          file: requestBody.file
          list_id: query.list_id
      - text: Upload {file} as a new {type} value list.
        slots:
          file: requestBody.file
          type: query.type
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/lists/privileges'].get
  update:
    x-apievangelist-phrasing:
      intent: Check my privileges on value lists
      effect: read
      questions:
      - Am I allowed to create or import value lists in this space?
      - Which cluster and index privileges do I hold for the value list data streams?
      instructions:
      - text: Show my value list privileges.
      - text: Check whether I have read or all access to .lists and .items.
      method: generated
      generated: '2026-09-26'