Create an Elastic Endpoint rule exception list item

Server: https://{kibana_url}

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

Api key auth Basic auth

Refer to Spaces for more information.

Create an Elastic Endpoint exception list item, and associate it with the Elastic Endpoint exception list.

Request

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 required

Autogenerated date of object creation.

created_by string required

Autogenerated value - user that created object.

description string required

Describes the exception list.

entries [] object required

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 required

Exception's identifier.

item_id string · min: 1 required

Human readable string identifier, e.g. trusted-linux-processes

list_id string · min: 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

name string · min: 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 [] object

Values: linux macos windows

tags [] object

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 required

Autogenerated date of last object update.

updated_by string required

Autogenerated value - user that last updated object.

Invalid input data

application/json

Unsuccessful authentication

application/json

Insufficient privileges

application/json

Endpoint list item already exists

application/json

Internal server error

application/json

Examples

Request Console 1 / 2 languages

Console Kibana Dev Tools

POST /api/endpoint_list/items
{
  "description": "Exclude common security tools from endpoint protection",
  "entries": [
    {
      "field": "process.name",
      "operator": "included",
      "type": "match_any",
      "value": [
        "scanner.exe",
        "updater.exe"
      ]
    }
  ],
  "name": "Trusted security tools",
  "os_types": [
    "windows"
  ],
  "type": "simple"
}

curl Shell

curl -X POST "https://{kibana_url}/api/endpoint_list/items" \
  -H "Content-Type: application/json" \
  -d '{
  "description": "Exclude common security tools from endpoint protection",
  "entries": [
    {
      "field": "process.name",
      "operator": "included",
      "type": "match_any",
      "value": [
        "scanner.exe",
        "updater.exe"
      ]
    }
  ],
  "name": "Trusted security tools",
  "os_types": [
    "windows"
  ],
  "type": "simple"
}'

Response

{
  "comments": [],
  "created_at": "2025-01-01T12:00:00.000Z",
  "created_by": "elastic",
  "description": "Blocks a known malicious file by its hash",
  "entries": [
    {
      "field": "file.hash.sha256",
      "operator": "included",
      "type": "match",
      "value": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
    }
  ],
  "id": "d4b0c1e2-3f4a-5b6c-7d8e-9f0a1b2c3d4e",
  "item_id": "block-malicious-file",
  "list_id": "endpoint_list",
  "name": "Block malicious file",
  "namespace_type": "agnostic",
  "os_types": [
    "windows"
  ],
  "tags": [
    "policy:all"
  ],
  "tie_breaker_id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
  "type": "simple",
  "updated_at": "2025-01-01T12:00:00.000Z",
  "updated_by": "elastic"
}

{
  "error": "Bad Request",
  "message": "[request body]: name: Required",
  "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/endpoint_list/items] is unauthorized for user, this action is granted by the Kibana privileges [lists-all]",
  "statusCode": 403
}

{
  "message": "exception list item id: \u0022block-malicious-file\u0022 already exists",
  "status_code": 409
}

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

Request Console 1 / 2 languages

Console Kibana Dev Tools

POST /api/endpoint_list/items
{
  "description": "Blocks a known malicious file by its hash",
  "entries": [
    {
      "field": "file.hash.sha256",
      "operator": "included",
      "type": "match",
      "value": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
    }
  ],
  "name": "Block malicious file",
  "os_types": [
    "windows"
  ],
  "tags": [
    "policy:all"
  ],
  "type": "simple"
}

curl Shell

curl -X POST "https://{kibana_url}/api/endpoint_list/items" \
  -H "Content-Type: application/json" \
  -d '{
  "description": "Blocks a known malicious file by its hash",
  "entries": [
    {
      "field": "file.hash.sha256",
      "operator": "included",
      "type": "match",
      "value": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
    }
  ],
  "name": "Block malicious file",
  "os_types": [
    "windows"
  ],
  "tags": [
    "policy:all"
  ],
  "type": "simple"
}'

Response

{
  "comments": [],
  "created_at": "2025-01-01T12:00:00.000Z",
  "created_by": "elastic",
  "description": "Blocks a known malicious file by its hash",
  "entries": [
    {
      "field": "file.hash.sha256",
      "operator": "included",
      "type": "match",
      "value": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
    }
  ],
  "id": "d4b0c1e2-3f4a-5b6c-7d8e-9f0a1b2c3d4e",
  "item_id": "block-malicious-file",
  "list_id": "endpoint_list",
  "name": "Block malicious file",
  "namespace_type": "agnostic",
  "os_types": [
    "windows"
  ],
  "tags": [
    "policy:all"
  ],
  "tie_breaker_id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
  "type": "simple",
  "updated_at": "2025-01-01T12:00:00.000Z",
  "updated_by": "elastic"
}

{
  "error": "Bad Request",
  "message": "[request body]: name: Required",
  "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/endpoint_list/items] is unauthorized for user, this action is granted by the Kibana privileges [lists-all]",
  "statusCode": 403
}

{
  "message": "exception list item id: \u0022block-malicious-file\u0022 already exists",
  "status_code": 409
}

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

Request { comments , description , entries , item_id , meta , name , os_types , tags , type , }

Responses

Request