--- type: api title: Create rule exception items description: Create exception items that apply to a single detection rule. url: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/kibana/v0/operation/operation-createruleexceptionlistitems resource: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/kibana/v0/operation/operation-createruleexceptionlistitems products: - Kibana --- # Create rule exception items - Server: `https://{kibana_url}` ## Paths - `POST` `/api/detection_engine/rules/{id}/exceptions` - [Api key auth](/elastic/docs-builder/docs/4371/api/doc/kibana/v0/authentication#apikeyauth) - [Basic auth](/elastic/docs-builder/docs/4371/api/doc/kibana/v0/authentication#basicauth) #### Path Parameters - `id` (string) Detection rule's identifier ## Description Create exception items that apply to a single detection rule. ## Request Body `application/json` Rule exception items. - `items` ([] object) — required - `comments` ([] object) — optional - `comment` (string · min: 1) — required A string that does not contain only whitespace characters - `description` (string) — required Describes the exception list. - `entries` ([] object) — required - `expire_time` (string) — optional - `item_id` (string · min: 1) — optional Human readable string identifier, e.g. `trusted-linux-processes` - `meta` (object) — optional - `name` (string · min: 1) — required Exception list name. - `namespace_type` (enum) — optional 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` ([] object) — optional Values: `linux`, `macos`, `windows` - `tags` ([] object) — optional - `type` (enum) — required Values: `simple` ## Responses #### `200` Successful response `application/json` Type: `[] 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. - `comments` ([] object) Array of comment fields: - comment (string): Comments about the exception item. - `comment` (string · min: 1) A string that does not contain only whitespace characters - `created_at` (string) Autogenerated date of object creation. - `created_by` (string · min: 1) A string that does not contain only whitespace characters - `id` (string · min: 1) A string that does not contain only whitespace characters - `updated_at` (string) Autogenerated date of last object update. - `updated_by` (string · min: 1) A string that does not contain only whitespace characters - `created_at` (string) Autogenerated date of object creation. - `created_by` (string) Autogenerated value - user that created object. - `description` (string) Describes the exception list. - `entries` ([] object) - `expire_time` (string) The exception item’s expiration date, in ISO format. This field is only available for regular exception items, not endpoint exceptions. - `id` (string · min: 1) Exception's identifier. - `item_id` (string · min: 1) Human readable string identifier, e.g. `trusted-linux-processes` - `list_id` (string · min: 1) 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 · min: 1) 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` - `os_types` ([] object) Values: `linux`, `macos`, `windows` - `tags` ([] object) - `tie_breaker_id` (string) Field used in search to ensure all containers are sorted and returned correctly. - `type` (enum) Values: `simple` - `updated_at` (string) Autogenerated date of last object update. - `updated_by` (string) Autogenerated value - user that last updated object. #### `400` Invalid input data response `application/json` One of: - **PlatformErrorResponse** - `error` (string) - `message` (string) - `statusCode` (integer) - **SiemErrorResponse** - `message` (string) - `status_code` (integer) #### `401` Unsuccessful authentication response `application/json` - `error` (string) - `message` (string) - `statusCode` (integer) #### `403` Not enough privileges response `application/json` - `error` (string) - `message` (string) - `statusCode` (integer) #### `500` Internal server error response `application/json` - `message` (string) - `status_code` (integer) ## Code Examples #### Console ```console POST /api/detection_engine/rules/{id}/exceptions { "items": [ { "description": "This is a sample detection type exception item.", "entries": [ { "field": "actingProcess.file.signer", "operator": "excluded", "type": "exists" }, { "field": "host.name", "operator": "included", "type": "match_any", "value": [ "saturn", "jupiter" ] } ], "item_id": "simple_list_item", "list_id": "simple_list", "name": "Sample Exception List Item", "namespace_type": "single", "os_types": [ "linux" ], "tags": [ "malware" ], "type": "simple" } ] } ``` #### curl ```curl curl -X POST "https://{kibana_url}/api/detection_engine/rules/{id}/exceptions" \ -H "Content-Type: application/json" \ -d '{ "items": [ { "description": "This is a sample detection type exception item.", "entries": [ { "field": "actingProcess.file.signer", "operator": "excluded", "type": "exists" }, { "field": "host.name", "operator": "included", "type": "match_any", "value": [ "saturn", "jupiter" ] } ], "item_id": "simple_list_item", "list_id": "simple_list", "name": "Sample Exception List Item", "namespace_type": "single", "os_types": [ "linux" ], "tags": [ "malware" ], "type": "simple" } ] }' ``` ## Response Examples #### Rule exception items ```json [ { "_version": "WzQsMV0=", "comments": [], "created_at": "2025-01-07T20:07:33.119Z", "created_by": "elastic", "description": "This is a sample detection type exception item.", "entries": [ { "field": "actingProcess.file.signer", "operator": "excluded", "type": "exists" }, { "field": "host.name", "operator": "included", "type": "match_any", "value": [ "saturn", "jupiter" ] } ], "id": "71a9f4b2-c85c-49b4-866f-c71eb9e67da2", "item_id": "simple_list_item", "list_id": "simple_list", "name": "Sample Exception List Item", "namespace_type": "single", "os_types": [ "linux" ], "tags": [ "malware" ], "tie_breaker_id": "09434836-9db9-4942-a234-5a9268e0b34c", "type": "simple", "updated_at": "2025-01-07T20:07:33.119Z", "updated_by": "elastic" } ] ``` #### Bad payload ```json { "error": "Bad Request", "message": "Invalid request payload JSON format", "statusCode": 400 } ``` #### Bad ```json { "error": "Bad Request", "message": "[request params]: id: Invalid uuid", "statusCode": 400 } ``` #### Unauthorized ```json { "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 } ``` #### Forbidden ```json { "message": "Unable to create exception-list", "status_code": 403 } ``` #### Server error ```json { "message": "Internal Server Error", "status_code": 500 } ```