Create an exception list

POST /api/exception_lists

An exception list groups exception items and can be associated with detection rules. You can assign exception lists to multiple detection rules.

All exception items added to the same list are evaluated using OR logic. That is, if any of the items in a list evaluate to true, the exception prevents the rule from generating an alert. Likewise, OR logic is used for evaluating exceptions when more than one exception list is assigned to a rule. To use the AND operator, you can define multiple clauses (entries) in a single exception item.

application/json

Body Required

Exception list's properties

description string Required

Describes the exception list.
list_id string(nonempty)

Exception list's human readable string identifier, e.g. trusted-linux-processes.

Minimum length is 1.
meta object

Placeholder for metadata about the list container.

Additional properties are allowed.
name string Required

The name of the exception list.
namespace_type string
Determines whether the exception container is available in all Kibana spaces or just the space in which it is created, where:
- single: Only available in the Kibana space in which it is created.
- agnostic: Available in all Kibana spaces.
Values are agnostic or single. Default value is single.
os_types array[string]

Use this field to specify the operating system. Only enter one value.

Values are linux, macos, or windows.
tags array[string]

String array containing words and phrases to help categorize exception containers.
type string Required

The type of exception list to be created. Different list types may denote where they can be utilized.

Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.
version integer

The document version, automatically increasd on updates.

Minimum value is 1.

Responses

200 application/json

Successful response
Hide response attributes Show response attributes object
- _version string
  
  The version id, normally returned by the API when the item was retrieved. Use it ensure updates are done against the latest version.
- created_at string(date-time) Required
  
  Autogenerated date of object creation.
- created_by string Required
  
  Autogenerated value - user that created object.
- description string Required
  
  Describes the exception list.
- id string(nonempty) Required
  
  Exception list's identifier.
  
  Minimum length is 1.
- immutable boolean Required
- list_id string(nonempty) Required
  
  Exception list's human readable string identifier, e.g. trusted-linux-processes.
  
  Minimum length is 1.
- meta object
  
  Placeholder for metadata about the list container.
  
  Additional properties are allowed.
- name string Required
  
  The name of the exception list.
- namespace_type string Required
  
  Determines whether the exception container is available in all Kibana spaces or just the space in which it is created, where:
  
  single: Only available in the Kibana space in which it is created.
  
  agnostic: Available in all Kibana spaces.
  
  Values are agnostic or single. Default value is single.
- os_types array[string]
  
  Use this field to specify the operating system. Only enter one value.
  
  Values are linux, macos, or windows.
- tags array[string]
  
  String array containing words and phrases to help categorize exception containers.
- tie_breaker_id string Required
  
  Field used in search to ensure all containers are sorted and returned correctly.
- type string Required
  
  The type of exception list to be created. Different list types may denote where they can be utilized.
  
  Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.
- updated_at string(date-time) Required
  
  Autogenerated date of last object update.
- updated_by string Required
  
  Autogenerated value - user that last updated object.
- version integer Required
  
  The document version, automatically increasd on updates.
  
  Minimum value is 1.
400 application/json

Invalid input data response
One of:
Security_Exceptions_API_PlatformErrorResponse object Security_Exceptions_API_SiemErrorResponse object
Hide attributes Show attributes

error string Required

message string Required

statusCode integer Required
Hide attributes Show attributes

message string Required

status_code integer Required
401 application/json

Unsuccessful authentication response
Hide response attributes Show response attributes object
- error string Required
- message string Required
- statusCode integer Required
403 application/json

Not enough privileges response
Hide response attributes Show response attributes object
- error string Required
- message string Required
- statusCode integer Required
409 application/json

Exception list already exists response
Hide response attributes Show response attributes object
- message string Required
- status_code integer Required
500 application/json

Internal server error response
Hide response attributes Show response attributes object
- message string Required
- status_code integer Required

POST /api/exception_lists

curl \
 --request POST 'https://localhost:5601/api/exception_lists' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"name":"Sample Detection Exception List","tags":["malware"],"type":"detection","list_id":"simple_list","os_types":["linux"],"description":"This is a sample detection type exception list.","namespace_type":"single"}'

Request example

{
  "name": "Sample Detection Exception List",
  "tags": [
    "malware"
  ],
  "type": "detection",
  "list_id": "simple_list",
  "os_types": [
    "linux"
  ],
  "description": "This is a sample detection type exception list.",
  "namespace_type": "single"
}

Response examples (200)

{
  "id": "28243c2f-624a-4443-823d-c0b894880931",
  "name": "Sample Detection Exception List",
  "tags": [
    "malware"
  ],
  "type": "detection",
  "list_id": "8c1aae4c-1ef5-4bce-a2e3-16584b501783",
  "version": 1,
  "_version": "WzMsMV0=",
  "os_types": [],
  "immutable": false,
  "created_at": "2025-01-09T01:05:23.019Z",
  "created_by": "elastic",
  "updated_at": "2025-01-09T01:05:23.020Z",
  "updated_by": "elastic",
  "description": "This is a sample detection type exception with an autogenerated list_id.",
  "namespace_type": "single",
  "tie_breaker_id": "ad94de31-39f7-4ad7-b8e4-988bfa95f338"
}

{
  "id": "1a744e77-22ca-4b6b-9085-54f55275ebe5",
  "name": "Sample Agnostic Endpoint Exception List",
  "tags": [
    "malware"
  ],
  "type": "endpoint",
  "list_id": "b935eb55-7b21-4c1c-b235-faa1df23b3d6",
  "version": 1,
  "_version": "WzUsMV0=",
  "os_types": [
    "linux"
  ],
  "immutable": false,
  "created_at": "2025-01-09T01:10:36.369Z",
  "created_by": "elastic",
  "updated_at": "2025-01-09T01:10:36.369Z",
  "updated_by": "elastic",
  "description": "This is a sample agnostic endpoint type exception.",
  "namespace_type": "agnostic",
  "tie_breaker_id": "49ea0adc-a2b8-4d83-a8f3-2fb98301dea3"
}

{
  "id": "9e5fc75a-a3da-46c5-96e3-a2ec59c6bb85",
  "name": "Sample Detection Exception List",
  "tags": [
    "malware"
  ],
  "type": "detection",
  "list_id": "simple_list",
  "version": 1,
  "_version": "WzIsMV0=",
  "os_types": [
    "linux"
  ],
  "immutable": false,
  "created_at": "2025-01-07T19:34:27.942Z",
  "created_by": "elastic",
  "updated_at": "2025-01-07T19:34:27.942Z",
  "updated_by": "elastic",
  "description": "This is a sample detection type exception list.",
  "namespace_type": "single",
  "tie_breaker_id": "78f1aca1-f8ee-4eb5-9ceb-f5c3ee656cb3"
}

{
  "id": "a79f4730-6e32-4278-abfc-349c0add7d54",
  "name": "Sample Endpoint Exception List",
  "tags": [
    "malware"
  ],
  "type": "endpoint",
  "list_id": "endpoint_list",
  "version": 1,
  "_version": "WzQsMV0=",
  "os_types": [
    "linux"
  ],
  "immutable": false,
  "created_at": "2025-01-09T01:07:49.658Z",
  "created_by": "elastic",
  "updated_at": "2025-01-09T01:07:49.658Z",
  "updated_by": "elastic",
  "description": "This is a sample endpoint type exception list.",
  "namespace_type": "single",
  "tie_breaker_id": "94a028af-8f47-427a-aca5-ffaf829e64ee"
}

Response examples (400)

{
  "error": "Bad Request",
  "message": "[request body]: list_id: Expected string, received number",
  "statusCode": 400
}

Response examples (401)

{
  "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
}

Response examples (403)

{
  "error": "Forbidden",
  "message": "API [POST /api/exception_lists] is unauthorized for user, this action is granted by the Kibana privileges [lists-all]",
  "statusCode": 403
}

Response examples (409)

{
  "message": "exception list id: \"simple_list\" already exists",
  "status_code": 409
}

Response examples (500)

{
  "message": "Internal Server Error",
  "status_code": 500
}