Create an exception list

Base URL: https://{kibana_url}

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

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.

Note

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.

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's properties

description string required

Describes the exception list.

list_id string · format: nonempty · min length: 1

The exception list's human-readable string identifier.

For endpoint artifacts, use one of the following values:

endpoint_list: Elastic Endpoint exception 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: Blocklists list

meta object

Placeholder for metadata about the list container.

name string required

The name of the exception list.

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

os_types enum[]

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

Values: linux macos windows

tags string[]

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

type enum required

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

Values: detection rule_default endpoint endpoint_trusted_apps endpoint_trusted_devices endpoint_events endpoint_host_isolation_exceptions endpoint_blocklists

version integer · min: 1

The document version, automatically increasd on updates.

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.

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.

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

Exception list's identifier.

immutable boolean 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 exception 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: Blocklists list

meta object

Placeholder for metadata about the list container.

name string required

The name of the exception list.

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[]

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

Values: linux macos windows

tags 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 enum required

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

Values: detection rule_default endpoint endpoint_trusted_apps endpoint_trusted_devices endpoint_events endpoint_host_isolation_exceptions endpoint_blocklists

updated_at string · format: date-time required

Autogenerated date of last object update.

updated_by string required

Autogenerated value - user that last updated object.

version integer · min: 1 required

The document version, automatically increasd on updates.

Invalid input data response

application/json

Unsuccessful authentication response

application/json

Not enough privileges response

application/json

Exception list already exists response

application/json

Internal server error response

application/json

Base URL: https://{kibana_url}

Examples

Request Console 1 / 2 languages

Console Kibana Dev Tools

POST kbn:/api/exception_lists
{
  "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"
}

Generated from the API spec

curl Shell

curl -X POST "${KIBANA_URL}/api/exception_lists" \
  -H "Authorization: ApiKey ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "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"
  }'

Generated from the API spec

Response

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

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

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

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

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

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

Authentication

Request body { }

Responses

Request body