POST /api/exception_lists
Api key auth

Spaces method and path for this operation:

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.

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)

    The exception list's human-readable string identifier.

    For endpoint artifacts, use one of the following values:

    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.

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

    Values are agnostic or 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_trusted_devices, 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

      The exception list's human-readable string identifier.

      For endpoint artifacts, use one of the following values:

      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.

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

      Values are agnostic or 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_trusted_devices, 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
  • 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://<KIBANA_URL>/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
}