Create an exception list item

Base URL: https://{kibana_url}

POST /api/exception_lists/items
POST /s/{space_id}/api/exception_lists/items

Refer to Spaces for more information.

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