Create an exception list item

Base URL: https://{kibana_url}

POST /api/exception_lists/items

Create an exception item and associate it with the specified exception list.

Note

Before creating exception items, you must create an exception list.

Authentication

Api key

Authorization: <value>

These APIs use key-based authentication. You must create an API key and use the encoded value in the request header. For example: Authorization: ApiKey base64AccessApiKey

Basic

Authorization: Basic <credentials>

Request body

Exception list item's properties

One of:

comments object[]

description string required

Describes the exception list.

expire_time string · format: date-time

The exception item’s expiration date, in ISO format. This field is only available for regular exception items, not endpoint exceptions.

item_id string · format: nonempty · min length: 1

Human readable string identifier, e.g. trusted-linux-processes

meta object

name string · format: nonempty · min length: 1 required

Exception list name.

namespace_type enum

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.

Values: agnostic single

type enum required

Values: simple

entries union[] required

list_id string · format: nonempty · min length: 1 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

os_types enum[]

Values: linux macos windows

tags string[] · format: nonempty

comments object[]

description string required

Describes the exception list.

expire_time string · format: date-time

The exception item’s expiration date, in ISO format. This field is only available for regular exception items, not endpoint exceptions.

item_id string · format: nonempty · min length: 1

Human readable string identifier, e.g. trusted-linux-processes

meta object

name string · format: nonempty · min length: 1 required

Exception list name.

namespace_type enum

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.

Values: agnostic single

type enum required

Values: simple

entries union[]

list_id enum required

Values: endpoint_list

os_types enum[]

Values: linux macos windows

tags string[] · default: []

Tags for categorization. Special tags for scope control:

"policy:all" - Global artifact (applies to all Elastic Defend policies)
"policy:<policy_id>" - Private artifact (applies to specific Elastic Defend policy only, where <policy_id> is the Elastic Defend integration policy ID)

comments object[]

description string required

Describes the exception list.

expire_time string · format: date-time

The exception item’s expiration date, in ISO format. This field is only available for regular exception items, not endpoint exceptions.

item_id string · format: nonempty · min length: 1

Human readable string identifier, e.g. trusted-linux-processes

meta object

name string · format: nonempty · min length: 1 required

Exception list name.

namespace_type enum

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.

Values: agnostic single

type enum required

Values: simple

entries union oneOf[] · min items: 1

Process hash, executable path, or code signature entries

One of:

field enum required: Process hash field; Values: process.hash.md5 process.hash.sha1 process.hash.sha256
operator enum required: Values: included
type enum required: Hash entries only support match type; Values: match
value string required: Hash value (MD5, SHA1, or SHA256)

list_id enum required

Values: endpoint_trusted_apps

os_types enum[] · min items: 1 · max items: 1

Must be Windows only

Values: windows

tags string[] · default: []

Tags for categorization. Special tags for scope control:

"policy:all" - Global artifact (applies to all Elastic Defend policies)
"policy:<policy_id>" - Private artifact (applies to specific Elastic Defend policy only, where <policy_id> is the Elastic Defend integration policy ID)

comments object[]

description string required

Describes the exception list.

expire_time string · format: date-time

The exception item’s expiration date, in ISO format. This field is only available for regular exception items, not endpoint exceptions.

item_id string · format: nonempty · min length: 1

Human readable string identifier, e.g. trusted-linux-processes

meta object

name string · format: nonempty · min length: 1 required

Exception list name.

namespace_type enum

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.

Values: agnostic single

type enum required

Values: simple

entries union oneOf[] · min items: 1

Process hash, executable path, or code signature entries

One of:

field enum required: Process hash field; Values: process.hash.md5 process.hash.sha1 process.hash.sha256
operator enum required: Values: included
type enum required: Hash entries only support match type; Values: match
value string required: Hash value (MD5, SHA1, or SHA256)

list_id enum required

Values: endpoint_trusted_apps

os_types enum[] · min items: 1 · max items: 1

Must be macOS only

Values: macos

tags string[] · default: []

Tags for categorization. Special tags for scope control:

"policy:all" - Global artifact (applies to all Elastic Defend policies)
"policy:<policy_id>" - Private artifact (applies to specific Elastic Defend policy only, where <policy_id> is the Elastic Defend integration policy ID)

comments object[]

description string required

Describes the exception list.

expire_time string · format: date-time

The exception item’s expiration date, in ISO format. This field is only available for regular exception items, not endpoint exceptions.

item_id string · format: nonempty · min length: 1

Human readable string identifier, e.g. trusted-linux-processes

meta object

name string · format: nonempty · min length: 1 required

Exception list name.

namespace_type enum

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.

Values: agnostic single

type enum required

Values: simple

entries union oneOf[] · min items: 1

Process hash or executable path entries (code signature not supported on Linux)

One of:

field enum required: Process hash field; Values: process.hash.md5 process.hash.sha1 process.hash.sha256
operator enum required: Values: included
type enum required: Hash entries only support match type; Values: match
value string required: Hash value (MD5, SHA1, or SHA256)

list_id enum required

Values: endpoint_trusted_apps

os_types enum[] · min items: 1 · max items: 1

Must be Linux only

Values: linux

tags string[] · default: []

Tags for categorization. Special tags for scope control:

"policy:all" - Global artifact (applies to all Elastic Defend policies)
"policy:<policy_id>" - Private artifact (applies to specific Elastic Defend policy only, where <policy_id> is the Elastic Defend integration policy ID)

comments object[]

description string required

Describes the exception list.

expire_time string · format: date-time

The exception item’s expiration date, in ISO format. This field is only available for regular exception items, not endpoint exceptions.

item_id string · format: nonempty · min length: 1

Human readable string identifier, e.g. trusted-linux-processes

meta object

name string · format: nonempty · min length: 1 required

Exception list name.

namespace_type enum

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.

Values: agnostic single

type enum required

Values: simple

entries object[] · min items: 1

Exception entries for the trusted device (duplicate field entries are not allowed)

list_id enum required

Values: endpoint_trusted_devices

os_types enum[] · min items: 1 · max items: 1

Must be Windows-only to allow username field

Values: windows

tags string[] · default: []

Tags for categorization. Special tags for scope control:

"policy:all" - Global artifact (applies to all Elastic Defend policies)
"policy:<policy_id>" - Private artifact (applies to specific Elastic Defend policy only, where <policy_id> is the Elastic Defend integration policy ID)

comments object[]

description string required

Describes the exception list.

expire_time string · format: date-time

The exception item’s expiration date, in ISO format. This field is only available for regular exception items, not endpoint exceptions.

item_id string · format: nonempty · min length: 1

Human readable string identifier, e.g. trusted-linux-processes

meta object

name string · format: nonempty · min length: 1 required

Exception list name.

namespace_type enum

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.

Values: agnostic single

type enum required

Values: simple

entries object[] · min items: 1

Exception entries for the trusted device (duplicate field entries are not allowed)

list_id enum required

Values: endpoint_trusted_devices

os_types enum[] · min items: 1 · max items: 1

macOS-only

Values: macos

tags string[] · default: []

Tags for categorization. Special tags for scope control:

"policy:all" - Global artifact (applies to all Elastic Defend policies)
"policy:<policy_id>" - Private artifact (applies to specific Elastic Defend policy only, where <policy_id> is the Elastic Defend integration policy ID)

comments object[]

description string required

Describes the exception list.

expire_time string · format: date-time

The exception item’s expiration date, in ISO format. This field is only available for regular exception items, not endpoint exceptions.

item_id string · format: nonempty · min length: 1

Human readable string identifier, e.g. trusted-linux-processes

meta object

name string · format: nonempty · min length: 1 required

Exception list name.

namespace_type enum

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.

Values: agnostic single

type enum required

Values: simple

entries object[] · min items: 1

Exception entries for the trusted device (duplicate field entries are not allowed, username not available when targeting both OS)

list_id enum required

Values: endpoint_trusted_devices

os_types enum[] · min items: 2 · max items: 2

Must include both Windows and macOS (username field not allowed)

Values: windows macos

tags string[] · default: []

Tags for categorization. Special tags for scope control:

"policy:all" - Global artifact (applies to all Elastic Defend policies)
"policy:<policy_id>" - Private artifact (applies to specific Elastic Defend policy only, where <policy_id> is the Elastic Defend integration policy ID)

comments object[]

description string required

Describes the exception list.

expire_time string · format: date-time

The exception item’s expiration date, in ISO format. This field is only available for regular exception items, not endpoint exceptions.

item_id string · format: nonempty · min length: 1

Human readable string identifier, e.g. trusted-linux-processes

meta object

name string · format: nonempty · min length: 1 required

Exception list name.

namespace_type enum

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.

Values: agnostic single

type enum required

Values: simple

entries union[]

list_id enum required

Values: endpoint_event_filters

os_types enum[]

Values: linux macos windows

tags string[] · default: []

Tags for categorization. Special tags for scope control:

"policy:all" - Global artifact (applies to all Elastic Defend policies)
"policy:<policy_id>" - Private artifact (applies to specific Elastic Defend policy only, where <policy_id> is the Elastic Defend integration policy ID)

comments object[]

description string required

Describes the exception list.

expire_time string · format: date-time

The exception item’s expiration date, in ISO format. This field is only available for regular exception items, not endpoint exceptions.

item_id string · format: nonempty · min length: 1

Human readable string identifier, e.g. trusted-linux-processes

meta object

name string · format: nonempty · min length: 1 required

Exception list name.

namespace_type enum

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.

Values: agnostic single

type enum required

Values: simple

entries object[] · min items: 1 · max items: 1

Exactly one entry allowed for host isolation exceptions

list_id enum required

Values: endpoint_host_isolation_exceptions

os_types enum[] · min items: 3 · max items: 3

Must include all three operating systems (windows, linux, macos)

Values: windows linux macos

tags string[] · default: []

Tags for categorization. Special tags for scope control:

"policy:all" - Global artifact (applies to all Elastic Defend policies)
"policy:<policy_id>" - Private artifact (applies to specific Elastic Defend policy only, where <policy_id> is the Elastic Defend integration policy ID)

comments object[]

description string required

Describes the exception list.

expire_time string · format: date-time

The exception item’s expiration date, in ISO format. This field is only available for regular exception items, not endpoint exceptions.

item_id string · format: nonempty · min length: 1

Human readable string identifier, e.g. trusted-linux-processes

meta object

name string · format: nonempty · min length: 1 required

Exception list name.

namespace_type enum

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.

Values: agnostic single

type enum required

Values: simple

entries union oneOf[] · min items: 1

Validation rules:

Hash entries: up to 3 (one for each hash type: md5, sha1, sha256)
Path entry: only 1 allowed
Code signature entry: only 1 allowed

One of:

type enum required: Must be match_any for blocklists; Values: match_any
field enum required: File hash or path field; Values: file.hash.md5 file.hash.sha1 file.hash.sha256 file.path file.path.caseless
operator enum required: Must be the value "included"; Values: included
value string[] · min items: 1 required: Array of hash values or file paths

list_id enum required

Values: endpoint_blocklists

os_types enum[] · min items: 1 · max items: 1

Windows-only

Values: windows

tags string[] · default: []

Tags for categorization. Special tags for scope control:

"policy:all" - Global artifact (applies to all Elastic Defend policies)
"policy:<policy_id>" - Private artifact (applies to specific Elastic Defend policy only, where <policy_id> is the Elastic Defend integration policy ID)

comments object[]

description string required

Describes the exception list.

expire_time string · format: date-time

The exception item’s expiration date, in ISO format. This field is only available for regular exception items, not endpoint exceptions.

item_id string · format: nonempty · min length: 1

Human readable string identifier, e.g. trusted-linux-processes

meta object

name string · format: nonempty · min length: 1 required

Exception list name.

namespace_type enum

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.

Values: agnostic single

type enum required

Values: simple

entries object[] · min items: 1

Validation rules:

Hash entries: up to 3 (one for each hash type: md5, sha1, sha256)
Path entry: only 1 allowed

list_id enum required

Values: endpoint_blocklists

os_types enum[] · min items: 1 · max items: 1

Linux-only

Values: linux

tags string[] · default: []

Tags for categorization. Special tags for scope control:

"policy:all" - Global artifact (applies to all Elastic Defend policies)
"policy:<policy_id>" - Private artifact (applies to specific Elastic Defend policy only, where <policy_id> is the Elastic Defend integration policy ID)

comments object[]

description string required

Describes the exception list.

expire_time string · format: date-time

The exception item’s expiration date, in ISO format. This field is only available for regular exception items, not endpoint exceptions.

item_id string · format: nonempty · min length: 1

Human readable string identifier, e.g. trusted-linux-processes

meta object

name string · format: nonempty · min length: 1 required

Exception list name.

namespace_type enum

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.

Values: agnostic single

type enum required

Values: simple

entries object[] · min items: 1

Validation rules:

Hash entries: up to 3 (one for each hash type: md5, sha1, sha256)
Path entry: only 1 allowed

list_id enum required

Values: endpoint_blocklists

os_types enum[] · min items: 1 · max items: 1

macOS-only

Values: macos

tags string[] · default: []

Tags for categorization. Special tags for scope control:

"policy:all" - Global artifact (applies to all Elastic Defend policies)
"policy:<policy_id>" - Private artifact (applies to specific Elastic Defend policy only, where <policy_id> is the Elastic Defend integration policy ID)

Responses

Successful response

application/json

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

comments object[] required

Array of comment fields:

comment (string): Comments about the exception item.

created_at string · format: 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.

entries union[] required

expire_time string · format: date-time

The exception item’s expiration date, in ISO format. This field is only available for regular exception items, not endpoint exceptions.

id string · format: nonempty · min length: 1 required

Exception's identifier.

item_id string · format: nonempty · min length: 1 required

Human readable string identifier, e.g. trusted-linux-processes

list_id string · format: nonempty · min length: 1 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

meta object

name string · format: nonempty · min length: 1 required

Exception list name.

namespace_type enum 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.

Values: agnostic single

os_types enum[]

Values: linux macos windows

tags string[] · format: nonempty

tie_breaker_id string required

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

type enum required

Values: simple

updated_at string · format: date-time required

Autogenerated date of last object update.

updated_by string required

Autogenerated value - user that last updated object.

Invalid input data response

application/json

Unsuccessful authentication response

application/json

Not enough privileges response

application/json

Exception list item already exists response

application/json

Internal server error response

application/json