Kibana Security Endpoint Exceptions API API
Endpoint Exceptions API allows you to manage detection rule endpoint exceptions to prevent a rule from generating an alert from incoming events even when the rule's other criteria are met.
OpenAPI Specification
openapi: 3.0.3
info:
contact:
name: Kibana Team
description: 'The Kibana REST APIs enable you to manage resources such as connectors, data views, and saved objects.
The API calls are stateless.
Each request that you make happens in isolation from other calls and must include all of the necessary information for Kibana to fulfill the
request.
API requests return JSON output, which is a format that is machine-readable and works well for automation.
To interact with Kibana APIs, use the following operations:
- GET: Fetches the information.
- PATCH: Applies partial modifications to the existing information.
- POST: Adds new information.
- PUT: Updates the existing information.
- DELETE: Removes the information.
You can prepend any Kibana API endpoint with `kbn:` and run the request in **Dev Tools → Console**.
For example:
```
GET kbn:/api/data_views
```
For more information about the console, refer to [Run API requests](https://www.elastic.co/docs/explore-analyze/query-filter/tools/console).
NOTE: Access to internal Kibana API endpoints will be restricted in Kibana version 9.0. Please move any integrations to publicly documented APIs.
## Documentation source and versions
This documentation is derived from the `main` branch of the [kibana](https://github.com/elastic/kibana) repository.
It is provided under license [Attribution-NonCommercial-NoDerivatives 4.0 International](https://creativecommons.org/licenses/by-nc-nd/4.0/).
This documentation contains work-in-progress information for future Elastic Stack releases.
'
title: Kibana APIs Actions Security Endpoint Exceptions API API
version: ''
x-doc-license:
name: Attribution-NonCommercial-NoDerivatives 4.0 International
url: https://creativecommons.org/licenses/by-nc-nd/4.0/
x-feedbackLink:
label: Feedback
url: https://github.com/elastic/docs-content/issues/new?assignees=&labels=feedback%2Ccommunity&projects=&template=api-feedback.yaml&title=%5BFeedback%5D%3A+
servers:
- url: https://{kibana_url}
variables:
kibana_url:
default: localhost:5601
security:
- apiKeyAuth: []
- basicAuth: []
tags:
- description: Endpoint Exceptions API allows you to manage detection rule endpoint exceptions to prevent a rule from generating an alert from incoming events even when the rule's other criteria are met.
name: Security Endpoint Exceptions API
x-displayName: Security Elastic Endpoint exceptions
paths:
/api/endpoint_list:
post:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb post">post</span> <span class="operation-path">/s/{space_id}/api/endpoint_list</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Create the exception list for Elastic Endpoint rule exceptions. When you create the exception list, it will have a `list_id` of `endpoint_list`. If the Elastic Endpoint exception list already exists, your request will return an empty response.'
operationId: CreateEndpointList
responses:
'200':
content:
application/json:
examples:
alreadyExists:
summary: Endpoint exception list already exists (empty response)
value: {}
newList:
summary: Endpoint exception list created
value:
created_at: '2025-01-01T00:00:00.000Z'
created_by: elastic
description: Endpoint Security Exception List
id: 2e23a8c4-ef7e-4c10-adfa-3eae4e4b4b8b
immutable: false
list_id: endpoint_list
name: Endpoint Security Exception List
namespace_type: agnostic
os_types: []
tags: []
tie_breaker_id: e3c5a8e0-5b6a-4b4b-8b3a-2e23a8c4ef7e
type: endpoint
updated_at: '2025-01-01T00:00:00.000Z'
updated_by: elastic
version: 1
schema:
$ref: '#/components/schemas/Security_Endpoint_Exceptions_API_EndpointList'
description: Successful response
'400':
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Security_Endpoint_Exceptions_API_PlatformErrorResponse'
- $ref: '#/components/schemas/Security_Endpoint_Exceptions_API_SiemErrorResponse'
description: Invalid input data
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/Security_Endpoint_Exceptions_API_PlatformErrorResponse'
description: Unsuccessful authentication
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/Security_Endpoint_Exceptions_API_PlatformErrorResponse'
description: Insufficient privileges
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/Security_Endpoint_Exceptions_API_SiemErrorResponse'
description: Internal server error
summary: Create an Elastic Endpoint rule exception list
tags:
- Security Endpoint Exceptions API
x-metaTags:
- content: Kibana
name: product_name
/api/endpoint_list/items:
delete:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb delete">delete</span> <span class="operation-path">/s/{space_id}/api/endpoint_list/items</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Delete an Elastic Endpoint exception list item, specified by the `id` or `item_id` field.'
operationId: DeleteEndpointListItem
parameters:
- description: Either `id` or `item_id` must be specified
in: query
name: id
required: false
schema:
$ref: '#/components/schemas/Security_Endpoint_Exceptions_API_ExceptionListItemId'
- description: Either `id` or `item_id` must be specified
in: query
name: item_id
required: false
schema:
$ref: '#/components/schemas/Security_Endpoint_Exceptions_API_ExceptionListItemHumanId'
responses:
'200':
content:
application/json:
examples:
deleted:
summary: Deleted endpoint exception list item
value:
comments: []
created_at: '2025-01-01T12:00:00.000Z'
created_by: elastic
description: Blocks a known malicious file by its hash
entries:
- field: file.hash.sha256
operator: included
type: match
value: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
id: d4b0c1e2-3f4a-5b6c-7d8e-9f0a1b2c3d4e
item_id: block-malicious-file
list_id: endpoint_list
name: Block malicious file
namespace_type: agnostic
os_types:
- windows
tags: []
tie_breaker_id: f1e2d3c4-b5a6-7890-abcd-ef1234567890
type: simple
updated_at: '2025-01-01T12:00:00.000Z'
updated_by: elastic
schema:
$ref: '#/components/schemas/Security_Endpoint_Exceptions_API_ExceptionListItem'
description: Successful response
'400':
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Security_Endpoint_Exceptions_API_PlatformErrorResponse'
- $ref: '#/components/schemas/Security_Endpoint_Exceptions_API_SiemErrorResponse'
description: Invalid input data
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/Security_Endpoint_Exceptions_API_PlatformErrorResponse'
description: Unsuccessful authentication
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/Security_Endpoint_Exceptions_API_PlatformErrorResponse'
description: Insufficient privileges
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/Security_Endpoint_Exceptions_API_SiemErrorResponse'
description: Endpoint list item not found
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/Security_Endpoint_Exceptions_API_SiemErrorResponse'
description: Internal server error
summary: Delete an Elastic Endpoint exception list item
tags:
- Security Endpoint Exceptions API
x-metaTags:
- content: Kibana
name: product_name
get:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb get">get</span> <span class="operation-path">/s/{space_id}/api/endpoint_list/items</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Get the details of an Elastic Endpoint exception list item, specified by the `id` or `item_id` field.'
operationId: ReadEndpointListItem
parameters:
- description: Either `id` or `item_id` must be specified
in: query
name: id
required: false
schema:
$ref: '#/components/schemas/Security_Endpoint_Exceptions_API_ExceptionListItemId'
- description: Either `id` or `item_id` must be specified
in: query
name: item_id
required: false
schema:
$ref: '#/components/schemas/Security_Endpoint_Exceptions_API_ExceptionListItemHumanId'
responses:
'200':
content:
application/json:
examples:
item:
summary: Endpoint exception list item
value:
comments: []
created_at: '2025-01-01T12:00:00.000Z'
created_by: elastic
description: Blocks a known malicious file by its hash
entries:
- field: file.hash.sha256
operator: included
type: match
value: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
id: d4b0c1e2-3f4a-5b6c-7d8e-9f0a1b2c3d4e
item_id: block-malicious-file
list_id: endpoint_list
name: Block malicious file
namespace_type: agnostic
os_types:
- windows
tags:
- policy:all
tie_breaker_id: f1e2d3c4-b5a6-7890-abcd-ef1234567890
type: simple
updated_at: '2025-01-01T12:00:00.000Z'
updated_by: elastic
schema:
$ref: '#/components/schemas/Security_Endpoint_Exceptions_API_ExceptionListItem'
description: Successful response
'400':
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Security_Endpoint_Exceptions_API_PlatformErrorResponse'
- $ref: '#/components/schemas/Security_Endpoint_Exceptions_API_SiemErrorResponse'
description: Invalid input data
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/Security_Endpoint_Exceptions_API_PlatformErrorResponse'
description: Unsuccessful authentication
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/Security_Endpoint_Exceptions_API_PlatformErrorResponse'
description: Insufficient privileges
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/Security_Endpoint_Exceptions_API_SiemErrorResponse'
description: Endpoint list item not found
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/Security_Endpoint_Exceptions_API_SiemErrorResponse'
description: Internal server error
summary: Get an Elastic Endpoint rule exception list item
tags:
- Security Endpoint Exceptions API
x-metaTags:
- content: Kibana
name: product_name
post:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb post">post</span> <span class="operation-path">/s/{space_id}/api/endpoint_list/items</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Create an Elastic Endpoint exception list item, and associate it with the Elastic Endpoint exception list.'
operationId: CreateEndpointListItem
requestBody:
content:
application/json:
examples:
matchAny:
summary: Exclude multiple process names
value:
description: Exclude common security tools from endpoint protection
entries:
- field: process.name
operator: included
type: match_any
value:
- scanner.exe
- updater.exe
name: Trusted security tools
os_types:
- windows
type: simple
simpleMatch:
summary: Block a specific file hash
value:
description: Blocks a known malicious file by its hash
entries:
- field: file.hash.sha256
operator: included
type: match
value: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
name: Block malicious file
os_types:
- windows
tags:
- policy:all
type: simple
schema:
type: object
properties:
comments:
$ref: '#/components/schemas/Security_Endpoint_Exceptions_API_ExceptionListItemCommentArray'
default: []
description:
$ref: '#/components/schemas/Security_Endpoint_Exceptions_API_ExceptionListItemDescription'
entries:
$ref: '#/components/schemas/Security_Endpoint_Exceptions_API_ExceptionListItemEntryArray'
item_id:
$ref: '#/components/schemas/Security_Endpoint_Exceptions_API_ExceptionListItemHumanId'
meta:
$ref: '#/components/schemas/Security_Endpoint_Exceptions_API_ExceptionListItemMeta'
name:
$ref: '#/components/schemas/Security_Endpoint_Exceptions_API_ExceptionListItemName'
os_types:
$ref: '#/components/schemas/Security_Endpoint_Exceptions_API_ExceptionListItemOsTypeArray'
default: []
tags:
$ref: '#/components/schemas/Security_Endpoint_Exceptions_API_ExceptionListItemTags'
default: []
type:
$ref: '#/components/schemas/Security_Endpoint_Exceptions_API_ExceptionListItemType'
required:
- type
- name
- description
- entries
description: Exception list item's properties
required: true
responses:
'200':
content:
application/json:
examples:
created:
summary: Endpoint exception list item created
value:
comments: []
created_at: '2025-01-01T12:00:00.000Z'
created_by: elastic
description: Blocks a known malicious file by its hash
entries:
- field: file.hash.sha256
operator: included
type: match
value: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
id: d4b0c1e2-3f4a-5b6c-7d8e-9f0a1b2c3d4e
item_id: block-malicious-file
list_id: endpoint_list
name: Block malicious file
namespace_type: agnostic
os_types:
- windows
tags:
- policy:all
tie_breaker_id: f1e2d3c4-b5a6-7890-abcd-ef1234567890
type: simple
updated_at: '2025-01-01T12:00:00.000Z'
updated_by: elastic
schema:
$ref: '#/components/schemas/Security_Endpoint_Exceptions_API_ExceptionListItem'
description: Successful response
'400':
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Security_Endpoint_Exceptions_API_PlatformErrorResponse'
- $ref: '#/components/schemas/Security_Endpoint_Exceptions_API_SiemErrorResponse'
description: Invalid input data
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/Security_Endpoint_Exceptions_API_PlatformErrorResponse'
description: Unsuccessful authentication
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/Security_Endpoint_Exceptions_API_PlatformErrorResponse'
description: Insufficient privileges
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/Security_Endpoint_Exceptions_API_SiemErrorResponse'
description: Endpoint list item already exists
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/Security_Endpoint_Exceptions_API_SiemErrorResponse'
description: Internal server error
summary: Create an Elastic Endpoint rule exception list item
tags:
- Security Endpoint Exceptions API
x-metaTags:
- content: Kibana
name: product_name
put:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb put">put</span> <span class="operation-path">/s/{space_id}/api/endpoint_list/items</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Update an Elastic Endpoint exception list item, specified by the `id` or `item_id` field.'
operationId: UpdateEndpointListItem
requestBody:
content:
application/json:
examples:
updateName:
summary: Update an endpoint exception list item
value:
description: Updated description for the exception
entries:
- field: file.hash.sha256
operator: included
type: match
value: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
item_id: block-malicious-file
name: Block malicious file (updated)
os_types:
- windows
- linux
type: simple
schema:
type: object
properties:
_version:
description: The version id, normally returned by the API when the item is retrieved. Use it ensure updates are made against the latest version.
type: string
comments:
$ref: '#/components/schemas/Security_Endpoint_Exceptions_API_ExceptionListItemCommentArray'
default: []
description:
$ref: '#/components/schemas/Security_Endpoint_Exceptions_API_ExceptionListItemDescription'
entries:
$ref: '#/components/schemas/Security_Endpoint_Exceptions_API_ExceptionListItemEntryArray'
id:
$ref: '#/components/schemas/Security_Endpoint_Exceptions_API_ExceptionListItemId'
description: Either `id` or `item_id` must be specified
item_id:
$ref: '#/components/schemas/Security_Endpoint_Exceptions_API_ExceptionListItemHumanId'
description: Either `id` or `item_id` must be specified
meta:
$ref: '#/components/schemas/Security_Endpoint_Exceptions_API_ExceptionListItemMeta'
name:
$ref: '#/components/schemas/Security_Endpoint_Exceptions_API_ExceptionListItemName'
os_types:
$ref: '#/components/schemas/Security_Endpoint_Exceptions_API_ExceptionListItemOsTypeArray'
default: []
tags:
$ref: '#/components/schemas/Security_Endpoint_Exceptions_API_ExceptionListItemTags'
type:
$ref: '#/components/schemas/Security_Endpoint_Exceptions_API_ExceptionListItemType'
required:
- type
- name
- description
- entries
description: Exception list item's properties
required: true
responses:
'200':
content:
application/json:
examples:
updated:
summary: Endpoint exception list item updated
value:
comments: []
created_at: '2025-01-01T12:00:00.000Z'
created_by: elastic
description: Updated description for the exception
entries:
- field: file.hash.sha256
operator: included
type: match
value: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
id: d4b0c1e2-3f4a-5b6c-7d8e-9f0a1b2c3d4e
item_id: block-malicious-file
list_id: endpoint_list
name: Block malicious file (updated)
namespace_type: agnostic
os_types:
- windows
- linux
tags:
- policy:all
tie_breaker_id: f1e2d3c4-b5a6-7890-abcd-ef1234567890
type: simple
updated_at: '2025-01-15T09:30:00.000Z'
updated_by: elastic
schema:
$ref: '#/components/schemas/Security_Endpoint_Exceptions_API_ExceptionListItem'
description: Successful response
'400':
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Security_Endpoint_Exceptions_API_PlatformErrorResponse'
- $ref: '#/components/schemas/Security_Endpoint_Exceptions_API_SiemErrorResponse'
description: Invalid input data
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/Security_Endpoint_Exceptions_API_PlatformErrorResponse'
description: Unsuccessful authentication
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/Security_Endpoint_Exceptions_API_PlatformErrorResponse'
description: Insufficient privileges
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/Security_Endpoint_Exceptions_API_SiemErrorResponse'
description: Endpoint list item not found
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/Security_Endpoint_Exceptions_API_SiemErrorResponse'
description: Internal server error
summary: Update an Elastic Endpoint rule exception list item
tags:
- Security Endpoint Exceptions API
x-metaTags:
- content: Kibana
name: product_name
/api/endpoint_list/items/_find:
get:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb get">get</span> <span class="operation-path">/s/{space_id}/api/endpoint_list/items/_find</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Get a list of all Elastic Endpoint exception list items.'
operationId: FindEndpointListItems
parameters:
- description: 'Filters the returned results according to the value of the specified field,
using the `<field name>:<field value>` syntax.
'
in: query
name: filter
required: false
schema:
$ref: '#/components/schemas/Security_Endpoint_Exceptions_API_NonEmptyString'
- description: The page number to return
in: query
name: page
required: false
schema:
minimum: 0
type: integer
- description: The number of exception list items to return per page
in: query
name: per_page
required: false
schema:
minimum: 0
type: integer
- description: Determines which field is used to sort the results
in: query
name: sort_field
required: false
schema:
$ref: '#/components/schemas/Security_Endpoint_Exceptions_API_NonEmptyString'
- description: Determines the sort order, which can be `desc` or `asc`
in: query
name: sort_order
required: false
schema:
enum:
- desc
- asc
type: string
responses:
'200':
content:
application/json:
examples:
foundItems:
summary: Found endpoint exception list items
value:
data:
- comments: []
created_at: '2025-01-01T12:00:00.000Z'
created_by: elastic
description: Blocks a known malicious file by its hash
entries:
- field: file.hash.sha256
operator: included
type: match
value: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
id: d4b0c1e2-3f4a-5b6c-7d8e-9f0a1b2c3d4e
item_id: block-malicious-file
list_id: endpoint_list
name: Block malicious file
namespace_type: agnostic
os_types:
- windows
tags:
- policy:all
tie_breaker_id: f1e2d3c4-b5a6-7890-abcd-ef1234567890
type: simple
updated_at: '2025-01-01T12:00:00.000Z'
updated_by: elastic
page: 1
per_page: 20
total: 1
schema:
type: object
properties:
data:
description: The list of endpoint exception list items.
items:
$ref: '#/components/schemas/Security_Endpoint_Exceptions_API_ExceptionListItem'
type: array
page:
description: The current page number.
minimum: 0
type: integer
per_page:
description: The number of items per page.
minimum: 0
type: integer
pit:
description: The point-in-time ID for pagination.
type: string
total:
description: The total number of endpoint exception list items.
minimum: 0
type: integer
required:
- data
- page
- per_page
- total
description: Successful response
'400':
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Security_Endpoint_Exceptions_API_PlatformErrorResponse'
- $ref: '#/components/schemas/Security_Endpoint_Exceptions_API_SiemErrorResponse'
description: Invalid input data
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/Security_Endpoint_Exceptions_API_PlatformErrorResponse'
description: Unsuccessful authentication
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/Security_Endpoint_Exceptions_API_PlatformErrorResponse'
description: Insufficient privileges
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/Security_Endpoint_Exceptions_API_SiemErrorResponse'
description: Endpoint list not found
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/Security_Endpoint_Exceptions_API_SiemErrorResponse'
description: Internal server error
summary: Get Elastic Endpoint exception list items
tags:
- Security Endpoint Exceptions API
x-metaTags:
- content: Kibana
name: product_name
components:
schemas:
Security_Endpoint_Exceptions_API_EndpointList:
oneOf:
- $ref: '#/components/schemas/Security_Endpoint_Exceptions_API_ExceptionList'
- additionalProperties: false
type: object
Security_Endpoint_Exceptions_API_ExceptionListOsTypeArray:
description: Use this field to specify the operating system. Only enter one value.
items:
$ref: '#/components/schemas/Security_Endpoint_Exceptions_API_ExceptionListOsType'
type: array
Security_Endpoint_Exceptions_API_ExceptionListName:
description: The name of the exception list.
example: My exception list
type: string
Security_Endpoint_Exceptions_API_ExceptionListItemComment:
type: object
properties:
comment:
$ref: '#/components/schemas/Security_Endpoint_Exceptions_API_NonEmptyString'
created_at:
description: Autogenerated date of object creation.
format: date-time
type: string
created_by:
$ref: '#/components/schemas/Security_Endpoint_Exceptions_API_NonEmptyString'
id:
$ref: '#/components/schemas/Security_Endpoint_Exceptions_API_NonEmptyString'
updated_at:
description: Autogenerated date of last object update.
format: date-time
type: string
updated_by:
$ref: '#/components/schemas/Security_Endpoint_Exceptions_API_NonEmptyString'
required:
- id
- comment
- created_at
- created_by
Security_Endpoint_Exceptions_API_ExceptionListItemTags:
items:
descriptio
# --- truncated at 32 KB (49 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/kibana/refs/heads/main/openapi/kibana-security-endpoint-exceptions-api-api-openapi.yml