Create a shared exception list

POST /api/exceptions/shared
Api key auth

An exception list groups exception items and can be associated with detection rules. A shared exception list can apply 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

  • description string Required

    Describes the exception list.

  • name string Required

    The name of the exception list.

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, endpoint_list.

      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.

      Values are agnostic or single. Default value is 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_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/exceptions/shared 
curl \ --request POST 'https://<KIBANA_URL>/api/exceptions/shared' \ --header "Authorization: $API_KEY" \ --header "Content-Type: application/json" \ --data '{"name":"Sample Detection Exception List","tags":["malware"],"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" ], "list_id": "simple_list", "os_types": [ "linux" ], "description": "This is a sample detection type exception list.", "namespace_type": "single" }
Response examples (200) 
{ "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" }
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) 
{ "message": "Unable to create exception-list", "status_code": 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 }