Sign in

v53

latestOpenAPI 3.0.3raw.githubusercontent.com2026-08-076771,7565.2 MB
Security Exceptions API

Create an exception list

Spaces method and path for this operation:

<div><span class="operation-verb post">post</span>&nbsp;<span class="operation-path">/s/{space_id}/api/exception_lists</span></div>

Refer to Spaces for more information.

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

info 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.

post/api/exception_lists

Request body

descriptionstring required

Describes the exception list.

list_idstring nonempty

The exception list's human-readable string identifier.

For endpoint artifacts, use one of the following values:

  • endpoint_list: Elastic Endpoint exceptions list
  • endpoint_trusted_apps: Trusted applications list
  • endpoint_trusted_devices: Trusted devices list
  • endpoint_event_filters: Event filters list
  • endpoint_host_isolation_exceptions: Host isolation exceptions list
  • endpoint_blocklists: Blocklist
metaSecurityExceptionsAPIExceptionListMeta

Placeholder for metadata about the list container.

namestring required

The name of the exception list.

namespace_type'agnostic' | 'single'

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.

For endpoint artifacts, the namespace_type must always be agnostic. Space awareness for endpoint artifacts is enforced based on Elastic Defend policy assignments.

os_typesSecurityExceptionsAPIExceptionListOsType[]

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

tagsstring[]

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

type'detection' | 'rule_default' | 'endpoint' | 'endpoint_trusted_apps' | 'endpoint_trusted_devices' | 'endpoint_events' | 'endpoint_host_isolation_exceptions' | 'endpoint_blocklists' | 'endpoint_custom_yara_signatures' required

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

versioninteger

The document version, automatically increasd on updates.

Example request

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

Response

Successful response

_versionstring

The version id, normally returned by the API when the item was retrieved. Use it ensure updates are done against the latest version.

created_atstring date-time required

Autogenerated date of object creation.

created_bystring required

Autogenerated value - user that created object.

descriptionstring required

Describes the exception list.

idstring nonempty required

Exception list's identifier.

immutableboolean required
list_idstring nonempty required

The exception list's human-readable string identifier.

For endpoint artifacts, use one of the following values:

  • endpoint_list: Elastic Endpoint exceptions list
  • endpoint_trusted_apps: Trusted applications list
  • endpoint_trusted_devices: Trusted devices list
  • endpoint_event_filters: Event filters list
  • endpoint_host_isolation_exceptions: Host isolation exceptions list
  • endpoint_blocklists: Blocklist
metaSecurityExceptionsAPIExceptionListMeta

Placeholder for metadata about the list container.

namestring required

The name of the exception list.

namespace_type'agnostic' | 'single' 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.

For endpoint artifacts, the namespace_type must always be agnostic. Space awareness for endpoint artifacts is enforced based on Elastic Defend policy assignments.

os_typesSecurityExceptionsAPIExceptionListOsType[]

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

tagsstring[]

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

tie_breaker_idstring required

Field used in search to ensure all containers are sorted and returned correctly.

type'detection' | 'rule_default' | 'endpoint' | 'endpoint_trusted_apps' | 'endpoint_trusted_devices' | 'endpoint_events' | 'endpoint_host_isolation_exceptions' | 'endpoint_blocklists' | 'endpoint_custom_yara_signatures' required

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

updated_atstring date-time required

Autogenerated date of last object update.

updated_bystring required

Autogenerated value - user that last updated object.

versioninteger required

The document version, automatically increasd on updates.

Example response

{
  "description": "This list tracks allowlisted values.",
  "id": "9e5fc75a-a3da-46c5-96e3-a2ec59c6bb85",
  "list_id": "simple_list",
  "name": "My exception list"
}