GET /api/endpoint_list/items/_find
Api key auth

Spaces method and path for this operation:

get /s/{space_id}/api/endpoint_list/items/_find

Refer to Spaces for more information.

Get a list of all Elastic Endpoint exception list items.

Query parameters

  • filter string(nonempty)

    Filters the returned results according to the value of the specified field, using the <field name>:<field value> syntax.

    Minimum length is 1.

  • page integer

    The page number to return

    Minimum value is 0.

  • per_page integer

    The number of exception list items to return per page

    Minimum value is 0.

  • sort_field string(nonempty)

    Determines which field is used to sort the results

    Minimum length is 1.

  • sort_order string

    Determines the sort order, which can be desc or asc

    Values are desc or asc.

Responses

  • 200 application/json

    Successful response

    Hide response attributes Show response attributes object
    • data array[object] Required

      The list of endpoint exception list items.

      Hide data attributes Show data 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.

      • comments array[object] Required

        Array of comment fields:

        • comment (string): Comments about the exception item.
        Hide comments attributes Show comments attributes object
        • comment string(nonempty) Required

          A string that does not contain only whitespace characters

          Minimum length is 1.

        • created_at string(date-time) Required

          Autogenerated date of object creation.

        • created_by string(nonempty) Required

          A string that does not contain only whitespace characters

          Minimum length is 1.

        • id string(nonempty) Required

          A string that does not contain only whitespace characters

          Minimum length is 1.

        • updated_at string(date-time)

          Autogenerated date of last object update.

        • updated_by string(nonempty)

          A string that does not contain only whitespace characters

          Minimum length is 1.

      • 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.

      • entries array[object] Required
        Any of:
        Security_Endpoint_Exceptions_API_ExceptionListItemEntryMatch object Security_Endpoint_Exceptions_API_ExceptionListItemEntryMatchAny object Security_Endpoint_Exceptions_API_ExceptionListItemEntryList object Security_Endpoint_Exceptions_API_ExceptionListItemEntryExists object Security_Endpoint_Exceptions_API_ExceptionListItemEntryNested object Security_Endpoint_Exceptions_API_ExceptionListItemEntryMatchWildcard object
      • expire_time string(date-time)

        The exception item’s expiration date, in ISO format. This field is only available for regular exception items, not endpoint exceptions.

      • id string(nonempty) Required

        Exception's identifier.

        Minimum length is 1.

      • item_id string(nonempty) Required

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

        Minimum length is 1.

      • 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

        Additional properties are allowed.

      • name string(nonempty) Required

        Exception list name.

        Minimum length is 1.

      • 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.

        Values are linux, macos, or windows.

      • tags array[string(nonempty)]

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

        Minimum length of each is 1.

      • tie_breaker_id string Required

        Field used in search to ensure all containers are sorted and returned correctly.

      • type string Required

        Value is simple.

      • updated_at string(date-time) Required

        Autogenerated date of last object update.

      • updated_by string Required

        Autogenerated value - user that last updated object.

    • page integer Required

      The current page number.

      Minimum value is 0.

    • per_page integer Required

      The number of items per page.

      Minimum value is 0.

    • pit string

      The point-in-time ID for pagination.

    • total integer Required

      The total number of endpoint exception list items.

      Minimum value is 0.
  • 400 application/json

    Invalid input data

    One of:
    Security_Endpoint_Exceptions_API_PlatformErrorResponse object Security_Endpoint_Exceptions_API_SiemErrorResponse object
  • 401 application/json

    Unsuccessful authentication

    Hide response attributes Show response attributes object
    • error string Required
    • message string Required
    • statusCode integer Required
  • 403 application/json

    Insufficient privileges

    Hide response attributes Show response attributes object
    • error string Required
    • message string Required
    • statusCode integer Required
  • 404 application/json

    Endpoint list not found

    Hide response attributes Show response attributes object
    • message string Required
    • status_code integer Required
  • 500 application/json

    Internal server error

    Hide response attributes Show response attributes object
    • message string Required
    • status_code integer Required
GET /api/endpoint_list/items/_find 
curl \
 --request GET 'https://<KIBANA_URL>/api/endpoint_list/items/_find' \
 --header "Authorization: $API_KEY"
Response examples (200) 
{
  "data": [
    {
      "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"
    }
  ],
  "page": 1,
  "per_page": 20,
  "total": 1
}