Elastic Stack

Elastic Stack (ELK Stack) Security Lists API

Lists can be used with detection rule exceptions to define values that prevent a rule from generating alerts. Lists are made up of: * **List containers**: A container for values of the same Elasticsearch data type. The following data types can be used: * `boolean` * `byte` * `date` * `date_nanos` * `date_range` * `double` * `double_range` * `float` * `float_range` * `half_float` * `integer` * `integer_range` * `ip` * `ip_range` * `keyword` * `long` * `long_range` * `short` * `text` * **List items**: The values used to determine whether the exception prevents an alert from being generated. All list items in the same list container must be of the same data type, and each item defines a single value. For example, an IP list container named `internal-ip-addresses-southport` contains five items, where each item defines one internal IP address: 1. `192.168.1.1` 2. `192.168.1.3` 3. `192.168.1.18` 4. `192.168.1.12` 5. `192.168.1.7` To use these IP addresses as values for defining rule exceptions, use the Security exceptions API to [create an exception list item](../operation/operation-createexceptionlistitem) that references the `internal-ip-addresses-southport` list. > info > Lists cannot be added directly to rules, nor do they define the operators used to determine when exceptions are applied (`is in list`, `is not in list`). Use an exception item to define the operator and associate it with an [exception container](../operation/operation-createexceptionlist). You can then add the exception container to a rule's `exceptions_list` object. ## Lists requirements Before you can start using lists, you must create the `.lists` and `.items` data streams for the relevant Kibana space. To do this, use the [Create list data streams](../operation/operation-createlistindex) endpoint. Once these data streams are created, your role needs privileges to manage rules. Refer to [Enable and access detections](https://www.elastic.co/guide/en/security/current/detections-permissions-section.html#enable-detections-ui) for a complete list of requirements.

Documentation GitHub OpenAPI

Operations 18

Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelist overlay

DELETE /api/lists Delete a value list and its items · Delete a value list #

Ask an LLM

“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?”

Tell an agent destructive · confirm first

Delete value list {id}.

Delete value list {id} and remove the exception references to it.

GET /api/lists Get a value list's details · Get value list details #

Ask an LLM

“Can I look up one value list by its ID?”

“What name, type and description does a given value list have?”

Tell an agent

Get the value list {id}.

Show the details of security value list {id}.

PATCH /api/lists Change specific fields of a value list · Patch a value list #

Ask an LLM

“Can I change just the name of a value list without replacing the rest?”

“How do I partially update an existing value list?”

Tell an agent

Patch value list {id} so its name is {name}.

Change only the description of value list {id} to {description}.

POST /api/lists Create a value list · Create a value list #

Ask an LLM

“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?”

Tell an agent

Create a {type} value list named {name} described as {description}.

Make a new value list with ID {id}, name {name}, type {type} and description {description}.

PUT /api/lists Replace a value list's name and description · Update a value list #

Ask an LLM

“Can I fully replace a value list, knowing unspecified fields get deleted?”

“How do I overwrite a value list's name and description together?”

Tell an agent

Replace value list {id} with name {name} and description {description}.

Overwrite the whole value list {id}, setting description to {description} and name to {name}.

GET /api/lists/_find Browse and filter value lists · Get value lists #

Ask an LLM

“What value lists exist in this Kibana space?”

“Can I page through value lists 20 at a time and sort them?”

Tell an agent

List all my value lists.

Find value lists matching filter {filter}, sorted by {sort_field}.

DELETE /api/lists/index Delete the value list data streams · Delete value list data streams #

Ask an LLM

“How do I remove the .lists and .items data streams entirely?”

“Can I delete all value list storage for a space?”

Tell an agent destructive · confirm first

Delete the .lists and .items data streams.

Tear down value list storage in this space.

GET /api/lists/index Check that value list data streams exist · Get status of value list data streams #

Ask an LLM

“Do the .lists and .items data streams exist in this space?”

“How can I verify value list storage is set up before importing?”

Tell an agent

Check the status of the value list data streams.

Verify that the .lists and .items data streams are present.

POST /api/lists/index Create value list data streams (deprecated) · Create list data streams #

Ask an LLM

“Do I still need to create the .lists and .items data streams by hand?”

“Is the call that creates value list backing storage deprecated?”

Tell an agent

Create the .lists and .items data streams for this space.

Provision value list backing data streams with the deprecated endpoint.

DELETE /api/lists/items Remove an item from a value list · Delete a value list item #

Ask an LLM

“What call removes a single value from a value list?”

“Can I delete a list item by its value instead of its ID?”

Tell an agent destructive · confirm first

Delete value list item {id}.

Remove {value} from value list {list_id}.

GET /api/lists/items Get a value list item · Get a value list item #

Ask an LLM

“How do I check whether a specific value is in a value list?”

“Can I fetch one list item by its ID?”

Tell an agent

Get value list item {id}.

Look up value {value} in value list {list_id}.

PATCH /api/lists/items Change specific fields of a value list item · Patch a value list item #

Ask an LLM

“Can I change just a list item's value without replacing its metadata?”

“How do I partially update one value list item?”

Tell an agent

Patch list item {id} so its value becomes {value}.

Update only the metadata of value list item {id} to {meta}.

POST /api/lists/items Add an item to a value list · Create a value list item #

Ask an LLM

“How do I add an IP address to an existing value list?”

“Must every item in a value list be the same type?”

Tell an agent

Add {value} to value list {list_id}.

Create a list item {value} in list {list_id} and refresh right away.

PUT /api/lists/items Replace a value list item · Update a value list item #

Ask an LLM

“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?”

Tell an agent

Replace list item {id} with value {value}.

Overwrite the entire value list item {id} so it holds {value}.

POST /api/lists/items/_export Export the values in a value list · Export value list items #

Ask an LLM

“How do I download all the values stored in a value list?”

“Can I export a value list's items to a file?”

Tell an agent

Export the items of value list {list_id}.

Download every value in list {list_id} as a file.

GET /api/lists/items/_find Browse the items in a value list · Get value list items #

Ask an LLM

“What values are in a given value list?”

“Can I page and filter through the items of one list?”

Tell an agent

List the items in value list {list_id}.

Find items in list {list_id} matching {filter}.

POST /api/lists/items/_import Import value list items from a TXT or CSV file · Import value list items #

Ask an LLM

“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?”

Tell an agent

Import the values in {file} into value list {list_id}.

Upload {file} as a new {type} value list.

GET /api/lists/privileges Check my privileges on value lists · Get value list privileges #

Ask an LLM

“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?”

Tell an agent

Show my value list privileges.

Check whether I have read or all access to .lists and .items.

Elastic Stack (ELK Stack) Security Lists API

Operations 18

Documentation

Specifications

Other Resources

Work with this as data

MCP server

Tools for apis

Call it yourself

Get an API key

OpenAPI Specification