Elastic Stack (ELK Stack) Security Endpoint Exceptions 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.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/elk-stack-security-endpoint-exceptions-api-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
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 Security Endpoint Exceptions 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:
examples:
badRequest:
value:
error: Bad Request
message: '[request body]: expected value of type [object] but got [undefined]'
statusCode: 400
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:
examples:
unauthorized:
value:
error: Unauthorized
message: "[security_exception\n\tRoot causes:\n\t\tsecurity_exception: unable to authenticate user [elastic] for REST request [/_security/_authenticate]]: unable to authenticate user [elastic] for REST request [/_security/_authenticate]"
statusCode: 401
schema:
$ref: '#/components/schemas/Security_Endpoint_Exceptions_API_PlatformErrorResponse'
description: Unsuccessful authentication
'403':
content:
application/json:
examples:
forbidden:
value:
error: Forbidden
message: API [POST /api/endpoint_list] is unauthorized for user, this action is granted by the Kibana privileges [lists-all]
statusCode: 403
schema:
$ref: '#/components/schemas/Security_Endpoint_Exceptions_API_PlatformErrorResponse'
description: Insufficient privileges
'500':
content:
application/json:
examples:
serverError:
value:
message: Internal Server Error
status_code: 500
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:
examples:
badRequest:
value:
error: Bad Request
message: Either "item_id" or "id" needs to be defined in the request
statusCode: 400
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:
examples:
unauthorized:
value:
error: Unauthorized
message: "[security_exception\n\tRoot causes:\n\t\tsecurity_exception: unable to authenticate user [elastic] for REST request [/_security/_authenticate]]: unable to authenticate user [elastic] for REST request [/_security/_authenticate]"
statusCode: 401
schema:
$ref: '#/components/schemas/Security_Endpoint_Exceptions_API_PlatformErrorResponse'
description: Unsuccessful authentication
'403':
content:
application/json:
examples:
forbidden:
value:
error: Forbidden
message: API [DELETE /api/endpoint_list/items?item_id=block-malicious-file] is unauthorized for user, this action is granted by the Kibana privileges [lists-all]
statusCode: 403
schema:
$ref: '#/components/schemas/Security_Endpoint_Exceptions_API_PlatformErrorResponse'
description: Insufficient privileges
'404':
content:
application/json:
examples:
notFound:
value:
message: 'exception list item item_id: "block-malicious-file" does not exist'
status_code: 404
schema:
$ref: '#/components/schemas/Security_Endpoint_Exceptions_API_SiemErrorResponse'
description: Endpoint list item not found
'500':
content:
application/json:
examples:
serverError:
value:
message: Internal Server Error
status_code: 500
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:
examples:
badRequest:
value:
error: Bad Request
message: id or item_id required
statusCode: 400
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:
examples:
unauthorized:
value:
error: Unauthorized
message: "[security_exception\n\tRoot causes:\n\t\tsecurity_exception: unable to authenticate user [elastic] for REST request [/_security/_authenticate]]: unable to authenticate user [elastic] for REST request [/_security/_authenticate]"
statusCode: 401
schema:
$ref: '#/components/schemas/Security_Endpoint_Exceptions_API_PlatformErrorResponse'
description: Unsuccessful authentication
'403':
content:
application/json:
examples:
forbidden:
value:
error: Forbidden
message: API [GET /api/endpoint_list/items?item_id=block-malicious-file] is unauthorized for user, this action is granted by the Kibana privileges [lists-read]
statusCode: 403
schema:
$ref: '#/components/schemas/Security_Endpoint_Exceptions_API_PlatformErrorResponse'
description: Insufficient privileges
'404':
content:
application/json:
examples:
notFound:
value:
message: 'exception list item item_id: "block-malicious-file" does not exist'
status_code: 404
schema:
$ref: '#/components/schemas/Security_Endpoint_Exceptions_API_SiemErrorResponse'
description: Endpoint list item not found
'500':
content:
application/json:
examples:
serverError:
value:
message: Internal Server Error
status_code: 500
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:
examples:
badRequest:
value:
error: Bad Request
message: '[request body]: name: Required'
statusCode: 400
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:
examples:
unauthorized:
value:
error: Unauthorized
message: "[security_exception\n\tRoot causes:\n\t\tsecurity_exception: unable to authenticate user [elastic] for REST request [/_security/_authenticate]]: unable to authenticate user [elastic] for REST request [/_security/_authenticate]"
statusCode: 401
schema:
$ref: '#/components/schemas/Security_Endpoint_Exceptions_API_PlatformErrorResponse'
description: Unsuccessful authentication
'403':
content:
application/json:
examples:
forbidden:
value:
error: Forbidden
message: API [POST /api/endpoint_list/items] is unauthorized for user, this action is granted by the Kibana privileges [lists-all]
statusCode: 403
schema:
$ref: '#/components/schemas/Security_Endpoint_Exceptions_API_PlatformErrorResponse'
description: Insufficient privileges
'409':
content:
application/json:
examples:
alreadyExists:
value:
message: 'exception list item id: "block-malicious-file" already exists'
status_code: 409
schema:
$ref: '#/components/schemas/Security_Endpoint_Exceptions_API_SiemErrorResponse'
description: Endpoint list item already exists
'500':
content:
application/json:
examples:
serverError:
value:
message: Internal Server Error
status_code: 500
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:
examples:
badRequest:
value:
error: Bad Request
message: '[request body]: name: Required'
statusCode: 400
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:
examples:
unauthorized:
value:
error: Unauthorized
message: "[security_exception\n\tRoot causes:\n\t\tsecurity_exception: unable to authenticate user [elastic] for REST request [/_security/_authenticate]]: unable to authenticate user [elastic] for REST request [/_security/_authenticate]"
statusCode: 401
schema:
$ref: '#/components/schemas/Security_Endpoint_Exceptions_API_PlatformErrorResponse'
description: Unsuccessful authentication
'403':
content:
application/json:
examples:
forbidden:
value:
error: Forbidden
message: API [PUT /api/endpoint_list/items] is unauthorized for user, this action is granted by the Kibana privileges [lists-all]
statusCode: 403
schema:
$ref: '#/components/schemas/Security_Endpoint_Exceptions_API_PlatformErrorResponse'
description: Insufficient privileges
'404':
content:
application/json:
examples:
notFound:
value:
message: 'list item item_id: "block-malicious-file" not found'
status_code: 404
schema:
$ref: '#/components/schemas/Security_Endpoint_Exceptions_API_SiemErrorResponse'
description: Endpoint list item not found
'500':
content:
application/json:
examples:
serverError:
value:
message: Internal Server Error
status_code: 500
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
# --- truncated at 32 KB (56 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/elk-stack/refs/heads/main/openapi/elk-stack-security-endpoint-exceptions-api-api-openapi.yml