Fleet Server hosts

List all detection rules

GET /api/detection_engine/rules/_find
Api key auth Basic auth

Retrieve a paginated list of detection rules. By default, the first page is returned, with 20 results per page.

Query parameters

  • fields array[string]
  • filter string

    Search query

  • sort_field string

    Field to sort by

    Values are created_at, createdAt, enabled, execution_summary.last_execution.date, execution_summary.last_execution.metrics.execution_gap_duration_s, execution_summary.last_execution.metrics.total_indexing_duration_ms, execution_summary.last_execution.metrics.total_search_duration_ms, execution_summary.last_execution.status, name, risk_score, riskScore, severity, updated_at, or updatedAt.

  • sort_order string

    Sort order

    Values are asc or desc.

  • page integer

    Page number

    Minimum value is 1. Default value is 1.

  • per_page integer

    Rules per page

    Minimum value is 0. Default value is 20.

Responses

  • 200 application/json; Elastic-Api-Version=2023-10-31

    Successful response

    Hide response attributes Show response attributes object
    • data array[object] Required
      Any of:
      Security_Detections_API_EqlRuleResponseFields object Security_Detections_API_QueryRuleResponseFields object Security_Detections_API_SavedQueryRuleResponseFields object Security_Detections_API_ThresholdRuleResponseFields object Security_Detections_API_ThreatMatchRuleResponseFields object Security_Detections_API_MachineLearningRuleResponseFields object Security_Detections_API_NewTermsRuleResponseFields object Security_Detections_API_EsqlRuleResponseFields object
      Hide attributes Show attributes
      • actions array[object] Required
        Hide actions attributes Show actions attributes object
        • action_type_id string Required

          The action type used for sending notifications.

        • alerts_filter object

          Additional properties are allowed.

        • frequency object

          The action frequency defines when the action runs (for example, only on rule execution or at specific time intervals).

          Hide frequency attributes Show frequency attributes object
          • notifyWhen string Required

            The condition for throttling the notification: onActionGroupChange, onActiveAlert, or onThrottleInterval

            Values are onActiveAlert, onThrottleInterval, or onActionGroupChange.

          • summary boolean Required

            Action summary indicates whether we will send a summary notification about all the generate alerts or notification per individual alert

          • throttle string | null Required

            Defines how often rule actions are taken.

            One of:
            string-1 string | null string-2 string | null

            Values are no_actions or rule.

        • group string

          Optionally groups actions by use cases. Use default for alert notifications.

        • id string Required

          The connector ID.

        • params object Required

          Object containing the allowed connector fields, which varies according to the connector type.

          Additional properties are allowed.

        • uuid string(nonempty)

          A string that does not contain only whitespace characters

          Minimum length is 1.

      • alias_purpose string

        Values are savedObjectConversion or savedObjectImport.

      • alias_target_id string
      • author array[string] Required
      • building_block_type string

        Determines if the rule acts as a building block. By default, building-block alerts are not displayed in the UI. These rules are used as a foundation for other rules that do generate alerts. Its value must be default.

      • description string Required

        Minimum length is 1.

      • enabled boolean Required

        Determines whether the rule is enabled.

      • exceptions_list array[object] Required
        Hide exceptions_list attributes Show exceptions_list attributes object
        • id string(nonempty) Required

          A string that does not contain only whitespace characters

          Minimum length is 1.

        • list_id string(nonempty) Required

          A string that does not contain only whitespace characters

          Minimum length is 1.

        • namespace_type string Required

          Determines the exceptions validity in rule's Kibana space

          Values are agnostic or single.

        • type string Required

          The exception type

          Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.

      • false_positives array[string] Required
      • from string(date-math) Required

        Time from which data is analyzed each time the rule runs, using a date math range. For example, now-4200s means the rule analyzes data from 70 minutes before its start time. Defaults to now-6m (analyzes data from 6 minutes before the start time).

      • interval string Required

        Frequency of rule execution, using a date math range. For example, "1h" means the rule runs every hour. Defaults to 5m (5 minutes).

      • investigation_fields object

        Schema for fields relating to investigation fields. These are user defined fields we use to highlight in various features in the UI such as alert details flyout and exceptions auto-population from alert. Added in PR #163235 Right now we only have a single field but anticipate adding more related fields to store various configuration states such as override - where a user might say if they want only these fields to display, or if they want these fields + the fields we select. When expanding this field, it may look something like:

        const investigationFields = z.object({
  field_names: NonEmptyArray(NonEmptyString),
  override: z.boolean().optional(),
});
        Hide investigation_fields attribute Show investigation_fields attribute object
        • field_names array[string(nonempty)] Required

          A string that does not contain only whitespace characters

          At least 1 element. Minimum length of each is 1.

      • license string

        The rule's license.

      • max_signals integer Required

        Minimum value is 1.

      • meta object

        Additional properties are allowed.

      • name string Required

        Minimum length is 1.

      • namespace string

        Has no effect.

      • note string

        Notes to help investigate alerts produced by the rule.

      • outcome string

        Values are exactMatch, aliasMatch, or conflict.

      • output_index string Deprecated

        (deprecated) Has no effect.

      • references array[string] Required
      • related_integrations array[object] Required

        Related integration is a potential dependency of a rule. It's assumed that if the user installs one of the related integrations of a rule, the rule might start to work properly because it will have source events (generated by this integration) potentially matching the rule's query.

        NOTE: Proper work is not guaranteed, because a related integration, if installed, can be configured differently or generate data that is not necessarily relevant for this rule.

        Related integration is a combination of a Fleet package and (optionally) one of the package's "integrations" that this package contains. It is represented by 3 properties:

        • package: name of the package (required, unique id)
        • version: version of the package (required, semver-compatible)
        • integration: name of the integration of this package (optional, id within the package)

        There are Fleet packages like windows that contain only one integration; in this case, integration should be unspecified. There are also packages like aws and azure that contain several integrations; in this case, integration should be specified.

        @example const x: RelatedIntegration = { package: 'windows', version: '1.5.x', };

        @example const x: RelatedIntegration = { package: 'azure', version: '~1.1.6', integration: 'activitylogs', };

        Hide related_integrations attributes Show related_integrations attributes object
        • integration string(nonempty)

          A string that does not contain only whitespace characters

          Minimum length is 1.

        • package string(nonempty) Required

          A string that does not contain only whitespace characters

          Minimum length is 1.

        • version string(nonempty) Required

          A string that does not contain only whitespace characters

          Minimum length is 1.

      • required_fields array[object] Required

        Input parameters to create a RequiredField. Does not include the ecs field, because ecs is calculated on the backend based on the field name and type.

        Hide required_fields attributes Show required_fields attributes object
        • name string(nonempty) Required

          A string that does not contain only whitespace characters

          Minimum length is 1.

        • type string(nonempty) Required

          A string that does not contain only whitespace characters

          Minimum length is 1.

      • response_actions array[object]
        One of:
        Security_Detections_API_OsqueryResponseAction object Security_Detections_API_EndpointResponseAction object
        Hide attributes Show attributes
      • risk_score integer Required

        Risk score (0 to 100)

        Minimum value is 0, maximum value is 100.

      • risk_score_mapping array[object] Required

        Overrides generated alerts' risk_score with a value from the source event

        Hide risk_score_mapping attributes Show risk_score_mapping attributes object
      • rule_name_override string

        Sets the source field for the alert's signal.rule.name value

      • setup string Required
      • severity string Required

        Severity of the rule

        Values are low, medium, high, or critical.

      • severity_mapping array[object] Required

        Overrides generated alerts' severity with values from the source event

        Hide severity_mapping attributes Show severity_mapping attributes object
        • field string Required
        • operator string Required

          Value is equals.

        • severity string Required

          Severity of the rule

          Values are low, medium, high, or critical.

        • value string Required
      • tags array[string] Required

        String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.

      • threat array[object] Required
        Hide threat attributes Show threat attributes object
        • framework string Required

          Relevant attack framework

        • tactic object Required
          Hide tactic attributes Show tactic attributes object
          • id string Required

            Tactic ID

          • name string Required

            Tactic name

          • reference string Required

            Tactic reference

        • technique array[object]

          Array containing information on the attack techniques (optional)

          Hide technique attributes Show technique attributes object
          • id string Required

            Technique ID

          • name string Required

            Technique name

          • reference string Required

            Technique reference

          • subtechnique array[object]

            Array containing more specific information on the attack technique

            Hide subtechnique attributes Show subtechnique attributes object
            • id string Required

              Subtechnique ID

            • name string Required

              Subtechnique name

            • reference string Required

              Subtechnique reference

      • throttle string | null

        Time interval in seconds, minutes, hours, or days.

        Format should match the following pattern: ^[1-9]\d*[smhd]$. Values are no_actions or rule.

      • timeline_id string

        Timeline template ID

      • timeline_title string

        Timeline template title

      • timestamp_override string

        Sets the time field used to query indices

      • timestamp_override_fallback_disabled boolean

        Disables the fallback to the event's @timestamp field

      • to string Required
      • version integer Required

        The rule's version number.

        Minimum value is 1.

      • created_at string(date-time) Required
      • created_by string Required
      • execution_summary object
        Hide execution_summary attribute Show execution_summary attribute object
        • last_execution object Required
          Hide last_execution attributes Show last_execution attributes object
          • date string(date-time) Required

            Date of the last execution

          • message string Required
          • metrics object Required
            Hide metrics attributes Show metrics attributes object
          • status string Required

            Status of the last execution

            Values are going to run, running, partial failure, failed, or succeeded.

          • status_order integer Required
      • id string(uuid) Required

        A universally unique identifier

      • immutable boolean Required Deprecated

        This field determines whether the rule is a prebuilt Elastic rule. It will be replaced with the rule_source field.

      • revision integer Required

        Minimum value is 0.

      • rule_id string Required

        Could be any string, not necessarily a UUID

      • rule_source object Required

        Type of rule source for internally sourced rules, i.e. created within the Kibana apps.

        Hide rule_source attributes Show rule_source attributes object
        • is_customized boolean Required

          Determines whether an external/prebuilt rule has been customized by the user (i.e. any of its fields have been modified and diverged from the base value).

        • type string Required Discriminator

          Value is external.

      • updated_at string(date-time) Required
      • updated_by string Required
      • language string Required

        Query language to use

        Value is eql.

      • query string Required

        EQL query to execute

      • type string Required Discriminator

        Rule type

        Value is eql.

      • alert_suppression object
        Hide alert_suppression attributes Show alert_suppression attributes object
        • duration object
          Hide duration attributes Show duration attributes object
          • unit string Required

            Values are s, m, or h.

          • value integer Required

            Minimum value is 1.

        • group_by array[string] Required

          At least 1 but not more than 3 elements.

        • missing_fields_strategy string

          Describes how alerts will be generated for documents with missing suppress by fields: doNotSuppress - per each document a separate alert will be created suppress - only alert will be created per suppress by bucket

          Values are doNotSuppress or suppress.

      • data_view_id string
      • event_category_override string
      • filters array
      • index array[string]
      • tiebreaker_field string

        Sets a secondary field for sorting events

      • timestamp_field string

        Contains the event timestamp used for sorting a sequence of events

    • page integer Required
    • perPage integer Required
    • total integer Required
GET /api/detection_engine/rules/_find 
curl \
 --request GET 'http://localhost:5622/api/detection_engine/rules/_find' \
 --header "Authorization: $API_KEY"
Response examples (200) 
{
  "data": [
    {
      "actions": [
        {
          "action_type_id": "string",
          "alerts_filter": {},
          "frequency": {
            "notifyWhen": "onActiveAlert",
            "summary": true,
            "throttle": "no_actions"
          },
          "group": "string",
          "id": "string",
          "params": {},
          "uuid": "string"
        }
      ],
      "alias_purpose": "savedObjectConversion",
      "alias_target_id": "string",
      "author": [
        "string"
      ],
      "building_block_type": "string",
      "description": "string",
      "enabled": true,
      "exceptions_list": [
        {
          "id": "string",
          "list_id": "string",
          "namespace_type": "agnostic",
          "type": "detection"
        }
      ],
      "false_positives": [
        "string"
      ],
      "from": "string",
      "interval": "string",
      "investigation_fields": {
        "field_names": [
          "string"
        ]
      },
      "license": "string",
      "max_signals": 42,
      "meta": {},
      "name": "string",
      "namespace": "string",
      "note": "string",
      "outcome": "exactMatch",
      "output_index": "string",
      "references": [
        "string"
      ],
      "related_integrations": [
        {
          "integration": "string",
          "package": "string",
          "version": "string"
        }
      ],
      "required_fields": [
        {
          "name": "string",
          "type": "string"
        }
      ],
      "response_actions": [
        {
          "action_type_id": ".osquery",
          "params": {
            "ecs_mapping": {
              "additionalProperty1": {
                "field": "string",
                "value": "string"
              },
              "additionalProperty2": {
                "field": "string",
                "value": "string"
              }
            },
            "pack_id": "string",
            "queries": [
              {
                "ecs_mapping": {
                  "additionalProperty1": {
                    "field": "string",
                    "value": "string"
                  },
                  "additionalProperty2": {
                    "field": "string",
                    "value": "string"
                  }
                },
                "id": "string",
                "platform": "string",
                "query": "string",
                "removed": true,
                "snapshot": true,
                "version": "string"
              }
            ],
            "query": "string",
            "saved_query_id": "string",
            "timeout": 42.0
          }
        }
      ],
      "risk_score": 42,
      "risk_score_mapping": [
        {
          "field": "string",
          "operator": "equals",
          "risk_score": 42,
          "value": "string"
        }
      ],
      "rule_name_override": "string",
      "setup": "string",
      "severity": "low",
      "severity_mapping": [
        {
          "field": "string",
          "operator": "equals",
          "severity": "low",
          "value": "string"
        }
      ],
      "tags": [
        "string"
      ],
      "threat": [
        {
          "framework": "string",
          "tactic": {
            "id": "string",
            "name": "string",
            "reference": "string"
          },
          "technique": [
            {
              "id": "string",
              "name": "string",
              "reference": "string",
              "subtechnique": [
                {
                  "id": "string",
                  "name": "string",
                  "reference": "string"
                }
              ]
            }
          ]
        }
      ],
      "throttle": "1h",
      "timeline_id": "string",
      "timeline_title": "string",
      "timestamp_override": "string",
      "timestamp_override_fallback_disabled": true,
      "to": "string",
      "version": 42,
      "created_at": "2025-05-04T09:42:00Z",
      "created_by": "string",
      "execution_summary": {
        "last_execution": {
          "date": "2025-05-04T09:42:00Z",
          "message": "string",
          "metrics": {
            "execution_gap_duration_s": 42,
            "total_enrichment_duration_ms": 42,
            "total_indexing_duration_ms": 42,
            "total_search_duration_ms": 42
          },
          "status": "going to run",
          "status_order": 42
        }
      },
      "id": "string",
      "immutable": true,
      "revision": 42,
      "rule_id": "string",
      "rule_source": {
        "is_customized": true,
        "type": "external"
      },
      "updated_at": "2025-05-04T09:42:00Z",
      "updated_by": "string",
      "language": "eql",
      "query": "string",
      "type": "eql",
      "alert_suppression": {
        "duration": {
          "unit": "s",
          "value": 42
        },
        "group_by": [
          "string"
        ],
        "missing_fields_strategy": "doNotSuppress"
      },
      "data_view_id": "string",
      "event_category_override": "string",
      "filters": [],
      "index": [
        "string"
      ],
      "tiebreaker_field": "string",
      "timestamp_field": "string"
    }
  ],
  "page": 42,
  "perPage": 42,
  "total": 42
}

Get exception lists

GET /api/exception_lists/_find
Api key auth Basic auth

Get a list of all exception list containers.

Query parameters

  • filter string

    Filters the returned results according to the value of the specified field.

    Uses the so type.field name:field value syntax, where so type can be:

    • exception-list: Specify a space-aware exception list.
    • exception-list-agnostic: Specify an exception list that is shared across spaces.
  • namespace_type array[string]

    Determines whether the returned containers are Kibana associated with a Kibana space or available in all spaces (agnostic or single)

    Values are agnostic or single. Default value is ["single"].

  • page integer

    The page number to return

    Minimum value is 1.

  • per_page integer

    The number of exception lists to return per page

    Minimum value is 1.

  • sort_field string

    Determines which field is used to sort the results.

  • sort_order string

    Determines the sort order, which can be desc or asc.

    Values are desc or asc.

Responses

  • 200 application/json; Elastic-Api-Version=2023-10-31

    Successful response

    Hide response attributes Show response attributes object
    • data array[object] Required
      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.

      • 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

        Exception list's human readable string identifier, e.g. trusted-linux-processes.

        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.

    • page integer Required

      Minimum value is 1.

    • per_page integer Required

      Minimum value is 1.

    • total integer Required

      Minimum value is 0.
  • 400 application/json; Elastic-Api-Version=2023-10-31

    Invalid input data response

    One of:
    Security_Exceptions_API_PlatformErrorResponse object Security_Exceptions_API_SiemErrorResponse object
    Hide attributes Show attributes
  • 401 application/json; Elastic-Api-Version=2023-10-31

    Unsuccessful authentication response

    Hide response attributes Show response attributes object
  • 403 application/json; Elastic-Api-Version=2023-10-31

    Not enough privileges response

    Hide response attributes Show response attributes object
  • 500 application/json; Elastic-Api-Version=2023-10-31

    Internal server error response

    Hide response attributes Show response attributes object
GET /api/exception_lists/_find 
curl \
 --request GET 'http://localhost:5622/api/exception_lists/_find' \
 --header "Authorization: $API_KEY"
Response examples (200) 
{
  "data": [
    {
      "id": "9e5fc75a-a3da-46c5-96e3-a2ec59c6bb85",
      "name": "Detection Exception List",
      "tags": [
        "malware"
      ],
      "type": "detection",
      "list_id": "simple_list",
      "version": 1,
      "_version": "WzIsMV0=",
      "os_types": [],
      "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"
    }
  ],
  "page": 1,
  "total": 1,
  "per_page": 20
}
Response examples (400) 
{
  "error": "Bad Request",
  "message": "[request query]: namespace_type.0: Invalid enum value. Expected 'agnostic' | 'single', received 'blob'",
  "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 [GET /api/exception_lists/_find?namespace_type=single] is unauthorized for user, this action is granted by the Kibana privileges [lists-read]",
  "statusCode": 403
}
Response examples (500) 
{
  "message": "Internal Server Error",
  "status_code": 500
}

Create list data streams

POST /api/lists/index
Api key auth Basic auth

Create .lists and .items data streams in the relevant space.

Responses

POST /api/lists/index 
curl \
 --request POST 'http://localhost:5622/api/lists/index' \
 --header "Authorization: $API_KEY"
Response examples (200) 
{
  "acknowledged": true
}
Response examples (400) 
{
  "error": "string",
  "message": "string",
  "statusCode": 42
}
{
  "message": "string",
  "status_code": 42
}
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]\n",
  "statusCode": 401
}
Response examples (403) 
{
  "error": "string",
  "message": "string",
  "statusCode": 42
}
Response examples (409) 
{
  "message": "data stream: \\\".lists-default\\\" and \\\".items-default\\\" already exists",
  "status_code": 409
}
Response examples (500) 
{
  "message": "Internal Server Error",
  "status_code": 500
}