Import detection rules

Base URL
https://{kibana_url}
  • POST /api/detection_engine/rules/_import
  • POST /s/{space_id}/api/detection_engine/rules/_import
Auth

Import detection rules from an .ndjson file, including actions and exception lists. The request must include:

  • The Content-Type: multipart/form-data HTTP header.
  • A link to the .ndjson file containing the rules.
Warning

When used with API key authentication, the user's key gets assigned to the affected rules. If the user's key gets deleted or the user becomes inactive, the rules will stop running.

If the API key that is used for authorization has different privileges than the key that created or most recently updated the rule, the rule behavior might change.

Note

To import rules with actions, you need at least Read privileges for the Action and Connectors feature. To overwrite or add new connectors, you need All privileges for the Actions and Connectors feature. To import rules without actions, you don’t need Actions and Connectors privileges. Refer to Enable and access detections for more information.

Note

Rule actions and connectors are included in the exported file, but sensitive information about the connector (such as authentication credentials) is not included. You must re-add missing connector details after importing detection rules.

You can use Kibana’s Saved Objects UI (Stack Management → Kibana → Saved Objects) or the Saved Objects APIs (experimental) to export and import any necessary connectors before importing detection rules.

Similarly, any value lists used for rule exceptions are not included in rule exports or imports. Use the Manage value lists UI (Rules → Detection rules (SIEM) → Manage value lists) to export and import value lists separately.

Path parameters

space_id string optional

An identifier for the space. If space_id is not provided in the URL, the default space is used. Refer to Spaces for more information.

Query parameters

overwrite boolean · default: false

Determines whether existing rules with the same rule_id are overwritten.

overwrite_exceptions boolean · default: false

Determines whether existing exception lists with the same list_id are overwritten. Both the exception list container and its items are overwritten.

overwrite_action_connectors boolean · default: false

Determines whether existing actions with the same kibana.alert.rule.actions.id are overwritten.

as_new_list boolean · default: false

Generates a new list ID for each imported exception list.

Request body

file string · format: binary

The .ndjson file containing the rules.

Response

Indicates a successful call.

application/json
action_connectors_errors object[] required
error object required
message string required
status_code integer · min: 400 required
id string
item_id string · min length: 1
list_id string · min length: 1
rule_id string

A stable unique identifier for the rule object. It can be assigned during rule creation. It can be any string, but often is a UUID. It should be unique not only within a given Kibana space, but also across spaces and Elastic environments. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have the same rule_ids.

action_connectors_success boolean required
action_connectors_success_count integer · min: 0 required
action_connectors_warnings object[] required
actionPath string required
buttonLabel string
message string required
type string required
errors object[] required
error object required
message string required
status_code integer · min: 400 required
id string
item_id string · min length: 1
list_id string · min length: 1
rule_id string

A stable unique identifier for the rule object. It can be assigned during rule creation. It can be any string, but often is a UUID. It should be unique not only within a given Kibana space, but also across spaces and Elastic environments. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have the same rule_ids.

exceptions_errors object[] required
error object required
message string required
status_code integer · min: 400 required
id string
item_id string · min length: 1
list_id string · min length: 1
rule_id string

A stable unique identifier for the rule object. It can be assigned during rule creation. It can be any string, but often is a UUID. It should be unique not only within a given Kibana space, but also across spaces and Elastic environments. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have the same rule_ids.

exceptions_success boolean required
exceptions_success_count integer · min: 0 required
rules_count integer · min: 0 required
success boolean required
success_count integer · min: 0 required
Base URL
https://{kibana_url}