Get a package signature verification key ID

Create a rule

POST /api/alerting/rule/{id}

Api key auth Basic auth

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Path parameters

id string Required

The identifier for the rule. If it is omitted, an ID is randomly generated.

application/json

Body

actions array[object]

An action that runs under defined conditions.

Default value is [] (empty).
Hide actions attributes Show actions attributes object
- alerts_filter object
  
  Conditions that affect whether the action runs. If you specify multiple conditions, all conditions must be met for the action to run. For example, if an alert occurs within the specified time frame and matches the query, the action runs.
  
  Additional properties are NOT allowed.
  Hide alerts_filter attributes Show alerts_filter attributes object
  
  query object
  
  Additional properties are NOT allowed.
  
  Hide query attributes Show query attributes object
  
  dsl string
  
  A filter written in Elasticsearch Query Domain Specific Language (DSL).
  
  filters array[object] Required
  
  A filter written in Elasticsearch Query Domain Specific Language (DSL) as defined in the kbn-es-query package.
  
  Hide filters attributes Show filters attributes object
  
  $state object
  
  Additional properties are NOT allowed.
  
  Hide $state attribute Show $state attribute object
  
  store string Required
  
  A filter can be either specific to an application context or applied globally.
  
  Values are appState or globalState.
  
  meta object Required
  
  Additional properties are allowed.
  
  query object
  
  Additional properties are allowed.
  
  kql string Required
  
  A filter written in Kibana Query Language (KQL).
  
  timeframe object
  
  Defines a period that limits whether the action runs.
  
  Additional properties are NOT allowed.
  
  Hide timeframe attributes Show timeframe attributes object
  
  days array[integer] Required
  
  Defines the days of the week that the action can run, represented as an array of numbers. For example, 1 represents Monday. An empty array is equivalent to specifying all the days of the week.
  
  Values are 1, 2, 3, 4, 5, 6, or 7.
  
  hours object Required
  
  Defines the range of time in a day that the action can run. If the start value is 00:00 and the end value is 24:00, actions be generated all day.
  
  Additional properties are NOT allowed.
  
  Hide hours attributes Show hours attributes object
  
  end string Required
  
  The end of the time frame in 24-hour notation (hh:mm).
  
  start string Required
  
  The start of the time frame in 24-hour notation (hh:mm).
  
  timezone string Required
  
  The ISO time zone for the hours values. Values such as UTC and UTC+1 also work but lack built-in daylight savings time support and are not recommended.
- frequency object
  
  Additional properties are NOT allowed.
  Hide frequency attributes Show frequency attributes object
  
  notify_when string Required
  
  Indicates how often alerts generate actions. Valid values include: onActionGroupChange: Actions run when the alert status changes; onActiveAlert: Actions run when the alert becomes active and at each check interval while the rule conditions are met; onThrottleInterval: Actions run when the alert becomes active and at the interval specified in the throttle property while the rule conditions are met. NOTE: You cannot specify notify_when at both the rule and action level. The recommended method is to set it for each action. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values.
  
  Values are onActionGroupChange, onActiveAlert, or onThrottleInterval.
  
  summary boolean Required
  
  Indicates whether the action is a summary.
  
  throttle string | null Required
  
  The throttle interval, which defines how often an alert generates repeated actions. It is specified in seconds, minutes, hours, or days and is applicable only if notify_when is set to onThrottleInterval. NOTE: You cannot specify the throttle interval at both the rule and action level. The recommended method is to set it for each action. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values.
- group string
  
  The group name, which affects when the action runs (for example, when the threshold is met or when the alert is recovered). Each rule type has a list of valid action group names. If you don't need to group actions, set to default.
- id string Required
  
  The identifier for the connector saved object.
- params object
  
  The parameters for the action, which are sent to the connector. The params are handled as Mustache templates and passed a default set of context.
  
  Default value is {} (empty). Additional properties are allowed.
- use_alert_data_for_template boolean
  
  Indicates whether to use alert data as a template.
- uuid string
  
  A universally unique identifier (UUID) for the action.
alert_delay object

Indicates that an alert occurs only when the specified number of consecutive runs met the rule conditions.

Additional properties are NOT allowed.
Hide alert_delay attribute Show alert_delay attribute object
- active number Required
  
  The number of consecutive runs that must meet the rule conditions.
consumer string Required

The name of the application or feature that owns the rule. For example: alerts, apm, discover, infrastructure, logs, metrics, ml, monitoring, securitySolution, siem, stackAlerts, or uptime.
enabled boolean

Indicates whether you want to run the rule on an interval basis after it is created.

Default value is true.
flapping object | null

When flapping detection is turned on, alerts that switch quickly between active and recovered states are identified as “flapping” and notifications are reduced.

Additional properties are NOT allowed.
Hide flapping attributes Show flapping attributes object | null
- look_back_window number Required
  
  The minimum number of runs in which the threshold must be met.
  
  Minimum value is 2, maximum value is 20.
- status_change_threshold number Required
  
  The minimum number of times an alert must switch states in the look back window.
  
  Minimum value is 2, maximum value is 20.
name string Required

The name of the rule. While this name does not have to be unique, a distinctive name can help you identify a rule.
notify_when string | null

Indicates how often alerts generate actions. Valid values include: onActionGroupChange: Actions run when the alert status changes; onActiveAlert: Actions run when the alert becomes active and at each check interval while the rule conditions are met; onThrottleInterval: Actions run when the alert becomes active and at the interval specified in the throttle property while the rule conditions are met. NOTE: You cannot specify notify_when at both the rule and action level. The recommended method is to set it for each action. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values.

Values are onActionGroupChange, onActiveAlert, or onThrottleInterval.
rule_type_id string Required

The rule type identifier.
schedule object Required

The check interval, which specifies how frequently the rule conditions are checked.

Additional properties are NOT allowed.
Hide schedule attribute Show schedule attribute object
- interval string Required
  
  The interval is specified in seconds, minutes, hours, or days.
tags array[string]

The tags for the rule.

Default value is [] (empty).
throttle string | null

Use the throttle property in the action frequency object instead. The throttle interval, which defines how often an alert generates repeated actions. NOTE: You cannot specify the throttle interval at both the rule and action level. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values.
params object

The parameters for the rule.
Any of:
params_property_apm_anomaly object params_property_apm_error_count object params_property_apm_transaction_duration object params_property_apm_transaction_error_rate object params_es_query_dsl_rule object params_es_query_esql_rule object params_es_query_kql_rule object params_index_threshold_rule object params_property_infra_inventory object Count object Ratio object params_property_infra_metric_threshold object params_property_slo_burn_rate object params_property_synthetics_uptime_tls object params_property_synthetics_monitor_status object
Hide attributes Show attributes

serviceName string

Filter the rule to apply to a specific service name.

transactionType string

Filter the rule to apply to a specific transaction type.

windowSize number Required

The size of the time window (in windowUnit units), which determines how far back to search for documents. Generally it should be a value higher than the rule check interval to avoid gaps in detection.

windowUnit string Required

The type of units for the time window. For example: minutes, hours, or days.

Values are m, h, or d.

environment string Required

Filter the rule to apply to a specific environment.

anomalySeverityType string Required

The severity of anomalies that will generate alerts: critical, major, minor, or warning.

Values are critical, major, minor, or warning.
Hide attributes Show attributes

serviceName string

Filter the errors coming from your application to apply the rule to a specific service.

windowSize number Required

The time frame in which the errors must occur (in windowUnit units). Generally it should be a value higher than the rule check interval to avoid gaps in detection.

windowUnit string Required

The type of units for the time window: minutes, hours, or days.

Values are m, h, or d.

environment string Required

Filter the errors coming from your application to apply the rule to a specific environment.

threshold number Required

The error count threshold.

groupBy array[string]

Perform a composite aggregation against the selected fields. When any of these groups match the selected rule conditions, an alert is triggered per group.

Values are service.name, service.environment, transaction.name, or error.grouping_key. Default value is ["service.name", "service.environment"].

errorGroupingKey string

Filter the errors coming from your application to apply the rule to a specific error grouping key, which is a hash of the stack trace and other properties.
Hide attributes Show attributes

serviceName string

Filter the rule to apply to a specific service.

transactionType string

Filter the rule to apply to a specific transaction type.

transactionName string

Filter the rule to apply to a specific transaction name.

windowSize number Required

The size of the time window (in windowUnit units), which determines how far back to search for documents. Generally it should be a value higher than the rule check interval to avoid gaps in detection.

windowUnit string Required

The type of units for the time window. For example: minutes, hours, or days.

Values are m, h, or d.

environment string Required

Filter the rule to apply to a specific environment.

threshold number Required

The latency threshold value.

groupBy array[string]

Perform a composite aggregation against the selected fields. When any of these groups match the selected rule conditions, an alert is triggered per group.

Values are service.name, service.environment, transaction.type, or transaction.name. Default value is ["service.name", "service.environment", "transaction.type"].

aggregationType string Required

The type of aggregation to perform.

Values are avg, 95th, or 99th.
Hide attributes Show attributes

serviceName string

The service name from APM

transactionType string

The transaction type from APM

transactionName string

The transaction name from APM

windowSize number Required

The window size

windowUnit string Required

The window size unit

Values are m, h, or d.

environment string Required

The environment from APM

threshold number Required

The error rate threshold value

groupBy array[string]

Values are service.name, service.environment, transaction.type, or transaction.name. Default value is ["service.name", "service.environment", "transaction.type"].
An Elasticsearch query rule can run a query defined in Elasticsearch Query DSL and compare the number of matches to a configured threshold. These parameters are appropriate when rule_type_id is .es-query.
Hide attributes Show attributes

aggField string

The name of the numeric field that is used in the aggregation. This property is required when aggType is avg, max, min or sum.

aggType string

The type of aggregation to perform.

Values are avg, count, max, min, or sum. Default value is count.

esQuery string Required

The query definition, which uses Elasticsearch Query DSL.

excludeHitsFromPreviousRun boolean

Indicates whether to exclude matches from previous runs. If true, you can avoid alert duplication by excluding documents that have already been detected by the previous rule run. This option is not available when a grouping field is specified.

groupBy string

Indicates whether the aggregation is applied over all documents (all) or split into groups (top) using a grouping field (termField). If grouping is used, an alert will be created for each group when it exceeds the threshold; only the top groups (up to termSize number of groups) are checked.

Values are all or top. Default value is all.

index array[string] | string Required

The indices to query.

One of:
array-1 array[string] string-2 string

searchType string

The type of query, in this case a query that uses Elasticsearch Query DSL.

Value is esQuery. Default value is esQuery.

size integer

The number of documents to pass to the configured actions when the threshold condition is met.

termField string | array[string]

The names of up to four fields that are used for grouping the aggregation. This property is required when groupBy is top.

One of:
string-1 string array-2 array[string]

termSize integer

This property is required when groupBy is top. It specifies the number of groups to check against the threshold and therefore limits the number of alerts on high cardinality fields.

threshold array[integer] Required

The threshold value that is used with the thresholdComparator. If the thresholdComparator is between or notBetween, you must specify the boundary values.

thresholdComparator string Required

The comparison function for the threshold. For example, "is above", "is above or equals", "is below", "is below or equals", "is between", and "is not between".

Values are >, >=, <, <=, between, or notBetween.

timeField string Required

The field that is used to calculate the time window.

timeWindowSize integer Required

The size of the time window (in timeWindowUnit units), which determines how far back to search for documents. Generally it should be a value higher than the rule check interval to avoid gaps in detection.

timeWindowUnit string Required

The type of units for the time window: seconds, minutes, hours, or days.

Values are s, m, h, or d.
An Elasticsearch query rule can run an ES|QL query and compare the number of matches to a configured threshold. These parameters are appropriate when rule_type_id is .es-query.
Hide attributes Show attributes

aggField string

The name of the numeric field that is used in the aggregation. This property is required when aggType is avg, max, min or sum.

aggType string

The type of aggregation to perform.

Values are avg, count, max, min, or sum. Default value is count.

esqlQuery object Required

Hide esqlQuery attribute Show esqlQuery attribute object

esql string Required

The query definition, which uses Elasticsearch Query Language.

excludeHitsFromPreviousRun boolean

Indicates whether to exclude matches from previous runs. If true, you can avoid alert duplication by excluding documents that have already been detected by the previous rule run. This option is not available when a grouping field is specified.

groupBy string

Indicates whether the aggregation is applied over all documents (all) or split into groups (top) using a grouping field (termField). If grouping is used, an alert will be created for each group when it exceeds the threshold; only the top groups (up to termSize number of groups) are checked.

Values are all or top. Default value is all.

searchType string Required

The type of query, in this case a query that uses Elasticsearch Query Language (ES|QL).

Value is esqlQuery.

size integer Required

When searchType is esqlQuery, this property is required but it does not affect the rule behavior.

termSize integer

This property is required when groupBy is top. It specifies the number of groups to check against the threshold and therefore limits the number of alerts on high cardinality fields.

threshold array[integer] Required

The threshold value that is used with the thresholdComparator. When searchType is esqlQuery, this property is required and must be set to zero.

Minimum value of each is 0, maximum value of each is 0.

thresholdComparator string Required

The comparison function for the threshold. When searchType is esqlQuery, this property is required and must be set to ">". Since the threshold value must be 0, the result is that an alert occurs whenever the query returns results.

Value is >.

timeField string

The field that is used to calculate the time window.

timeWindowSize integer Required

The size of the time window (in timeWindowUnit units), which determines how far back to search for documents. Generally it should be a value higher than the rule check interval to avoid gaps in detection.

timeWindowUnit string Required

The type of units for the time window: seconds, minutes, hours, or days.

Values are s, m, h, or d.
An Elasticsearch query rule can run a query defined in KQL or Lucene and compare the number of matches to a configured threshold. These parameters are appropriate when rule_type_id is .es-query.
Hide attributes Show attributes

aggField string

The name of the numeric field that is used in the aggregation. This property is required when aggType is avg, max, min or sum.

aggType string

The type of aggregation to perform.

Values are avg, count, max, min, or sum. Default value is count.

excludeHitsFromPreviousRun boolean

Indicates whether to exclude matches from previous runs. If true, you can avoid alert duplication by excluding documents that have already been detected by the previous rule run. This option is not available when a grouping field is specified.

groupBy string

Indicates whether the aggregation is applied over all documents (all) or split into groups (top) using a grouping field (termField). If grouping is used, an alert will be created for each group when it exceeds the threshold; only the top groups (up to termSize number of groups) are checked.

Values are all or top. Default value is all.

searchConfiguration object

The query definition, which uses KQL or Lucene to fetch the documents from Elasticsearch.

Hide searchConfiguration attributes Show searchConfiguration attributes object

filter array[object]

A filter written in Elasticsearch Query Domain Specific Language (DSL) as defined in the kbn-es-query package.

Hide filter attributes Show filter attributes object

meta object

Hide meta attributes Show meta attributes object

alias string | null

controlledBy string

disabled boolean

field string

group string

index string

isMultiIndex boolean

key string

negate boolean

params object

type string

value string

query object

$state object

index string | array[string]

The indices to query.

One of:
string-1 string array-2 array[string]

query object

Hide query attributes Show query attributes object

language string

query string

searchType string Required

The type of query, in this case a text-based query that uses KQL or Lucene.

Value is searchSource.

size integer Required

The number of documents to pass to the configured actions when the threshold condition is met.

termField string | array[string]

The names of up to four fields that are used for grouping the aggregation. This property is required when groupBy is top.

One of:
string-1 string array-2 array[string]

termSize integer

This property is required when groupBy is top. It specifies the number of groups to check against the threshold and therefore limits the number of alerts on high cardinality fields.

threshold array[integer] Required

The threshold value that is used with the thresholdComparator. If the thresholdComparator is between or notBetween, you must specify the boundary values.

thresholdComparator string Required

The comparison function for the threshold. For example, "is above", "is above or equals", "is below", "is below or equals", "is between", and "is not between".

Values are >, >=, <, <=, between, or notBetween.

timeField string

The field that is used to calculate the time window.

timeWindowSize integer Required

The size of the time window (in timeWindowUnit units), which determines how far back to search for documents. Generally it should be a value higher than the rule check interval to avoid gaps in detection.

timeWindowUnit string Required

The type of units for the time window: seconds, minutes, hours, or days.

Values are s, m, h, or d.
An index threshold rule runs an Elasticsearch query, aggregates field values from documents, compares them to threshold values, and schedules actions to run when the thresholds are met. These parameters are appropriate when rule_type_id is .index-threshold.
Hide attributes Show attributes

aggField string

The name of the numeric field that is used in the aggregation. This property is required when aggType is avg, max, min or sum.

aggType string

The type of aggregation to perform.

Values are avg, count, max, min, or sum. Default value is count.

filterKuery string

A KQL expression thats limits the scope of alerts.

groupBy string

Indicates whether the aggregation is applied over all documents (all) or split into groups (top) using a grouping field (termField). If grouping is used, an alert will be created for each group when it exceeds the threshold; only the top groups (up to termSize number of groups) are checked.

Values are all or top. Default value is all.

index array[string] Required

The indices to query.

termField string | array[string]

The names of up to four fields that are used for grouping the aggregation. This property is required when groupBy is top.

One of:
string-1 string array-2 array[string]

termSize integer

This property is required when groupBy is top. It specifies the number of groups to check against the threshold and therefore limits the number of alerts on high cardinality fields.

threshold array[integer] Required

The threshold value that is used with the thresholdComparator. If the thresholdComparator is between or notBetween, you must specify the boundary values.

thresholdComparator string Required

The comparison function for the threshold. For example, "is above", "is above or equals", "is below", "is below or equals", "is between", and "is not between".

Values are >, >=, <, <=, between, or notBetween.

timeField string Required

The field that is used to calculate the time window.

timeWindowSize integer Required

The size of the time window (in timeWindowUnit units), which determines how far back to search for documents. Generally it should be a value higher than the rule check interval to avoid gaps in detection.

timeWindowUnit string Required

The type of units for the time window: seconds, minutes, hours, or days.

Values are s, m, h, or d.
Hide attributes Show attributes

criteria array[object]

Hide criteria attributes Show criteria attributes object

metric string

Values are count, cpu, diskLatency, load, memory, memoryTotal, tx, rx, logRate, diskIOReadBytes, diskIOWriteBytes, s3TotalRequests, s3NumberOfObjects, s3BucketSize, s3DownloadBytes, s3UploadBytes, rdsConnections, rdsQueriesExecuted, rdsActiveTransactions, rdsLatency, sqsMessagesVisible, sqsMessagesDelayed, sqsMessagesSent, sqsMessagesEmpty, sqsOldestMessage, or custom.

timeSize number

timeUnit string

Values are s, m, h, or d.

sourceId string

threshold array[number]

comparator string

Values are <, <=, >, >=, between, or outside.

customMetric object

Hide customMetric attributes Show customMetric attributes object

type string

Value is custom.

field string

aggregation string

Values are avg, max, min, or rate.

id string

label string

warningThreshold array[number]

warningComparator string

Values are <, <=, >, >=, between, or outside.

filterQuery string

filterQueryText string

nodeType string

Values are host, pod, container, awsEC2, awsS3, awsSQS, or awsRDS.

sourceId string

alertOnNoData boolean
Hide attributes Show attributes

criteria array[object]

Hide criteria attributes Show criteria attributes object

field string

comparator string

Values are more than, more than or equals, less than, less than or equals, equals, does not equal, matches, does not match, matches phrase, or does not match phrase.

value number | string

One of:
number-1 number string-2 string

count object Required

Hide count attributes Show count attributes object

comparator string

Values are more than, more than or equals, less than, less than or equals, equals, does not equal, matches, does not match, matches phrase, or does not match phrase.

value number

timeSize number Required

timeUnit string Required

Values are s, m, h, or d.

logView object Required

Hide logView attributes Show logView attributes object

logViewId string

type string

Value is log-view-reference.

groupBy array[string]
Hide attributes Show attributes

criteria array[array]

Hide criteria attributes Show criteria attributes object

field string

comparator string

Values are more than, more than or equals, less than, less than or equals, equals, does not equal, matches, does not match, matches phrase, or does not match phrase.

value number | string

One of:
number-1 number string-2 string

count object Required

Hide count attributes Show count attributes object

comparator string

Values are more than, more than or equals, less than, less than or equals, equals, does not equal, matches, does not match, matches phrase, or does not match phrase.

value number

timeSize number Required

timeUnit string Required

Values are s, m, h, or d.

logView object Required

Hide logView attributes Show logView attributes object

logViewId string

type string

Value is log-view-reference.

groupBy array[string]
Hide attributes Show attributes

criteria array[object]

One of:
non count criterion object count criterion object custom criterion object

Hide attributes Show attributes

threshold array[number]

comparator string

Values are <, <=, >, >=, between, or outside.

timeUnit string

timeSize number

warningThreshold array[number]

warningComparator string

Values are <, <=, >, >=, between, or outside.

metric string

aggType string

Values are avg, max, min, cardinality, rate, count, sum, p95, p99, or custom.

Hide attributes Show attributes

threshold array[number]

comparator string

Values are <, <=, >, >=, between, or outside.

timeUnit string

timeSize number

warningThreshold array[number]

warningComparator string

Values are <, <=, >, >=, between, or outside.

aggType string

Value is count.

Hide attributes Show attributes

threshold array[number]

comparator string

Values are <, <=, >, >=, between, or outside.

timeUnit string

timeSize number

warningThreshold array[number]

warningComparator string

Values are <, <=, >, >=, between, or outside.

aggType string

Value is custom.

customMetric array[object]

One of:
object-1 object object-2 object

Hide attributes Show attributes

name string

aggType string

Values are avg, sum, max, min, or cardinality.

field string

equation string

label string

groupBy string | array[string]

One of:
string-1 string array-2 array[string]

filterQuery string

sourceId string

alertOnNoData boolean

alertOnGroupDisappear boolean
Hide attributes Show attributes

sloId string

The SLO identifier used by the rule

burnRateThreshold number

The burn rate threshold used to trigger the alert

maxBurnRateThreshold number

The maximum burn rate threshold value defined by the SLO error budget

longWindow object

The duration of the long window used to compute the burn rate

Hide longWindow attributes Show longWindow attributes object

value number

The duration value

unit string

The duration unit

shortWindow object

The duration of the short window used to compute the burn rate

Hide shortWindow attributes Show shortWindow attributes object

value number

The duration value

unit string

The duration unit
Hide attributes Show attributes

search string

certExpirationThreshold number

certAgeThreshold number
Hide attributes Show attributes

availability object

Hide availability attributes Show availability attributes object

range number

rangeUnit string

threshold string

filters string | object

One of:
string-1 string object-2 object Deprecated

locations array[string] Deprecated

numTimes number Required

search string

shouldCheckStatus boolean Required

shouldCheckAvailability boolean Required

timerangeCount number

timerangeUnit string

timerange object Deprecated

Hide timerange attributes Show timerange attributes object Deprecated

from string

to string

version number

isAutoGenerated boolean

Responses

200 application/json

Indicates a successful call.
Hide response attributes Show response attributes object
- actions array[object] Required
  
  Hide actions attributes Show actions attributes object
  
  alerts_filter object
  
  Defines a period that limits whether the action runs.
  
  Additional properties are NOT allowed.
  
  Hide alerts_filter attributes Show alerts_filter attributes object
  
  query object
  
  Additional properties are NOT allowed.
  
  Hide query attributes Show query attributes object
  
  dsl string
  
  A filter written in Elasticsearch Query Domain Specific Language (DSL).
  
  filters array[object] Required
  
  A filter written in Elasticsearch Query Domain Specific Language (DSL) as defined in the kbn-es-query package.
  
  Hide filters attributes Show filters attributes object
  
  $state object
  
  Additional properties are NOT allowed.
  
  Hide $state attribute Show $state attribute object
  
  store string Required
  
  A filter can be either specific to an application context or applied globally.
  
  Values are appState or globalState.
  
  meta object Required
  
  Additional properties are allowed.
  
  query object
  
  Additional properties are allowed.
  
  kql string Required
  
  A filter written in Kibana Query Language (KQL).
  
  timeframe object
  
  Additional properties are NOT allowed.
  
  Hide timeframe attributes Show timeframe attributes object
  
  days array[integer] Required
  
  Defines the days of the week that the action can run, represented as an array of numbers. For example, 1 represents Monday. An empty array is equivalent to specifying all the days of the week.
  
  Values are 1, 2, 3, 4, 5, 6, or 7.
  
  hours object Required
  
  Additional properties are NOT allowed.
  
  Hide hours attributes Show hours attributes object
  
  end string Required
  
  The end of the time frame in 24-hour notation (hh:mm).
  
  start string Required
  
  The start of the time frame in 24-hour notation (hh:mm).
  
  timezone string Required
  
  The ISO time zone for the hours values. Values such as UTC and UTC+1 also work but lack built-in daylight savings time support and are not recommended.
  
  connector_type_id string Required
  
  The type of connector. This property appears in responses but cannot be set in requests.
  
  frequency object
  
  Additional properties are NOT allowed.
  
  Hide frequency attributes Show frequency attributes object
  
  notify_when string Required
  
  Indicates how often alerts generate actions. Valid values include: onActionGroupChange: Actions run when the alert status changes; onActiveAlert: Actions run when the alert becomes active and at each check interval while the rule conditions are met; onThrottleInterval: Actions run when the alert becomes active and at the interval specified in the throttle property while the rule conditions are met. NOTE: You cannot specify notify_when at both the rule and action level. The recommended method is to set it for each action. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values.
  
  Values are onActionGroupChange, onActiveAlert, or onThrottleInterval.
  
  summary boolean Required
  
  Indicates whether the action is a summary.
  
  throttle string | null Required
  
  The throttle interval, which defines how often an alert generates repeated actions. It is specified in seconds, minutes, hours, or days and is applicable only if 'notify_when' is set to 'onThrottleInterval'. NOTE: You cannot specify the throttle interval at both the rule and action level. The recommended method is to set it for each action. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values.
  
  group string
  
  The group name, which affects when the action runs (for example, when the threshold is met or when the alert is recovered). Each rule type has a list of valid action group names. If you don't need to group actions, set to default.
  
  id string Required
  
  The identifier for the connector saved object.
  
  params object Required
  
  The parameters for the action, which are sent to the connector. The params are handled as Mustache templates and passed a default set of context.
  
  Additional properties are allowed.
  
  use_alert_data_for_template boolean
  
  Indicates whether to use alert data as a template.
  
  uuid string
  
  A universally unique identifier (UUID) for the action.
- active_snoozes array[string]
  
  List of active snoozes for the rule.
- alert_delay object
  
  Indicates that an alert occurs only when the specified number of consecutive runs met the rule conditions.
  
  Additional properties are NOT allowed.
  
  Hide alert_delay attribute Show alert_delay attribute object
  
  active number Required
  
  The number of consecutive runs that must meet the rule conditions.
- api_key_created_by_user boolean | null
  
  Indicates whether the API key that is associated with the rule was created by the user.
- api_key_owner string | null Required
  
  The owner of the API key that is associated with the rule and used to run background tasks.
- consumer string Required
  
  The name of the application or feature that owns the rule. For example: alerts, apm, discover, infrastructure, logs, metrics, ml, monitoring, securitySolution, siem, stackAlerts, or uptime.
- created_at string Required
  
  The date and time that the rule was created.
- created_by string | null Required
  
  The identifier for the user that created the rule.
- enabled boolean Required
  
  Indicates whether you want to run the rule on an interval basis after it is created.
- execution_status object Required
  
  Additional properties are NOT allowed.
  
  Hide execution_status attributes Show execution_status attributes object
  
  error object
  
  Additional properties are NOT allowed.
  
  Hide error attributes Show error attributes object
  
  message string Required
  
  Error message.
  
  reason string Required
  
  Reason for error.
  
  Values are read, decrypt, execute, unknown, license, timeout, disabled, or validate.
  
  last_duration number
  
  Duration of last execution of the rule.
  
  last_execution_date string Required
  
  The date and time when rule was executed last.
  
  status string Required
  
  Status of rule execution.
  
  Values are ok, active, error, warning, pending, or unknown.
  
  warning object
  
  Additional properties are NOT allowed.
  
  Hide warning attributes Show warning attributes object
  
  message string Required
  
  Warning message.
  
  reason string Required
  
  Reason for warning.
  
  Values are maxExecutableActions, maxAlerts, maxQueuedActions, or ruleExecution.
- flapping object | null
  
  When flapping detection is turned on, alerts that switch quickly between active and recovered states are identified as “flapping” and notifications are reduced.
  
  Additional properties are NOT allowed.
  
  Hide flapping attributes Show flapping attributes object | null
  
  look_back_window number Required
  
  The minimum number of runs in which the threshold must be met.
  
  Minimum value is 2, maximum value is 20.
  
  status_change_threshold number Required
  
  The minimum number of times an alert must switch states in the look back window.
  
  Minimum value is 2, maximum value is 20.
- id string Required
  
  The identifier for the rule.
- is_snoozed_until string | null
  
  The date when the rule will no longer be snoozed.
- last_run object | null
  
  Additional properties are NOT allowed.
  
  Hide last_run attributes Show last_run attributes object | null
  
  alerts_count object Required
  
  Additional properties are NOT allowed.
  
  Hide alerts_count attributes Show alerts_count attributes object
  
  active number | null
  
  Number of active alerts during last run.
  
  ignored number | null
  
  Number of ignored alerts during last run.
  
  new number | null
  
  Number of new alerts during last run.
  
  recovered number | null
  
  Number of recovered alerts during last run.
  
  outcome string Required
  
  Outcome of last run of the rule. Value could be succeeded, warning or failed.
  
  Values are succeeded, warning, or failed.
  
  outcome_msg array[string] | null
  
  Outcome message generated during last rule run.
  
  outcome_order number
  
  Order of the outcome.
  
  warning string | null
  
  Warning of last rule execution.
  
  Values are read, decrypt, execute, unknown, license, timeout, disabled, validate, maxExecutableActions, maxAlerts, maxQueuedActions, or ruleExecution.
- mapped_params object
  
  Additional properties are allowed.
- monitoring object
  
  Monitoring details of the rule.
  
  Additional properties are NOT allowed.
  
  Hide monitoring attribute Show monitoring attribute object
  
  run object Required
  
  Rule run details.
  
  Additional properties are NOT allowed.
  
  Hide run attributes Show run attributes object
  
  calculated_metrics object Required
  
  Calculation of different percentiles and success ratio.
  
  Additional properties are NOT allowed.
  
  Hide calculated_metrics attributes Show calculated_metrics attributes object
  
  p50 number
  
  p95 number
  
  p99 number
  
  success_ratio number Required
  
  history array[object] Required
  
  History of the rule run.
  
  Hide history attributes Show history attributes object
  
  duration number
  
  Duration of the rule run.
  
  outcome string
  
  Outcome of last run of the rule. Value could be succeeded, warning or failed.
  
  Values are succeeded, warning, or failed.
  
  success boolean Required
  
  Indicates whether the rule run was successful.
  
  timestamp number Required
  
  Time of rule run.
  
  last_run object Required
  
  Additional properties are NOT allowed.
  
  Hide last_run attributes Show last_run attributes object
  
  metrics object Required
  
  Additional properties are NOT allowed.
  
  Hide metrics attributes Show metrics attributes object
  
  duration number
  
  Duration of most recent rule run.
  
  gap_duration_s number | null
  
  Duration in seconds of rule run gap.
  
  gap_range object | null
  
  Additional properties are NOT allowed.
  
  Hide gap_range attributes Show gap_range attributes object | null
  
  gte string Required
  
  End of the gap range.
  
  lte string Required
  
  Start of the gap range.
  
  total_alerts_created number | null
  
  Total number of alerts created during last rule run.
  
  total_alerts_detected number | null
  
  Total number of alerts detected during last rule run.
  
  total_indexing_duration_ms number | null
  
  Total time spent indexing documents during last rule run in milliseconds.
  
  total_search_duration_ms number | null
  
  Total time spent performing Elasticsearch searches as measured by Kibana; includes network latency and time spent serializing or deserializing the request and response.
  
  timestamp string Required
  
  Time of the most recent rule run.
- mute_all boolean Required
  
  Indicates whether all alerts are muted.
- muted_alert_ids array[string] Required
  
  List of identifiers of muted alerts.
- name string Required
  
  The name of the rule.
- next_run string | null
  
  Date and time of the next run of the rule.
- notify_when string | null
  
  Indicates how often alerts generate actions. Valid values include: onActionGroupChange: Actions run when the alert status changes; onActiveAlert: Actions run when the alert becomes active and at each check interval while the rule conditions are met; onThrottleInterval: Actions run when the alert becomes active and at the interval specified in the throttle property while the rule conditions are met. NOTE: You cannot specify notify_when at both the rule and action level. The recommended method is to set it for each action. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values.
  
  Values are onActionGroupChange, onActiveAlert, or onThrottleInterval.
- params object Required
  
  The parameters for the rule.
  
  Additional properties are allowed.
- revision number Required
  
  The rule revision number.
- rule_type_id string Required
  
  The rule type identifier.
- running boolean | null
  
  Indicates whether the rule is running.
- schedule object Required
  
  Additional properties are NOT allowed.
  
  Hide schedule attribute Show schedule attribute object
  
  interval string Required
  
  The interval is specified in seconds, minutes, hours, or days.
- scheduled_task_id string
  
  Identifier of the scheduled task.
- snooze_schedule array[object]
  
  Hide snooze_schedule attributes Show snooze_schedule attributes object
  
  duration number Required
  
  Duration of the rule snooze schedule.
  
  id string
  
  Identifier of the rule snooze schedule.
  
  rRule object Required
  
  Additional properties are NOT allowed.
  
  Hide rRule attributes Show rRule attributes object
  
  byhour array[number] | null
  
  Indicates hours of the day to recur.
  
  byminute array[number] | null
  
  Indicates minutes of the hour to recur.
  
  bymonth array[number] | null
  
  Indicates months of the year that this rule should recur.
  
  bymonthday array[number] | null
  
  Indicates the days of the month to recur.
  
  bysecond array[number] | null
  
  Indicates seconds of the day to recur.
  
  bysetpos array[number] | null
  
  A positive or negative integer affecting the nth day of the month. For example, -2 combined with byweekday of FR is 2nd to last Friday of the month. It is recommended to not set this manually and just use byweekday.
  
  byweekday array[string | number] | null
  
  Indicates the days of the week to recur or else nth-day-of-month strings. For example, "+2TU" second Tuesday of month, "-1FR" last Friday of the month, which are internally converted to a byweekday/bysetpos combination.
  
  byweekno array[number] | null
  
  Indicates number of the week hours to recur.
  
  byyearday array[number] | null
  
  Indicates the days of the year that this rule should recur.
  
  count number
  
  Number of times the rule should recur until it stops.
  
  dtstart string Required
  
  Rule start date in Coordinated Universal Time (UTC).
  
  freq integer
  
  Indicates frequency of the rule. Options are YEARLY, MONTHLY, WEEKLY, DAILY.
  
  Values are 0, 1, 2, 3, 4, 5, or 6.
  
  interval number
  
  Indicates the interval of frequency. For example, 1 and YEARLY is every 1 year, 2 and WEEKLY is every 2 weeks.
  
  tzid string Required
  
  Indicates timezone abbreviation.
  
  until string
  
  Recur the rule until this date.
  
  wkst string
  
  Indicates the start of week, defaults to Monday.
  
  Values are MO, TU, WE, TH, FR, SA, or SU.
  
  skipRecurrences array[string]
  
  Skips recurrence of rule on this date.
- tags array[string] Required
  
  The tags for the rule.
- throttle string | null Deprecated
  
  Deprecated in 8.13.0. Use the throttle property in the action frequency object instead. The throttle interval, which defines how often an alert generates repeated actions. NOTE: You cannot specify the throttle interval at both the rule and action level. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values.
- updated_at string Required
  
  The date and time that the rule was updated most recently.
- updated_by string | null Required
  
  The identifier for the user that updated this rule most recently.
- view_in_app_relative_url string | null
  
  Relative URL to view rule in the app.
400

Indicates an invalid schema or parameters.
403

Indicates that this call is forbidden.
409

Indicates that the rule id is already in use.

POST /api/alerting/rule/{id}

curl \
 --request POST 'https://localhost:5601/api/alerting/rule/{id}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"name":"my Elasticsearch query ESQL rule","params":{"size":0,"esqlQuery":{"esql":"FROM kibana_sample_data_logs | KEEP bytes, clientip, host, geo.dest | where geo.dest != \"GB\" | STATS sumbytes = sum(bytes) by clientip, host | WHERE sumbytes \u003e 5000 | SORT sumbytes desc | LIMIT 10"},"threshold":[0],"timeField":"@timestamp","searchType":"esqlQuery","timeWindowSize":1,"timeWindowUnit":"d","thresholdComparator":"\u003e"},"actions":[{"id":"d0db1fe0-78d6-11ee-9177-f7d404c8c945","group":"query matched","params":{"level":"info","message":"Elasticsearch query rule '{{rule.name}}' is active:\n- Value: {{context.value}} - Conditions Met: {{context.conditions}} over {{rule.params.timeWindowSize}}{{rule.params.timeWindowUnit}} - Timestamp: {{context.date}} - Link: {{context.link}}"},"frequency":{"summary":false,"notify_when":"onActiveAlert"}}],"consumer":"stackAlerts","schedule":{"interval":"1d"},"rule_type_id":".es-query"}'

Request examples

Create an Elasticsearch query rule that uses Elasticsearch Query Language (ES|QL) to define its query and a server log connector to send notifications.

{
  "name": "my Elasticsearch query ESQL rule",
  "params": {
    "size": 0,
    "esqlQuery": {
      "esql": "FROM kibana_sample_data_logs | KEEP bytes, clientip, host, geo.dest | where geo.dest != \"GB\" | STATS sumbytes = sum(bytes) by clientip, host | WHERE sumbytes > 5000 | SORT sumbytes desc | LIMIT 10"
    },
    "threshold": [
      0
    ],
    "timeField": "@timestamp",
    "searchType": "esqlQuery",
    "timeWindowSize": 1,
    "timeWindowUnit": "d",
    "thresholdComparator": ">"
  },
  "actions": [
    {
      "id": "d0db1fe0-78d6-11ee-9177-f7d404c8c945",
      "group": "query matched",
      "params": {
        "level": "info",
        "message": "Elasticsearch query rule '{{rule.name}}' is active:\n- Value: {{context.value}} - Conditions Met: {{context.conditions}} over {{rule.params.timeWindowSize}}{{rule.params.timeWindowUnit}} - Timestamp: {{context.date}} - Link: {{context.link}}"
      },
      "frequency": {
        "summary": false,
        "notify_when": "onActiveAlert"
      }
    }
  ],
  "consumer": "stackAlerts",
  "schedule": {
    "interval": "1d"
  },
  "rule_type_id": ".es-query"
}

Create an Elasticsearch query rule that uses Kibana query language (KQL).

{
  "name": "my Elasticsearch query KQL rule",
  "params": {
    "size": 100,
    "aggType": "count",
    "groupBy": "all",
    "threshold": [
      1000
    ],
    "searchType": "searchSource",
    "timeWindowSize": 5,
    "timeWindowUnit": "m",
    "searchConfiguration": {
      "index": "90943e30-9a47-11e8-b64d-95841ca0b247",
      "query": {
        "query": "\"\"geo.src : \"US\" \"\"",
        "language": "kuery"
      }
    },
    "thresholdComparator": ">",
    "excludeHitsFromPreviousRun": true
  },
  "consumer": "alerts",
  "schedule": {
    "interval": "1m"
  },
  "rule_type_id": ".es-query"
}

Create an Elasticsearch query rule that uses Elasticsearch query domain specific language (DSL) to define its query and a server log connector to send notifications.

{
  "name": "my Elasticsearch query rule",
  "params": {
    "size": 100,
    "index": [
      "kibana_sample_data_logs"
    ],
    "esQuery": "\"\"\"{\"query\":{\"match_all\" : {}}}\"\"\"",
    "threshold": [
      100
    ],
    "timeField": "@timestamp",
    "timeWindowSize": 1,
    "timeWindowUnit": "d",
    "thresholdComparator": ">"
  },
  "actions": [
    {
      "id": "fdbece50-406c-11ee-850e-c71febc4ca7f",
      "group": "query matched",
      "params": {
        "level": "info",
        "message": "The system has detected {{alerts.new.count}} new, {{alerts.ongoing.count}} ongoing, and {{alerts.recovered.count}} recovered alerts."
      },
      "frequency": {
        "summary": true,
        "throttle": "1d",
        "notify_when": "onThrottleInterval"
      }
    },
    {
      "id": "fdbece50-406c-11ee-850e-c71febc4ca7f",
      "group": "recovered",
      "params": {
        "level": "info",
        "message": "Recovered"
      },
      "frequency": {
        "summary": false,
        "notify_when": "onActionGroupChange"
      }
    }
  ],
  "consumer": "alerts",
  "schedule": {
    "interval": "1d"
  },
  "rule_type_id": ".es-query"
}

Create an index threshold rule that uses a server log connector to send notifications when the threshold is met.

{
  "name": "my rule",
  "tags": [
    "cpu"
  ],
  "params": {
    "index": [
      ".test-index"
    ],
    "aggType": "avg",
    "groupBy": "top",
    "aggField": "sheet.version",
    "termSize": 6,
    "termField": "name.keyword",
    "threshold": [
      1000
    ],
    "timeField": "@timestamp",
    "timeWindowSize": 5,
    "timeWindowUnit": "m",
    "thresholdComparator": ">"
  },
  "actions": [
    {
      "id": "48de3460-f401-11ed-9f8e-399c75a2deeb",
      "group": "threshold met",
      "params": {
        "level": "info",
        "message": "Rule '{{rule.name}}' is active for group '{{context.group}}':\n\n- Value: {{context.value}}\n- Conditions Met: {{context.conditions}} over {{rule.params.timeWindowSize}}{{rule.params.timeWindowUnit}}\n- Timestamp: {{context.date}}"
      },
      "frequency": {
        "summary": false,
        "notify_when": "onActionGroupChange"
      }
    }
  ],
  "consumer": "alerts",
  "schedule": {
    "interval": "1m"
  },
  "alert_delay": {
    "active": 3
  },
  "rule_type_id": ".index-threshold"
}

Create a tracking containment rule that checks when an entity is contained or no longer contained within a boundary.

{
  "name": "my tracking rule",
  "params": {
    "index": "kibana_sample_data_logs",
    "entity": "agent.keyword",
    "indexId": "90943e30-9a47-11e8-b64d-95841ca0b247",
    "geoField": "geo.coordinates",
    "dateField\"": "@timestamp",
    "boundaryType": "entireIndex",
    "boundaryIndexId": "0cd90abf-abe7-44c7-909a-f621bbbcfefc",
    "boundaryGeoField": "location",
    "boundaryNameField": "name",
    "boundaryIndexTitle": "boundary*"
  },
  "consumer": "alerts",
  "schedule": {
    "interval": "1h"
  },
  "rule_type_id": ".geo-containment"
}

Response examples (200)

The response for successfully creating an Elasticsearch query rule that uses Elasticsearch Query Language (ES|QL).

{
  "id": "e0d62360-78e8-11ee-9177-f7d404c8c945",
  "name": "my Elasticsearch query ESQL rule",
  "tags": [],
  "params": {
    "size": 0,
    "aggType": "count",
    "groupBy": "all",
    "esqlQuery": {
      "esql": "FROM kibana_sample_data_logs | keep bytes, clientip, host, geo.dest | WHERE geo.dest != \"GB\" | stats sumbytes = sum(bytes) by clientip, host | WHERE sumbytes > 5000 | sort sumbytes desc | limit 10"
    },
    "threshold": [
      0
    ],
    "timeField": "@timestamp",
    "searchType": "esqlQuery",
    "timeWindowSize": 1,
    "timeWindowUnit": "d",
    "thresholdComparator": ">",
    "excludeHitsFromPreviousRun\"": "true,"
  },
  "actions": [
    {
      "id": "d0db1fe0-78d6-11ee-9177-f7d404c8c945",
      "uuid": "bfe370a3-531b-4855-bbe6-ad739f578844",
      "group": "query matched",
      "params": {
        "level": "info",
        "message": "Elasticsearch query rule '{{rule.name}}' is active:\n- Value: {{context.value}} - Conditions Met: {{context.conditions}} over {{rule.params.timeWindowSize}}{{rule.params.timeWindowUnit}} - Timestamp: {{context.date}} - Link: {{context.link}}"
      },
      "frequency": {
        "summary": false,
        "throttle": null,
        "notify_when": "onActiveAlert"
      },
      "connector_type_id": ".server-log"
    }
  ],
  "enabled": true,
  "running": false,
  "consumer": "stackAlerts",
  "mute_all": false,
  "revision": 0,
  "schedule": {
    "interval": "1d"
  },
  "throttle": null,
  "created_at": "2023-11-01T19:00:10.453Z",
  "created_by": "elastic",
  "updated_at": "2023-11-01T19:00:10.453Z",
  "updated_by": "elastic\",",
  "notify_when": null,
  "rule_type_id": ".es-query",
  "api_key_owner": "elastic",
  "muted_alert_ids": [],
  "execution_status": {
    "status": "pending",
    "last_execution_date": "2023-11-01T19:00:10.453Z"
  },
  "scheduled_task_id": "e0d62360-78e8-11ee-9177-f7d404c8c945",
  "api_key_created_by_user": false
}

The response for successfully creating an Elasticsearch query rule that uses Kibana query language (KQL).

{
  "id": "7bd506d0-2284-11ee-8fad-6101956ced88",
  "name": "my Elasticsearch query KQL rule\"",
  "tags": [],
  "params": {
    "size": 100,
    "aggType": "count",
    "groupBy": "all",
    "threshold": [
      1000
    ],
    "searchType": "searchSource",
    "timeWindowSize": 5,
    "timeWindowUnit": "m",
    "searchConfiguration": {
      "index": "90943e30-9a47-11e8-b64d-95841ca0b247",
      "query": {
        "query": "\"\"geo.src : \"US\" \"\"",
        "language": "kuery"
      }
    },
    "thresholdComparator": ">",
    "excludeHitsFromPreviousRun": true
  },
  "actions": [],
  "enabled": true,
  "running": false,
  "consumer": "alerts",
  "mute_all": false,
  "revision": 0,
  "schedule": {
    "interval": "1m"
  },
  "throttle": null,
  "created_at": "2023-07-14T20:24:50.729Z",
  "created_by": "elastic",
  "updated_at": "2023-07-14T20:24:50.729Z",
  "updated_by": "elastic",
  "notify_when": null,
  "rule_type_id": ".es-query",
  "api_key_owner": "elastic",
  "muted_alert_ids": [],
  "execution_status": {
    "status": "pending",
    "last_execution_date": "2023-07-14T20:24:50.729Z"
  },
  "scheduled_task_id": "7bd506d0-2284-11ee-8fad-6101956ced88",
  "api_key_created_by_user": false
}

The response for successfully creating an Elasticsearch query rule that uses Elasticsearch query domain specific language (DSL).

{
  "id": "58148c70-407f-11ee-850e-c71febc4ca7f",
  "name": "my Elasticsearch query rule",
  "tags": [],
  "params": {
    "size": 100,
    "index": [
      "kibana_sample_data_logs"
    ],
    "aggType": "count",
    "esQuery": "\"\"\"{\"query\":{\"match_all\" : {}}}\"\"\"",
    "groupBy": "all",
    "threshold": [
      100
    ],
    "timeField": "@timestamp",
    "searchType": "esQuery",
    "timeWindowSize": 1,
    "timeWindowUnit": "d",
    "thresholdComparator": ">",
    "excludeHitsFromPreviousRun": true
  },
  "actions": [
    {
      "id": "fdbece50-406c-11ee-850e-c71febc4ca7f",
      "uuid": "53f3c2a3-e5d0-4cfa-af3b-6f0881385e78",
      "group": "query matched",
      "params": {
        "level": "info",
        "message": "The system has detected {{alerts.new.count}} new, {{alerts.ongoing.count}} ongoing, and {{alerts.recovered.count}} recovered alerts."
      },
      "frequency": {
        "summary": true,
        "throttle": "1d",
        "notify_when": "onThrottleInterval"
      },
      "connector_type_id": ".server-log"
    },
    {
      "id": "fdbece50-406c-11ee-850e-c71febc4ca7f",
      "uuid": "2324e45b-c0df-45c7-9d70-4993e30be758",
      "group": "recovered",
      "params": {
        "level": "info",
        "message": "Recovered"
      },
      "frequency": {
        "summary": false,
        "throttle": null,
        "notify_when": "onActionGroupChange"
      },
      "connector_type_id": ".server-log"
    }
  ],
  "enabled": true,
  "running": false,
  "consumer": "alerts",
  "mute_all": false,
  "revision": 0,
  "schedule": {
    "interval": "1d"
  },
  "throttle": null,
  "created_at": "2023-08-22T00:03:38.263Z",
  "created_by": "elastic",
  "updated_at": "2023-08-22T00:03:38.263Z",
  "updated_by": "elastic",
  "notify_when": null,
  "rule_type_id": ".es-query",
  "api_key_owner": "elastic",
  "muted_alert_ids": [],
  "execution_status": {
    "status": "pending",
    "last_execution_date": "2023-08-22T00:03:38.263Z"
  },
  "scheduled_task_id": "58148c70-407f-11ee-850e-c71febc4ca7f",
  "api_key_created_by_user": false
}

The response for successfully creating an index threshold rule.

{
  "id": "41893910-6bca-11eb-9e0d-85d233e3ee35",
  "name": "my rule",
  "tags": [
    "cpu"
  ],
  "params": {
    "index": [
      ".test-index"
    ],
    "aggType": "avg",
    "groupBy": "top",
    "aggField": "sheet.version",
    "termSize": 6,
    "termField": "name.keyword",
    "threshold": [
      1000
    ],
    "timeField": "@timestamp",
    "timeWindowSize": 5,
    "timeWindowUnit": "m",
    "thresholdComparator": ">"
  },
  "actions": [
    {
      "id": "dceeb5d0-6b41-11eb-802b-85b0c1bc8ba2",
      "uuid": "07aef2a0-9eed-4ef9-94ec-39ba58eb609d",
      "group": "threshold met",
      "params": {
        "level": "info",
        "message": "Rule {{rule.name}} is active for group {{context.group} :\n\n- Value: {{context.value}}\n- Conditions Met: {{context.conditions}} over {{rule.params.timeWindowSize}}{{rule.params.timeWindowUnit}}\n- Timestamp: {{context.date}}"
      },
      "frequency": {
        "summary": false,
        "throttle": null,
        "notify_when": "onActionGroupChange"
      },
      "connector_type_id": ".server-log"
    }
  ],
  "enabled": true,
  "running": false,
  "consumer": "alerts",
  "mute_all": false,
  "revision": 0,
  "schedule": {
    "interval": "1m"
  },
  "throttle": null,
  "created_at": "2022-06-08T17:20:31.632Z",
  "created_by": "elastic",
  "updated_at": "2022-06-08T17:20:31.632Z",
  "updated_by": "elastic",
  "alert_delay": {
    "active": 3
  },
  "notify_when": null,
  "rule_type_id": ".index-threshold",
  "api_key_owner": "elastic",
  "muted_alert_ids": [],
  "execution_status": {
    "status": "pending",
    "last_execution_date": "2022-06-08T17:20:31.632Z"
  },
  "scheduled_task_id": "425b0800-6bca-11eb-9e0d-85d233e3ee35",
  "api_key_created_by_user": false
}

The response for successfully creating a tracking containment rule.

{
  "id": "b6883f9d-5f70-4758-a66e-369d7c26012f",
  "name": "my tracking rule",
  "tags": [],
  "params": {
    "index": "kibana_sample_data_logs",
    "entity": "agent.keyword",
    "indexId": "90943e30-9a47-11e8-b64d-95841ca0b247",
    "geoField": "geo.coordinates",
    "dateField": "@timestamp",
    "boundaryType": "entireIndex",
    "boundaryIndexId": "0cd90abf-abe7-44c7-909a-f621bbbcfefc",
    "boundaryGeoField": "location",
    "boundaryNameField": "name",
    "boundaryIndexTitle": "boundary*"
  },
  "actions": [],
  "enabled": true,
  "running": false,
  "consumer": "alerts",
  "last_run": {
    "outcome": "succeeded",
    "warning": null,
    "outcome_msg": null,
    "alerts_count": {
      "new": 0,
      "active": 0,
      "ignored": 0,
      "recovered": 0
    },
    "outcome_order": 0
  },
  "mute_all": false,
  "next_run": "2024-02-15T03:26:38.033Z",
  "revision": 1,
  "schedule": {
    "interval": "1h"
  },
  "throttle": null,
  "created_at": "2024-02-14T19:52:55.920Z",
  "created_by": "elastic",
  "updated_at": "2024-02-15T03:24:32.574Z",
  "updated_by": "elastic",
  "notify_when": null,
  "rule_type_id": ".geo-containment",
  "api_key_owner": "elastic",
  "muted_alert_ids": [],
  "execution_status": {
    "status": "ok",
    "last_duration": 74,
    "last_execution_date": "2024-02-15T03:25:38.125Z"
  },
  "scheduled_task_id": "b6883f9d-5f70-4758-a66e-369d7c26012f",
  "api_key_created_by_user": false
}

Disable a rule

POST /api/alerting/rule/{id}/_disable

Api key auth Basic auth

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Path parameters

id string Required

The identifier for the rule.

application/json

Body

untrack boolean

Defines whether this rule's alerts should be untracked.

Responses

204

Indicates a successful call.
400

Indicates an invalid schema.
403

Indicates that this call is forbidden.
404

Indicates a rule with the given ID does not exist.

POST /api/alerting/rule/{id}/_disable

curl \
 --request POST 'https://localhost:5601/api/alerting/rule/{id}/_disable' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"untrack":true}'

Request examples

# Headers
kbn-xsrf: true

# Payload
{
  "untrack": true
}

Create or update agent configuration

PUT /api/apm/settings/agent-configuration

Api key auth Basic auth

Headers

elastic-api-version string Required

The version of the API to use

Value is 2023-10-31. Default value is 2023-10-31.
kbn-xsrf string Required

A required header to protect against CSRF attacks

Query parameters

overwrite boolean

If the config exists ?overwrite=true is required

application/json

Body Required

agent_name string

Agent name
service object Required

Service
Hide service attributes Show service attributes object
- environment string
  
  Environment
- name string
  
  Name
settings object Required

Agent configuration settings
Hide settings attribute Show settings attribute object
- * string Additional properties

Responses

200 application/json

Successful response

Additional properties are NOT allowed.
400 application/json

Bad Request response
Hide response attributes Show response attributes object
- error string
  
  Error type
- message string
  
  Error message
- statusCode number
  
  Error status code
401 application/json

Unauthorized response
Hide response attributes Show response attributes object
- error string
  
  Error type
- message string
  
  Error message
- statusCode number
  
  Error status code
403 application/json

Forbidden response
Hide response attributes Show response attributes object
- error string
  
  Error type
- message string
  
  Error message
- statusCode number
  
  Error status code
404 application/json

Not found response
Hide response attributes Show response attributes object
- error string
  
  Error type
- message string
  
  Error message
- statusCode number
  
  Error status code

PUT /api/apm/settings/agent-configuration

curl \
 --request PUT 'https://localhost:5601/api/apm/settings/agent-configuration' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "elastic-api-version: 2023-10-31" \
 --header "kbn-xsrf: true" \
 --data '{"agent_name":"string","service":{"environment":"prod","name":"node"},"settings":{"additionalProperty1":"string","additionalProperty2":"string"}}'

Request examples

# Headers
elastic-api-version: 2023-10-31
kbn-xsrf: true

# Payload
{
  "agent_name": "string",
  "service": {
    "environment": "prod",
    "name": "node"
  },
  "settings": {
    "additionalProperty1": "string",
    "additionalProperty2": "string"
  }
}

Response examples (200)

{}

Response examples (400)

{
  "error": "Not Found",
  "message": "Not Found",
  "statusCode": 400
}

Response examples (401)

{
  "error": "Unauthorized",
  "message": "string",
  "statusCode": 401
}

Response examples (403)

{
  "error": "Forbidden",
  "message": "string",
  "statusCode": 403
}

Response examples (404)

{
  "error": "Not Found",
  "message": "Not Found",
  "statusCode": 404
}

Lookup single agent configuration

POST /api/apm/settings/agent-configuration/search

Api key auth Basic auth

This endpoint allows to search for single agent configuration and update 'applied_by_agent' field.

Headers

elastic-api-version string Required

The version of the API to use

Value is 2023-10-31. Default value is 2023-10-31.
kbn-xsrf string Required

A required header to protect against CSRF attacks

application/json

Body Required

etag string

If etags match then applied_by_agent field will be set to true
mark_as_applied_by_agent boolean

markAsAppliedByAgent=true means "force setting it to true regardless of etag". This is needed for Jaeger agent that doesn't have etags
service object Required

Service
Hide service attributes Show service attributes object
- environment string
  
  Environment
- name string
  
  Name

Responses

200 application/json

Successful response
Hide response attributes Show response attributes object
- _id string
  
  Identifier
- _index string
  
  Index
- _score number
  
  Score
- _source object
  
  Agent configuration
  
  Hide _source attributes Show _source attributes object
  
  @timestamp number Required
  
  Timestamp
  
  agent_name string
  
  Agent name
  
  applied_by_agent boolean
  
  Applied by agent
  
  etag string Required
  
  Etag
  
  service object Required
  
  Service
  
  Hide service attributes Show service attributes object
  
  environment string
  
  Environment
  
  name string
  
  Name
  
  settings object Required
  
  Agent configuration settings
  
  Hide settings attribute Show settings attribute object
  
  * string Additional properties
400 application/json

Bad Request response
Hide response attributes Show response attributes object
- error string
  
  Error type
- message string
  
  Error message
- statusCode number
  
  Error status code
401 application/json

Unauthorized response
Hide response attributes Show response attributes object
- error string
  
  Error type
- message string
  
  Error message
- statusCode number
  
  Error status code
404 application/json

Not found response
Hide response attributes Show response attributes object
- error string
  
  Error type
- message string
  
  Error message
- statusCode number
  
  Error status code

POST /api/apm/settings/agent-configuration/search

curl \
 --request POST 'https://localhost:5601/api/apm/settings/agent-configuration/search' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "elastic-api-version: 2023-10-31" \
 --header "kbn-xsrf: true" \
 --data '{"etag":"0bc3b5ebf18fba8163fe4c96f491e3767a358f85","mark_as_applied_by_agent":true,"service":{"environment":"prod","name":"node"}}'

Request examples

# Headers
elastic-api-version: 2023-10-31
kbn-xsrf: true

# Payload
{
  "etag": "0bc3b5ebf18fba8163fe4c96f491e3767a358f85",
  "mark_as_applied_by_agent": true,
  "service": {
    "environment": "prod",
    "name": "node"
  }
}

Response examples (200)

{
  "_id": "string",
  "_index": "string",
  "_score": 42.0,
  "_source": {
    "@timestamp": 1730194190636,
    "agent_name": "string",
    "applied_by_agent": true,
    "etag": "0bc3b5ebf18fba8163fe4c96f491e3767a358f85",
    "service": {
      "environment": "prod",
      "name": "node"
    },
    "settings": {
      "additionalProperty1": "string",
      "additionalProperty2": "string"
    }
  }
}

Response examples (400)

{
  "error": "Not Found",
  "message": "Not Found",
  "statusCode": 400
}

Response examples (401)

{
  "error": "Unauthorized",
  "message": "string",
  "statusCode": 401
}

Response examples (404)

{
  "error": "Not Found",
  "message": "Not Found",
  "statusCode": 404
}

Get case tags

GET /api/cases/tags

Api key auth Basic auth

Aggregates and returns a list of case tags. You must have read privileges for the Cases feature in the Management, Observability, or Security section of the Kibana feature privileges, depending on the owner of the cases you're seeking.

Query parameters

owner string | array[string]

A filter to limit the response to a specific set of applications. If this parameter is omitted, the response contains information about all the cases that the user has access to read.

Responses

200 application/json

Indicates a successful call.

Not more than 10000 elements.
401 application/json

Authorization information is missing or invalid.
Hide response attributes Show response attributes object
- error string
- message string
- statusCode integer

GET /api/cases/tags

curl \
 --request GET 'https://localhost:5601/api/cases/tags' \
 --header "Authorization: $API_KEY"

Response examples (200)

[
  "observability",
  "security",
  "tag 1",
  "tag 2"
]

Response examples (401)

{
  "error": "Unauthorized",
  "message": "string",
  "statusCode": 401
}

Get a full agent policy

GET /api/fleet/agent_policies/{agentPolicyId}/full

Api key auth Basic auth

Get a full agent policy by ID.

[Required authorization] Route required privileges: fleet-agent-policies-read.

Path parameters

agentPolicyId string Required

Query parameters

download boolean
standalone boolean
kubernetes boolean

Responses

200 application/json
Hide response attribute Show response attribute object
- item string | object Required
  
  Any of:
  string-1 string object-2 object
  
  Hide attributes Show attributes
  
  agent object
  
  Additional properties are NOT allowed.
  
  Hide agent attributes Show agent attributes object
  
  download object Required
  
  Additional properties are NOT allowed.
  
  Hide download attributes Show download attributes object
  
  secrets object
  
  Additional properties are NOT allowed.
  
  Hide secrets attribute Show secrets attribute object
  
  ssl object
  
  Additional properties are NOT allowed.
  
  Hide ssl attribute Show ssl attribute object
  
  key object Required
  
  Additional properties are NOT allowed.
  
  Hide key attribute Show key attribute object
  
  id string
  
  sourceURI string Required
  
  ssl object
  
  Additional properties are NOT allowed.
  
  Hide ssl attributes Show ssl attributes object
  
  certificate string
  
  certificate_authorities array[string]
  
  key string
  
  renegotiation string
  
  verification_mode string
  
  features object Required
  
  Hide features attribute Show features attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attribute Show * attribute object
  
  enabled boolean Required
  
  limits object
  
  Additional properties are NOT allowed.
  
  Hide limits attribute Show limits attribute object
  
  go_max_procs number
  
  logging object
  
  Additional properties are NOT allowed.
  
  Hide logging attributes Show logging attributes object
  
  files object
  
  Additional properties are NOT allowed.
  
  Hide files attributes Show files attributes object
  
  interval string
  
  keepfiles number
  
  rotateeverybytes number
  
  level string
  
  to_files boolean
  
  monitoring object Required
  
  Additional properties are NOT allowed.
  
  Hide monitoring attributes Show monitoring attributes object
  
  enabled boolean Required
  
  logs boolean Required
  
  metrics boolean Required
  
  namespace string
  
  traces boolean Required
  
  use_output string
  
  protection object
  
  Additional properties are NOT allowed.
  
  Hide protection attributes Show protection attributes object
  
  enabled boolean Required
  
  signing_key string Required
  
  uninstall_token_hash string Required
  
  fleet object
  
  Any of:
  object-1 object object-2 object
  
  Hide attributes Show attributes
  
  hosts array[string] Required
  
  proxy_url string
  
  secrets object
  
  Additional properties are NOT allowed.
  
  Hide secrets attribute Show secrets attribute object
  
  ssl object
  
  Additional properties are NOT allowed.
  
  Hide ssl attribute Show ssl attribute object
  
  key object Required
  
  Additional properties are NOT allowed.
  
  Hide key attribute Show key attribute object
  
  id string
  
  ssl object
  
  Additional properties are NOT allowed.
  
  Hide ssl attributes Show ssl attributes object
  
  certificate string
  
  certificate_authorities array[string]
  
  key string
  
  renegotiation string
  
  verification_mode string
  
  Hide attribute Show attribute
  
  kibana object Required
  
  Additional properties are NOT allowed.
  
  Hide kibana attributes Show kibana attributes object
  
  hosts array[string] Required
  
  path string
  
  protocol string Required
  
  id string Required
  
  inputs array[object] Required
  
  Hide inputs attributes Show inputs attributes object
  
  data_stream object Required
  
  Additional properties are allowed.
  
  Hide data_stream attribute Show data_stream attribute object
  
  namespace string Required
  
  id string Required
  
  meta object
  
  Additional properties are allowed.
  
  Hide meta attribute Show meta attribute object
  
  package object
  
  Additional properties are allowed.
  
  Hide package attributes Show package attributes object
  
  name string Required
  
  version string Required
  
  name string Required
  
  package_policy_id string Required
  
  processors array[object]
  
  Hide processors attribute Show processors attribute object
  
  add_fields object Required
  
  Additional properties are allowed.
  
  Hide add_fields attributes Show add_fields attributes object
  
  fields object Required
  
  target string Required
  
  revision number Required
  
  streams array[object]
  
  Hide streams attributes Show streams attributes object
  
  data_stream object Required
  
  Additional properties are allowed.
  
  Hide data_stream attributes Show data_stream attributes object
  
  dataset string Required
  
  type string
  
  id string Required
  
  type string Required
  
  use_output string Required
  
  namespaces array[string]
  
  output_permissions object
  
  Hide output_permissions attribute Show output_permissions attribute object
  
  * object Additional properties
  
  Additional properties are allowed.
  
  outputs object Required
  
  Hide outputs attribute Show outputs attribute object
  
  * object Additional properties
  
  Additional properties are allowed.
  
  Hide * attributes Show * attributes object
  
  ca_sha256 string | null
  
  hosts array[string]
  
  proxy_url string
  
  type string Required
  
  revision number
  
  secret_references array[object]
  
  Hide secret_references attribute Show secret_references attribute object
  
  id string Required
  
  signed object
  
  Additional properties are NOT allowed.
  
  Hide signed attributes Show signed attributes object
  
  data string Required
  
  signature string Required
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

GET /api/fleet/agent_policies/{agentPolicyId}/full

curl \
 --request GET 'https://localhost:5601/api/fleet/agent_policies/{agentPolicyId}/full' \
 --header "Authorization: $API_KEY"

Response examples (200)

{
  "item": "string"
}

Response examples (400)

{
  "error": "string",
  "errorType": "string",
  "message": "string",
  "statusCode": 42.0
}

Bulk get assets

POST /api/fleet/epm/bulk_assets

Api key auth Basic auth

[Required authorization] Route required privileges: integrations-read OR fleet-setup OR fleet-all.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

application/json

Body

assetIds array[object] Required
Hide assetIds attributes Show assetIds attributes object
- id string Required
- type string Required

Responses

200 application/json
Hide response attribute Show response attribute object
- items array[object] Required
  
  Hide items attributes Show items attributes object
  
  appLink string
  
  attributes object Required
  
  Additional properties are NOT allowed.
  
  Hide attributes attributes Show attributes attributes object
  
  description string
  
  service string
  
  title string
  
  id string Required
  
  type string Required
  
  updatedAt string
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

POST /api/fleet/epm/bulk_assets

curl \
 --request POST 'https://localhost:5601/api/fleet/epm/bulk_assets' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"assetIds":[{"id":"string","type":"string"}]}'

Request examples

# Headers
kbn-xsrf: true

# Payload
{
  "assetIds": [
    {
      "id": "string",
      "type": "string"
    }
  ]
}

Response examples (200)

{
  "items": [
    {
      "appLink": "string",
      "attributes": {
        "description": "string",
        "service": "string",
        "title": "string"
      },
      "id": "string",
      "type": "string",
      "updatedAt": "string"
    }
  ]
}

Response examples (400)

{
  "error": "string",
  "errorType": "string",
  "message": "string",
  "statusCode": 42.0
}

Get a package signature verification key ID

GET /api/fleet/epm/verification_key_id

Api key auth Basic auth

[Required authorization] Route required privileges: integrations-read OR fleet-setup OR fleet-all.

Responses

200 application/json
Hide response attribute Show response attribute object
- id string | null Required
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

GET /api/fleet/epm/verification_key_id

curl \
 --request GET 'https://localhost:5601/api/fleet/epm/verification_key_id' \
 --header "Authorization: $API_KEY"

Response examples (200)

{
  "id": "string"
}

Response examples (400)

{
  "error": "string",
  "errorType": "string",
  "message": "string",
  "statusCode": 42.0
}

Create a package policy

POST /api/fleet/package_policies

Api key auth Basic auth

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Query parameters

format string

Values are simplified or legacy.

application/json

Body object

You should use inputs as an object and not use the deprecated inputs array.

additional_datastreams_permissions array[string] | null

Additional datastream permissions, that will be added to the agent policy.
description string

Package policy description
enabled boolean
force boolean

Force package policy creation even if package is not verified, or if the agent policy is managed.
id string

Package policy unique identifier
inputs array[object] Required
Hide inputs attributes Show inputs attributes object
- config object
  
  Package variable (see integration documentation for more information)
  Hide config attribute Show config attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
- enabled boolean Required
- id string
- keep_enabled boolean
- policy_template string
- streams array[object]
  Hide streams attributes Show streams attributes object
  
  config object
  
  Package variable (see integration documentation for more information)
  
  Hide config attribute Show config attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
  
  data_stream object Required
  
  Additional properties are NOT allowed.
  
  Hide data_stream attributes Show data_stream attributes object
  
  dataset string Required
  
  elasticsearch object
  
  Additional properties are NOT allowed.
  
  Hide elasticsearch attributes Show elasticsearch attributes object
  
  dynamic_dataset boolean
  
  dynamic_namespace boolean
  
  privileges object
  
  Additional properties are NOT allowed.
  
  Hide privileges attribute Show privileges attribute object
  
  indices array[string]
  
  type string Required
  
  enabled boolean Required
  
  id string
  
  keep_enabled boolean
  
  release string
  
  Values are ga, beta, or experimental.
  
  vars object
  
  Package variable (see integration documentation for more information)
  
  Hide vars attribute Show vars attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
- type string Required
- vars object
  
  Package variable (see integration documentation for more information)
  Hide vars attribute Show vars attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
is_managed boolean
name string Required

Package policy name (should be unique)
namespace string

The package policy namespace. Leave blank to inherit the agent policy's namespace.
output_id string | null
overrides object | null

Override settings that are defined in the package policy. The override option should be used only in unusual circumstances and not as a routine procedure.

Additional properties are NOT allowed.
Hide overrides attribute Show overrides attribute object | null
- inputs object
  
  Additional properties are allowed.
package object

Additional properties are NOT allowed.
Hide package attributes Show package attributes object
- experimental_data_stream_features array[object]
  Hide experimental_data_stream_features attributes Show experimental_data_stream_features attributes object
  
  data_stream string Required
  
  features object Required
  
  Additional properties are NOT allowed.
  
  Hide features attributes Show features attributes object
  
  doc_value_only_numeric boolean
  
  doc_value_only_other boolean
  
  synthetic_source boolean
  
  tsdb boolean
- name string Required
  
  Package name
- requires_root boolean
- title string
- version string Required
  
  Package version
policy_id string | null Deprecated

Agent policy ID where that package policy will be added
policy_ids array[string]

Agent policy IDs where that package policy will be added
supports_agentless boolean | null

Indicates whether the package policy belongs to an agentless agent policy.

Default value is false.
vars object

Package variable (see integration documentation for more information)
Hide vars attribute Show vars attribute object
- * object Additional properties
  
  Additional properties are NOT allowed.
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string

additional_datastreams_permissions array[string] | null

Additional datastream permissions, that will be added to the agent policy.
description string
force boolean
id string
inputs object

Package policy inputs (see integration documentation to know what inputs are available)
Hide inputs attribute Show inputs attribute object
- * object Additional properties
  
  Additional properties are NOT allowed.
  Hide * attributes Show * attributes object
  
  enabled boolean
  
  enable or disable that input, (default to true)
  
  streams object
  
  Input streams (see integration documentation to know what streams are available)
  
  Hide streams attribute Show streams attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  enabled boolean
  
  enable or disable that stream, (default to true)
  
  vars object
  
  Input/stream level variable (see integration documentation for more information)
  
  vars object
  
  Input/stream level variable (see integration documentation for more information)
name string Required
namespace string
output_id string | null
package object Required

Additional properties are NOT allowed.
Hide package attributes Show package attributes object
- experimental_data_stream_features array[object]
  Hide experimental_data_stream_features attributes Show experimental_data_stream_features attributes object
  
  data_stream string Required
  
  features object Required
  
  Additional properties are NOT allowed.
  
  Hide features attributes Show features attributes object
  
  doc_value_only_numeric boolean
  
  doc_value_only_other boolean
  
  synthetic_source boolean
  
  tsdb boolean
- name string Required
  
  Package name
- requires_root boolean
- title string
- version string Required
  
  Package version
policy_id string | null
policy_ids array[string]
supports_agentless boolean | null

Indicates whether the package policy belongs to an agentless agent policy.

Default value is false.
vars object

Input/stream level variable (see integration documentation for more information)

Responses

200 application/json
Hide response attribute Show response attribute object
- item object Required
  
  Additional properties are NOT allowed.
  
  Hide item attributes Show item attributes object
  
  additional_datastreams_permissions array[string] | null
  
  Additional datastream permissions, that will be added to the agent policy.
  
  agents number
  
  created_at string Required
  
  created_by string Required
  
  description string
  
  Package policy description
  
  elasticsearch object
  
  Additional properties are allowed.
  
  Hide elasticsearch attribute Show elasticsearch attribute object
  
  privileges object
  
  Additional properties are allowed.
  
  Hide privileges attribute Show privileges attribute object
  
  cluster array[string]
  
  enabled boolean Required
  
  id string Required
  
  inputs array[object] | object Required
  
  Any of:
  array-1 array[object] object-2 object
  
  Hide attributes Show attributes object
  
  config object
  
  Package variable (see integration documentation for more information)
  
  Hide config attribute Show config attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
  
  enabled boolean Required
  
  id string
  
  keep_enabled boolean
  
  policy_template string
  
  streams array[object] Required
  
  Hide streams attributes Show streams attributes object
  
  config object
  
  Package variable (see integration documentation for more information)
  
  Hide config attribute Show config attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
  
  data_stream object Required
  
  Additional properties are NOT allowed.
  
  Hide data_stream attributes Show data_stream attributes object
  
  dataset string Required
  
  elasticsearch object
  
  Additional properties are NOT allowed.
  
  Hide elasticsearch attributes Show elasticsearch attributes object
  
  dynamic_dataset boolean
  
  dynamic_namespace boolean
  
  privileges object
  
  Additional properties are NOT allowed.
  
  Hide privileges attribute Show privileges attribute object
  
  indices array[string]
  
  type string Required
  
  enabled boolean Required
  
  id string
  
  keep_enabled boolean
  
  release string
  
  Values are ga, beta, or experimental.
  
  vars object
  
  Package variable (see integration documentation for more information)
  
  Hide vars attribute Show vars attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
  
  type string Required
  
  vars object
  
  Package variable (see integration documentation for more information)
  
  Hide vars attribute Show vars attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
  
  Package policy inputs (see integration documentation to know what inputs are available)
  
  Hide attribute Show attribute
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  enabled boolean
  
  enable or disable that input, (default to true)
  
  streams object
  
  Input streams (see integration documentation to know what streams are available)
  
  Hide streams attribute Show streams attribute object
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  enabled boolean
  
  enable or disable that stream, (default to true)
  
  vars object
  
  Input/stream level variable (see integration documentation for more information)
  
  vars object
  
  Input/stream level variable (see integration documentation for more information)
  
  is_managed boolean
  
  name string Required
  
  Package policy name (should be unique)
  
  namespace string
  
  The package policy namespace. Leave blank to inherit the agent policy's namespace.
  
  output_id string | null
  
  overrides object | null
  
  Override settings that are defined in the package policy. The override option should be used only in unusual circumstances and not as a routine procedure.
  
  Additional properties are NOT allowed.
  
  Hide overrides attribute Show overrides attribute object | null
  
  inputs object
  
  Additional properties are allowed.
  
  package object
  
  Additional properties are NOT allowed.
  
  Hide package attributes Show package attributes object
  
  experimental_data_stream_features array[object]
  
  Hide experimental_data_stream_features attributes Show experimental_data_stream_features attributes object
  
  data_stream string Required
  
  features object Required
  
  Additional properties are NOT allowed.
  
  Hide features attributes Show features attributes object
  
  doc_value_only_numeric boolean
  
  doc_value_only_other boolean
  
  synthetic_source boolean
  
  tsdb boolean
  
  name string Required
  
  Package name
  
  requires_root boolean
  
  title string
  
  version string Required
  
  Package version
  
  policy_id string | null Deprecated
  
  Agent policy ID where that package policy will be added
  
  policy_ids array[string]
  
  Agent policy IDs where that package policy will be added
  
  revision number Required
  
  secret_references array[object]
  
  Hide secret_references attribute Show secret_references attribute object
  
  id string Required
  
  spaceIds array[string]
  
  supports_agentless boolean | null
  
  Indicates whether the package policy belongs to an agentless agent policy.
  
  Default value is false.
  
  updated_at string Required
  
  updated_by string Required
  
  vars object
  
  Any of:
  object-1 object object-2 object
  
  Package variable (see integration documentation for more information)
  
  Hide attribute Show attribute
  
  * object Additional properties
  
  Additional properties are NOT allowed.
  
  Hide * attributes Show * attributes object
  
  frozen boolean
  
  type string
  
  version string
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number
409 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

POST /api/fleet/package_policies

curl \
 --request POST 'https://localhost:5601/api/fleet/package_policies' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"additional_datastreams_permissions":["string"],"description":"string","enabled":true,"force":true,"id":"string","inputs":[{"config":{"additionalProperty1":{"frozen":true,"type":"string"},"additionalProperty2":{"frozen":true,"type":"string"}},"enabled":true,"id":"string","keep_enabled":true,"policy_template":"string","streams":[{"config":{"additionalProperty1":{"frozen":true,"type":"string"},"additionalProperty2":{"frozen":true,"type":"string"}},"data_stream":{"dataset":"string","elasticsearch":{"dynamic_dataset":true,"dynamic_namespace":true,"privileges":{"indices":["string"]}},"type":"string"},"enabled":true,"id":"string","keep_enabled":true,"release":"ga","vars":{"additionalProperty1":{"frozen":true,"type":"string"},"additionalProperty2":{"frozen":true,"type":"string"}}}],"type":"string","vars":{"additionalProperty1":{"frozen":true,"type":"string"},"additionalProperty2":{"frozen":true,"type":"string"}}}],"is_managed":true,"name":"string","namespace":"string","output_id":"string","overrides":{"inputs":{}},"package":{"experimental_data_stream_features":[{"data_stream":"string","features":{"doc_value_only_numeric":true,"doc_value_only_other":true,"synthetic_source":true,"tsdb":true}}],"name":"string","requires_root":true,"title":"string","version":"string"},"policy_id":"string","policy_ids":["string"],"supports_agentless":false,"vars":{"additionalProperty1":{"frozen":true,"type":"string"},"additionalProperty2":{"frozen":true,"type":"string"}}}'

Request examples

# Headers
kbn-xsrf: true

# Payload
{
  "additional_datastreams_permissions": [
    "string"
  ],
  "description": "string",
  "enabled": true,
  "force": true,
  "id": "string",
  "inputs": [
    {
      "config": {
        "additionalProperty1": {
          "frozen": true,
          "type": "string"
        },
        "additionalProperty2": {
          "frozen": true,
          "type": "string"
        }
      },
      "enabled": true,
      "id": "string",
      "keep_enabled": true,
      "policy_template": "string",
      "streams": [
        {
          "config": {
            "additionalProperty1": {
              "frozen": true,
              "type": "string"
            },
            "additionalProperty2": {
              "frozen": true,
              "type": "string"
            }
          },
          "data_stream": {
            "dataset": "string",
            "elasticsearch": {
              "dynamic_dataset": true,
              "dynamic_namespace": true,
              "privileges": {
                "indices": [
                  "string"
                ]
              }
            },
            "type": "string"
          },
          "enabled": true,
          "id": "string",
          "keep_enabled": true,
          "release": "ga",
          "vars": {
            "additionalProperty1": {
              "frozen": true,
              "type": "string"
            },
            "additionalProperty2": {
              "frozen": true,
              "type": "string"
            }
          }
        }
      ],
      "type": "string",
      "vars": {
        "additionalProperty1": {
          "frozen": true,
          "type": "string"
        },
        "additionalProperty2": {
          "frozen": true,
          "type": "string"
        }
      }
    }
  ],
  "is_managed": true,
  "name": "string",
  "namespace": "string",
  "output_id": "string",
  "overrides": {
    "inputs": {}
  },
  "package": {
    "experimental_data_stream_features": [
      {
        "data_stream": "string",
        "features": {
          "doc_value_only_numeric": true,
          "doc_value_only_other": true,
          "synthetic_source": true,
          "tsdb": true
        }
      }
    ],
    "name": "string",
    "requires_root": true,
    "title": "string",
    "version": "string"
  },
  "policy_id": "string",
  "policy_ids": [
    "string"
  ],
  "supports_agentless": false,
  "vars": {
    "additionalProperty1": {
      "frozen": true,
      "type": "string"
    },
    "additionalProperty2": {
      "frozen": true,
      "type": "string"
    }
  }
}

# Headers
kbn-xsrf: true

# Payload
{
  "additional_datastreams_permissions": [
    "string"
  ],
  "description": "string",
  "force": true,
  "id": "string",
  "inputs": {
    "additionalProperty1": {
      "enabled": true,
      "streams": {
        "additionalProperty1": {
          "enabled": true,
          "vars": {}
        },
        "additionalProperty2": {
          "enabled": true,
          "vars": {}
        }
      },
      "vars": {}
    },
    "additionalProperty2": {
      "enabled": true,
      "streams": {
        "additionalProperty1": {
          "enabled": true,
          "vars": {}
        },
        "additionalProperty2": {
          "enabled": true,
          "vars": {}
        }
      },
      "vars": {}
    }
  },
  "name": "string",
  "namespace": "string",
  "output_id": "string",
  "package": {
    "experimental_data_stream_features": [
      {
        "data_stream": "string",
        "features": {
          "doc_value_only_numeric": true,
          "doc_value_only_other": true,
          "synthetic_source": true,
          "tsdb": true
        }
      }
    ],
    "name": "string",
    "requires_root": true,
    "title": "string",
    "version": "string"
  },
  "policy_id": "string",
  "policy_ids": [
    "string"
  ],
  "supports_agentless": false,
  "vars": {}
}

Response examples (200)

{
  "item": {
    "additional_datastreams_permissions": [
      "string"
    ],
    "agents": 42.0,
    "created_at": "string",
    "created_by": "string",
    "description": "string",
    "elasticsearch": {
      "privileges": {
        "cluster": [
          "string"
        ]
      }
    },
    "enabled": true,
    "id": "string",
    "inputs": [
      {
        "config": {
          "additionalProperty1": {
            "frozen": true,
            "type": "string"
          },
          "additionalProperty2": {
            "frozen": true,
            "type": "string"
          }
        },
        "enabled": true,
        "id": "string",
        "keep_enabled": true,
        "policy_template": "string",
        "streams": [
          {
            "config": {
              "additionalProperty1": {
                "frozen": true,
                "type": "string"
              },
              "additionalProperty2": {
                "frozen": true,
                "type": "string"
              }
            },
            "data_stream": {
              "dataset": "string",
              "elasticsearch": {
                "dynamic_dataset": true,
                "dynamic_namespace": true,
                "privileges": {
                  "indices": [
                    "string"
                  ]
                }
              },
              "type": "string"
            },
            "enabled": true,
            "id": "string",
            "keep_enabled": true,
            "release": "ga",
            "vars": {
              "additionalProperty1": {
                "frozen": true,
                "type": "string"
              },
              "additionalProperty2": {
                "frozen": true,
                "type": "string"
              }
            }
          }
        ],
        "type": "string",
        "vars": {
          "additionalProperty1": {
            "frozen": true,
            "type": "string"
          },
          "additionalProperty2": {
            "frozen": true,
            "type": "string"
          }
        }
      }
    ],
    "is_managed": true,
    "name": "string",
    "namespace": "string",
    "output_id": "string",
    "overrides": {
      "inputs": {}
    },
    "package": {
      "experimental_data_stream_features": [
        {
          "data_stream": "string",
          "features": {
            "doc_value_only_numeric": true,
            "doc_value_only_other": true,
            "synthetic_source": true,
            "tsdb": true
          }
        }
      ],
      "name": "string",
      "requires_root": true,
      "title": "string",
      "version": "string"
    },
    "policy_id": "string",
    "policy_ids": [
      "string"
    ],
    "revision": 42.0,
    "secret_references": [
      {
        "id": "string"
      }
    ],
    "spaceIds": [
      "string"
    ],
    "supports_agentless": false,
    "updated_at": "string",
    "updated_by": "string",
    "vars": {
      "additionalProperty1": {
        "frozen": true,
        "type": "string"
      },
      "additionalProperty2": {
        "frozen": true,
        "type": "string"
      }
    },
    "version": "string"
  }
}

Response examples (400)

{
  "error": "string",
  "errorType": "string",
  "message": "string",
  "statusCode": 42.0
}

Response examples (409)

{
  "error": "string",
  "errorType": "string",
  "message": "string",
  "statusCode": 42.0
}

Get a proxy

GET /api/fleet/proxies/{itemId}

Api key auth Basic auth

Get a proxy by ID.

[Required authorization] Route required privileges: fleet-settings-read.

Path parameters

itemId string Required

Responses

200 application/json
Hide response attribute Show response attribute object
- item object Required
  
  Additional properties are NOT allowed.
  
  Hide item attributes Show item attributes object
  
  certificate string | null
  
  certificate_authorities string | null
  
  certificate_key string | null
  
  id string Required
  
  is_preconfigured boolean
  
  Default value is false.
  
  name string Required
  
  proxy_headers object | null
  
  url string Required
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

GET /api/fleet/proxies/{itemId}

curl \
 --request GET 'https://localhost:5601/api/fleet/proxies/{itemId}' \
 --header "Authorization: $API_KEY"

Response examples (200)

{
  "item": {
    "certificate": "string",
    "certificate_authorities": "string",
    "certificate_key": "string",
    "id": "string",
    "is_preconfigured": false,
    "name": "string",
    "proxy_headers": {},
    "url": "string"
  }
}

Response examples (400)

{
  "error": "string",
  "errorType": "string",
  "message": "string",
  "statusCode": 42.0
}

Delete a role

DELETE /api/security/role/{name}

Api key auth Basic auth

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Path parameters

name string Required

Minimum length is 1.

Responses

204

Indicates a successful call.

DELETE /api/security/role/{name}

curl \
 --request DELETE 'https://localhost:5601/api/security/role/{name}' \
 --header "Authorization: $API_KEY" \
 --header "kbn-xsrf: true"

Add and remove detection alert tags

POST /api/detection_engine/signals/tags

Api key auth Basic auth

And tags to detection alerts, and remove them from alerts.

You cannot add and remove the same alert tag in the same request.

application/json

Body Required

An object containing tags to add or remove and alert ids the changes will be applied

ids array[string(nonempty)] Required

A list of alerts ids.

At least 1 element. Minimum length of each is 1.
tags object Required

Object with list of tags to add and remove.
Hide tags attributes Show tags attributes object
- tags_to_add array[string(nonempty)] Required
  
  List of keywords to organize related alerts into categories that you can filter and group.
  
  Minimum length of each is 1.
- tags_to_remove array[string(nonempty)] Required
  
  List of keywords to organize related alerts into categories that you can filter and group.
  
  Minimum length of each is 1.

Responses

200 application/json

Successful response

Elasticsearch update by query response

Additional properties are allowed.
400 application/json

Invalid input data response
One of:
Security_Detections_API_PlatformErrorResponse object Security_Detections_API_SiemErrorResponse object
Hide attributes Show attributes

error string Required

message string Required

statusCode integer Required
Hide attributes Show attributes

message string Required

status_code integer Required
401 application/json

Unsuccessful authentication response
Hide response attributes Show response attributes object
- error string Required
- message string Required
- statusCode integer Required
500 application/json

Internal server error response
Hide response attributes Show response attributes object
- message string Required
- status_code integer Required

POST /api/detection_engine/signals/tags

curl \
 --request POST 'https://localhost:5601/api/detection_engine/signals/tags' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"ids":["549c7129c76cbd554aba1bd638f8a49dde95088f5832e50218358e7eca1cf16e"],"tags":{"tags_to_add":["Duplicate"],"tags_to_remove":[]}}'

Request examples

{
  "ids": [
    "549c7129c76cbd554aba1bd638f8a49dde95088f5832e50218358e7eca1cf16e"
  ],
  "tags": {
    "tags_to_add": [
      "Duplicate"
    ],
    "tags_to_remove": []
  }
}

{
  "ids": [
    "549c7129c76cbd554aba1bd638f8a49dde95088f5832e50218358e7eca1cf16e"
  ],
  "tags": {
    "tags_to_add": [],
    "tags_to_remove": [
      "Duplicate"
    ]
  }
}

Response examples (200)

{
  "took": "68,",
  "noops": "0,",
  "total": "1,",
  "batches": "1,",
  "deleted": "0,",
  "retries": {
    "bulk": "0,",
    "search": 0
  },
  "updated": "1,",
  "failures": [],
  "timed_out": "false,",
  "throttled_millis": "0,",
  "version_conflicts": "0,",
  "requests_per_second": "-1,",
  "throttled_until_millis": "0,"
}

Response examples (400)

{
  "error": "string",
  "message": "string",
  "statusCode": 42
}

{
  "message": "string",
  "status_code": 42
}

Response examples (401)

{
  "error": "string",
  "message": "string",
  "statusCode": 42
}

Response examples (500)

{
  "message": "string",
  "status_code": 42
}

Get a file

POST /api/endpoint/action/get_file

Api key auth Basic auth

Get a file from an endpoint.

application/json

Body Required

agent_type string

List of agent types to retrieve. Defaults to endpoint.

Values are endpoint, sentinel_one, crowdstrike, or microsoft_defender_endpoint.
alert_ids array[string(nonempty)]

A list of alerts ids.

At least 1 element. Minimum length of each is 1.
case_ids array[string]

Case IDs to be updated (cannot contain empty strings)

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

Optional comment
endpoint_ids array[string] Required

List of endpoint IDs (cannot contain empty strings)

At least 1 element. Minimum length of each is 1.
parameters object Required

Optional parameters object
Hide parameters attribute Show parameters attribute object
- path string Required

Responses

200 application/json

OK

POST /api/endpoint/action/get_file

curl \
 --request POST 'https://localhost:5601/api/endpoint/action/get_file' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"comment":"Get my file","parameters":{"path":"/usr/my-file.txt"},"endpoint_ids":["ed518850-681a-4d60-bb98-e22640cae2a8"]}'

Request example

{
  "comment": "Get my file",
  "parameters": {
    "path": "/usr/my-file.txt"
  },
  "endpoint_ids": [
    "ed518850-681a-4d60-bb98-e22640cae2a8"
  ]
}

Response examples (200)

{
  "data": {
    "id": "27ba1b42-7cc6-4e53-86ce-675c876092b2",
    "hosts": {
      "ed518850-681a-4d60-bb98-e22640cae2a8": {
        "name": "gke-endpoint-gke-clu-endpoint-node-po-e1a3ab89-4c4r"
      }
    },
    "agents": [
      "ed518850-681a-4d60-bb98-e22640cae2a8"
    ],
    "status": "pending",
    "command": "get-file",
    "outputs": {},
    "agentType": "endpoint",
    "createdBy": "myuser",
    "isExpired": false,
    "startedAt": "2023-07-28T19:00:03.911Z",
    "agentState": {
      "ed518850-681a-4d60-bb98-e22640cae2a8": {
        "isCompleted": false,
        "wasSuccessful": false
      }
    },
    "parameters": {
      "path": "/usr/my-file.txt"
    },
    "isCompleted": false,
    "wasSuccessful": false
  }
}

Get running processes

POST /api/endpoint/action/running_procs

Api key auth Basic auth

Get a list of all processes running on an endpoint.

application/json

Body Required

agent_type string

List of agent types to retrieve. Defaults to endpoint.

Values are endpoint, sentinel_one, crowdstrike, or microsoft_defender_endpoint.
alert_ids array[string(nonempty)]

A list of alerts ids.

At least 1 element. Minimum length of each is 1.
case_ids array[string]

Case IDs to be updated (cannot contain empty strings)

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

Optional comment
endpoint_ids array[string] Required

List of endpoint IDs (cannot contain empty strings)

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

Optional parameters object

Responses

200 application/json

OK

POST /api/endpoint/action/running_procs

curl \
 --request POST 'https://localhost:5601/api/endpoint/action/running_procs' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"endpoint_ids":["ed518850-681a-4d60-bb98-e22640cae2a8"]}'

Request example

{
  "endpoint_ids": [
    "ed518850-681a-4d60-bb98-e22640cae2a8"
  ]
}

Response examples (200)

{
  "data": {
    "id": "233db9ea-6733-4849-9226-5a7039c7161d",
    "agents": [
      "ed518850-681a-4d60-bb98-e22640cae2a8"
    ],
    "errors": [],
    "command": "running-processes",
    "comment": "",
    "outputs": {
      "ed518850-681a-4d60-bb98-e22640cae2a8": {
        "type": "json",
        "content": {
          "key": "value"
        }
      }
    },
    "agentType": "endpoint",
    "createdBy": "myuser",
    "isExpired": false,
    "startedAt": "2022-07-29T19:08:49.126Z",
    "parameters": {},
    "completedAt": "2022-07-29T19:09:44.961Z",
    "isCompleted": true,
    "wasSuccessful": true
  }
}

Create an exception list

POST /api/exception_lists

Api key auth Basic auth

An exception list groups exception items and can be associated with detection rules. You can assign exception lists to multiple detection rules.

All exception items added to the same list are evaluated using OR logic. That is, if any of the items in a list evaluate to true, the exception prevents the rule from generating an alert. Likewise, OR logic is used for evaluating exceptions when more than one exception list is assigned to a rule. To use the AND operator, you can define multiple clauses (entries) in a single exception item.

application/json

Body Required

Exception list's properties

description string Required

Describes the exception list.
list_id string(nonempty)

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
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.
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.
version integer

The document version, automatically increasd on updates.

Minimum value is 1.

Responses

200 application/json

Successful response
Hide response attributes Show response 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.
400 application/json

Invalid input data response
One of:
Security_Exceptions_API_PlatformErrorResponse object Security_Exceptions_API_SiemErrorResponse object
Hide attributes Show attributes

error string Required

message string Required

statusCode integer Required
Hide attributes Show attributes

message string Required

status_code integer Required
401 application/json

Unsuccessful authentication response
Hide response attributes Show response attributes object
- error string Required
- message string Required
- statusCode integer Required
403 application/json

Not enough privileges response
Hide response attributes Show response attributes object
- error string Required
- message string Required
- statusCode integer Required
409 application/json

Exception list already exists response
Hide response attributes Show response attributes object
- message string Required
- status_code integer Required
500 application/json

Internal server error response
Hide response attributes Show response attributes object
- message string Required
- status_code integer Required

POST /api/exception_lists

curl \
 --request POST 'https://localhost:5601/api/exception_lists' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"name":"Sample Detection Exception List","tags":["malware"],"type":"detection","list_id":"simple_list","os_types":["linux"],"description":"This is a sample detection type exception list.","namespace_type":"single"}'

Request example

{
  "name": "Sample Detection Exception List",
  "tags": [
    "malware"
  ],
  "type": "detection",
  "list_id": "simple_list",
  "os_types": [
    "linux"
  ],
  "description": "This is a sample detection type exception list.",
  "namespace_type": "single"
}

Response examples (200)

{
  "id": "28243c2f-624a-4443-823d-c0b894880931",
  "name": "Sample Detection Exception List",
  "tags": [
    "malware"
  ],
  "type": "detection",
  "list_id": "8c1aae4c-1ef5-4bce-a2e3-16584b501783",
  "version": 1,
  "_version": "WzMsMV0=",
  "os_types": [],
  "immutable": false,
  "created_at": "2025-01-09T01:05:23.019Z",
  "created_by": "elastic",
  "updated_at": "2025-01-09T01:05:23.020Z",
  "updated_by": "elastic",
  "description": "This is a sample detection type exception with an autogenerated list_id.",
  "namespace_type": "single",
  "tie_breaker_id": "ad94de31-39f7-4ad7-b8e4-988bfa95f338"
}

{
  "id": "1a744e77-22ca-4b6b-9085-54f55275ebe5",
  "name": "Sample Agnostic Endpoint Exception List",
  "tags": [
    "malware"
  ],
  "type": "endpoint",
  "list_id": "b935eb55-7b21-4c1c-b235-faa1df23b3d6",
  "version": 1,
  "_version": "WzUsMV0=",
  "os_types": [
    "linux"
  ],
  "immutable": false,
  "created_at": "2025-01-09T01:10:36.369Z",
  "created_by": "elastic",
  "updated_at": "2025-01-09T01:10:36.369Z",
  "updated_by": "elastic",
  "description": "This is a sample agnostic endpoint type exception.",
  "namespace_type": "agnostic",
  "tie_breaker_id": "49ea0adc-a2b8-4d83-a8f3-2fb98301dea3"
}

{
  "id": "9e5fc75a-a3da-46c5-96e3-a2ec59c6bb85",
  "name": "Sample Detection Exception List",
  "tags": [
    "malware"
  ],
  "type": "detection",
  "list_id": "simple_list",
  "version": 1,
  "_version": "WzIsMV0=",
  "os_types": [
    "linux"
  ],
  "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"
}

{
  "id": "a79f4730-6e32-4278-abfc-349c0add7d54",
  "name": "Sample Endpoint Exception List",
  "tags": [
    "malware"
  ],
  "type": "endpoint",
  "list_id": "endpoint_list",
  "version": 1,
  "_version": "WzQsMV0=",
  "os_types": [
    "linux"
  ],
  "immutable": false,
  "created_at": "2025-01-09T01:07:49.658Z",
  "created_by": "elastic",
  "updated_at": "2025-01-09T01:07:49.658Z",
  "updated_by": "elastic",
  "description": "This is a sample endpoint type exception list.",
  "namespace_type": "single",
  "tie_breaker_id": "94a028af-8f47-427a-aca5-ffaf829e64ee"
}

Response examples (400)

{
  "error": "Bad Request",
  "message": "[request body]: list_id: Expected string, received number",
  "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 [POST /api/exception_lists] is unauthorized for user, this action is granted by the Kibana privileges [lists-all]",
  "statusCode": 403
}

Response examples (409)

{
  "message": "exception list id: \"simple_list\" already exists",
  "status_code": 409
}

Response examples (500)

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

Import value list items

POST /api/lists/items/_import

Api key auth Basic auth

Import value list items from a TXT or CSV file. The maximum file size is 9 million bytes.

You can import items to a new or existing list.

Query parameters

list_id string(nonempty)

List's id.

Required when importing to an existing list.

Minimum length is 1.
type string

Type of the importing list.

Required when importing a new list whose list id is not specified.

Values are binary, boolean, byte, date, date_nanos, date_range, double, double_range, float, float_range, geo_point, geo_shape, half_float, integer, integer_range, ip, ip_range, keyword, long, long_range, shape, short, or text.
serializer string
Determines how uploaded list item values are parsed. By default, list items are parsed using these named regex groups:
- (?<value>.+) - Single value item types, such as ip, long, date, keyword, and text.
- (?<gte>.+)-(?<lte>.+)|(?<value>.+) - Range value item types, such as date_range, ip_range, double_range, float_range, integer_range, and long_range.
deserializer string
Determines how retrieved list item values are presented. By default list items are presented using these Handelbar expressions:
- {{{value}}} - Single value item types, such as ip, long, date, keyword, and text.
- {{{gte}}}-{{{lte}}} - Range value item types, such as ip_range, double_range, float_range, integer_range, and long_range.
- {{{gte}}},{{{lte}}} - Date range values.
refresh string

Determines when changes made by the request are made visible to search.

Values are true, false, or wait_for.

multipart/form-data

Body Required

file string(binary)

A .txt or .csv file containing newline separated list items.

Responses

200 application/json

Successful response
Hide response attributes Show response attributes object
- _version string
  
  The version id, normally returned by the API when the document is retrieved. Use it ensure updates are done against the latest version.
- @timestamp string(date-time)
- created_at string(date-time) Required
  
  Autogenerated date of object creation.
- created_by string Required
  
  Autogenerated value - user that created object.
- description string(nonempty) Required
  
  Describes the value list.
  
  Minimum length is 1.
- deserializer string
  
  Determines how retrieved list item values are presented. By default list items are presented using these Handelbar expressions:
  
  {{{value}}} - Single value item types, such as ip, long, date, keyword, and text.
  
  {{{gte}}}-{{{lte}}} - Range value item types, such as ip_range, double_range, float_range, integer_range, and long_range.
  
  {{{gte}}},{{{lte}}} - Date range values.
- id string(nonempty) Required
  
  Value list's identifier.
  
  Minimum length is 1.
- immutable boolean Required
- meta object
  
  Placeholder for metadata about the value list.
  
  Additional properties are allowed.
- name string(nonempty) Required
  
  Value list's name.
  
  Minimum length is 1.
- serializer string
  
  Determines how uploaded list item values are parsed. By default, list items are parsed using these named regex groups:
  
  (?<value>.+) - Single value item types, such as ip, long, date, keyword, and text.
  
  (?<gte>.+)-(?<lte>.+)|(?<value>.+) - Range value item types, such as date_range, ip_range, double_range, float_range, integer_range, and long_range.
- tie_breaker_id string Required
  
  Field used in search to ensure all containers are sorted and returned correctly.
- type string Required
  
  Specifies the Elasticsearch data type of excludes the list container holds. Some common examples:
  
  keyword: Many ECS fields are Elasticsearch keywords
  
  ip: IP addresses
  
  ip_range: Range of IP addresses (supports IPv4, IPv6, and CIDR notation)
  
  Values are binary, boolean, byte, date, date_nanos, date_range, double, double_range, float, float_range, geo_point, geo_shape, half_float, integer, integer_range, ip, ip_range, keyword, long, long_range, shape, short, or text.
- 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 number.
  
  Minimum value is 1.
400 application/json

Invalid input data response
One of:
Security_Lists_API_PlatformErrorResponse object Security_Lists_API_SiemErrorResponse object
Hide attributes Show attributes

error string Required

message string Required

statusCode integer Required
Hide attributes Show attributes

message string Required

status_code integer Required
401 application/json

Unsuccessful authentication response
Hide response attributes Show response attributes object
- error string Required
- message string Required
- statusCode integer Required
403 application/json

Not enough privileges response
Hide response attributes Show response attributes object
- error string Required
- message string Required
- statusCode integer Required
409 application/json

List with specified list_id does not exist response
Hide response attributes Show response attributes object
- message string Required
- status_code integer Required
500 application/json

Internal server error response
Hide response attributes Show response attributes object
- message string Required
- status_code integer Required

POST /api/lists/items/_import

curl \
 --request POST 'https://localhost:5601/api/lists/items/_import' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: multipart/form-data" \
 --form "file=127.0.0.1
127.0.0.2
127.0.0.3
127.0.0.4
127.0.0.5
127.0.0.6
127.0.0.7
127.0.0.8
127.0.0.9
"

Response examples (200)

{
  "id": "ip_list",
  "name": "Simple list with an ip",
  "type": "ip",
  "version": 1,
  "_version": "WzAsMV0=",
  "immutable": false,
  "@timestamp": "2025-01-08T04:47:34.273Z",
  "created_at": "2025-01-08T04:47:34.273Z",
  "created_by": "elastic",
  "updated_at": "2025-01-08T04:47:34.273Z",
  "updated_by": "elastic",
  "description": "This list describes bad internet ip",
  "tie_breaker_id": "f5508188-b1e9-4e6e-9662-d039a7d89899"
}

Response examples (400)

{
  "message": "Either type or list_id need to be defined in the query",
  "status_code": 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 [POST /api/lists/items/_import?list_id=ip_list] is unauthorized for user, this action is granted by the Kibana privileges [lists-all]",
  "statusCode": 403
}

Response examples (409)

{
  "message": "string",
  "status_code": 42
}

Response examples (500)

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

Get an existing saved Timeline or Timeline template

GET /api/timeline/resolve

Api key auth Basic auth

Query parameters

template_timeline_id string

The ID of the template timeline to resolve
id string

The ID of the timeline to resolve

Responses

200 application/json

The (template) Timeline has been found
Hide response attributes Show response attributes object
- alias_purpose string
  
  Values are savedObjectConversion or savedObjectImport.
- alias_target_id string
- outcome string Required
  
  Values are exactMatch, aliasMatch, or conflict.
- timeline object | null Required
  
  Hide timeline attributes Show timeline attributes object | null
  
  columns array[object] | null
  
  The Timeline's columns
  
  Hide columns attributes Show columns attributes object
  
  aggregatable boolean | null
  
  category string | null
  
  columnHeaderType string | null
  
  description string | null
  
  example string | null
  
  id string | null
  
  indexes array[string] | null
  
  name string | null
  
  placeholder string | null
  
  searchable boolean | null
  
  type string | null
  
  created number | null
  
  The time the Timeline was created, using a 13-digit Epoch timestamp.
  
  createdBy string | null
  
  The user who created the Timeline.
  
  dataProviders array[object] | null
  
  Object containing query clauses
  
  Hide dataProviders attributes Show dataProviders attributes object
  
  and array[object] | null
  
  Hide and attributes Show and attributes object
  
  enabled boolean | null
  
  excluded boolean | null
  
  id string | null
  
  kqlQuery string | null
  
  name string | null
  
  queryMatch object | null
  
  Hide queryMatch attributes Show queryMatch attributes object | null
  
  displayField string | null
  
  displayValue string | null
  
  field string | null
  
  operator string | null
  
  value string | null | array[string]
  
  One of:
  string-1 string | null array-2 array[string] | null
  
  type string | null
  
  The type of data provider.
  
  Values are default or template.
  
  enabled boolean | null
  
  excluded boolean | null
  
  id string | null
  
  kqlQuery string | null
  
  name string | null
  
  queryMatch object | null
  
  Hide queryMatch attributes Show queryMatch attributes object | null
  
  displayField string | null
  
  displayValue string | null
  
  field string | null
  
  operator string | null
  
  value string | null | array[string]
  
  One of:
  string-1 string | null array-2 array[string] | null
  
  type string | null
  
  The type of data provider.
  
  Values are default or template.
  
  dataViewId string | null
  
  ID of the Timeline's Data View
  
  dateRange object | null
  
  The Timeline's search period.
  
  Hide dateRange attributes Show dateRange attributes object | null
  
  end string | null
  
  start string | null
  
  description string | null
  
  The Timeline's description
  
  eqlOptions object | null
  
  EQL query that is used in the correlation tab
  
  Hide eqlOptions attributes Show eqlOptions attributes object | null
  
  eventCategoryField string | null
  
  query string | null
  
  size string | null
  
  tiebreakerField string | null
  
  timestampField string | null
  
  eventType string | null Deprecated
  
  Event types displayed in the Timeline
  
  excludedRowRendererIds array[string] | null
  
  A list of row renderers that should not be used when in Event renderers mode
  
  Values are alert, alerts, auditd, auditd_file, library, netflow, plain, registry, suricata, system, system_dns, system_endgame_process, system_file, system_fim, system_security_event, system_socket, threat_match, or zeek.
  
  favorite array[object] | null
  
  Indicates when and who marked a Timeline as a favorite.
  
  Hide favorite attributes Show favorite attributes object
  
  favoriteDate number | null
  
  fullName string | null
  
  userName string | null
  
  filters array[object] | null
  
  A list of filters that should be applied to the query
  
  Hide filters attributes Show filters attributes object
  
  exists string | null
  
  match_all string | null
  
  meta object | null
  
  Hide meta attributes Show meta attributes object | null
  
  alias string | null
  
  controlledBy string | null
  
  disabled boolean | null
  
  field string | null
  
  formattedValue string | null
  
  index string | null
  
  key string | null
  
  negate boolean | null
  
  params string | null
  
  type string | null
  
  value string | null
  
  missing string | null
  
  query string | null
  
  range string | null
  
  script string | null
  
  indexNames array[string] | null
  
  A list of index names to use in the query (e.g. when the default data view has been modified)
  
  kqlMode string | null
  
  Indicates whether the KQL bar filters the query results or searches for additional results, where:
  
  filter: filters query results
  
  search: displays additional search results
  
  kqlQuery object | null
  
  KQL bar query.
  
  Hide kqlQuery attribute Show kqlQuery attribute object | null
  
  filterQuery object | null
  
  Hide filterQuery attributes Show filterQuery attributes object | null
  
  kuery object | null
  
  Hide kuery attributes Show kuery attributes object | null
  
  expression string | null
  
  kind string | null
  
  serializedQuery string | null
  
  savedQueryId string | null
  
  The ID of the saved query that might be used in the Query tab
  
  savedSearchId string | null
  
  The ID of the saved search that is used in the ES|QL tab
  
  sort object | null
  
  Object indicating how rows are sorted in the Timeline's grid
  
  Hide sort attributes Show sort attributes object | null
  
  columnId string | null
  
  columnType string | null
  
  sortDirection string | null
  
  status string | null
  
  The status of the Timeline.
  
  Values are active, draft, or immutable.
  
  templateTimelineId string | null
  
  A unique ID (UUID) for Timeline templates. For Timelines, the value is null.
  
  templateTimelineVersion number | null
  
  Timeline template version number. For Timelines, the value is null.
  
  timelineType string | null
  
  The type of Timeline.
  
  Values are default or template.
  
  title string | null
  
  The Timeline's title.
  
  updated number | null
  
  The last time the Timeline was updated, using a 13-digit Epoch timestamp
  
  updatedBy string | null
  
  The user who last updated the Timeline
  
  eventIdToNoteIds array[object] | null
  
  Hide eventIdToNoteIds attributes Show eventIdToNoteIds attributes object
  
  created number | null
  
  The time the note was created, using a 13-digit Epoch timestamp.
  
  createdBy string | null
  
  The user who created the note.
  
  updated number | null
  
  The last time the note was updated, using a 13-digit Epoch timestamp
  
  updatedBy string | null
  
  The user who last updated the note
  
  eventId string | null
  
  The _id of the associated event for this note.
  
  note string | null
  
  The text of the note
  
  timelineId string Required
  
  The savedObjectId of the Timeline that this note is associated with
  
  noteId string Required
  
  The savedObjectId of the note
  
  version string Required
  
  The version of the note
  
  noteIds array[string] | null
  
  notes array[object] | null
  
  Hide notes attributes Show notes attributes object
  
  created number | null
  
  The time the note was created, using a 13-digit Epoch timestamp.
  
  createdBy string | null
  
  The user who created the note.
  
  updated number | null
  
  The last time the note was updated, using a 13-digit Epoch timestamp
  
  updatedBy string | null
  
  The user who last updated the note
  
  eventId string | null
  
  The _id of the associated event for this note.
  
  note string | null
  
  The text of the note
  
  timelineId string Required
  
  The savedObjectId of the Timeline that this note is associated with
  
  noteId string Required
  
  The savedObjectId of the note
  
  version string Required
  
  The version of the note
  
  pinnedEventIds array[string] | null
  
  pinnedEventsSaveObject array[object] | null
  
  Hide pinnedEventsSaveObject attributes Show pinnedEventsSaveObject attributes object
  
  created number | null
  
  The time the pinned event was created, using a 13-digit Epoch timestamp.
  
  createdBy string | null
  
  The user who created the pinned event.
  
  updated number | null
  
  The last time the pinned event was updated, using a 13-digit Epoch timestamp
  
  updatedBy string | null
  
  The user who last updated the pinned event
  
  eventId string Required
  
  The _id of the associated event for this pinned event.
  
  timelineId string Required
  
  The savedObjectId of the timeline that this pinned event is associated with
  
  pinnedEventId string Required
  
  The savedObjectId of this pinned event
  
  version string Required
  
  The version of this pinned event
  
  savedObjectId string Required
  
  version string Required
400

The request is missing parameters
404

The (template) Timeline was not found

GET /api/timeline/resolve

curl \
 --request GET 'https://localhost:5601/api/timeline/resolve' \
 --header "Authorization: $API_KEY"

Response examples (200)

{
  "alias_purpose": "savedObjectConversion",
  "alias_target_id": "string",
  "outcome": "exactMatch",
  "timeline": {
    "columns": [
      {
        "id": "@timestamp",
        "columnHeaderType": "not-filtered"
      },
      {
        "id": "event.category",
        "columnHeaderType": "not-filtered"
      }
    ],
    "created": 1587468588922,
    "createdBy": "casetester",
    "dataProviders": [
      {
        "id": "id-d3a1d35a3e84a81b2f8f3859e064c224cdee1b4bcbf66f57d124dcc739c98e6b",
        "name": "d3a1d35a3e84a81b2f8f3859e064c224cdee1b4bcbf66f57d124dcc739c98e6b",
        "enabled": true,
        "excluded": false,
        "queryMatch": {
          "field": "_id,",
          "value": "d3a1d35a3e84a81b2f8f3859e064c224cdee1b4bcbf66f57d124dcc739c98e6b,",
          "operator": ":"
        }
      }
    ],
    "dataViewId": "security-solution-default",
    "dateRange": {
      "end": 1587456479201,
      "start": 1587370079200
    },
    "description": "Investigating exposure of CVE XYZ",
    "eqlOptions": {
      "size": 100,
      "query": "sequence\\n[process where process.name == \"sudo\"]\\n[any where true]",
      "timestampField": "@timestamp",
      "eventCategoryField": "event.category"
    },
    "eventType": "all",
    "excludedRowRendererIds": [
      "alert"
    ],
    "favorite": [
      {
        "userName": "elastic",
        "favoriteDate": 1741337636741
      }
    ],
    "filters": [
      {
        "meta": {
          "key": "@timestamp",
          "type": "exists",
          "alias": "Custom filter name",
          "index": ".alerts-security.alerts-default,logs-*",
          "value": "exists",
          "negate": "false,",
          "disabled": false
        },
        "query": "{\"exists\":{\"field\":\"@timestamp\"}}"
      }
    ],
    "indexNames": [
      ".logs*"
    ],
    "kqlMode": "search",
    "kqlQuery": {
      "kuery": {
        "kind": "kuery",
        "expression": "_id : *"
      },
      "filterQuery": null,
      "serializedQuery": "{\"bool\":{\"should\":[{\"exists\":{\"field\":\"_id\"}}],\"minimum_should_match\":1}}"
    },
    "savedQueryId": "c7b16904-02d7-4f32-b8f2-cc20f9625d6e",
    "savedSearchId": "6ce1b592-84e3-4b4a-9552-f189d4b82075",
    "sort": {
      "columnId": "@timestamp",
      "sortDirection": "desc"
    },
    "status": "active",
    "templateTimelineId": "6ce1b592-84e3-4b4a-9552-f189d4b82075",
    "templateTimelineVersion": 12,
    "timelineType": "default",
    "title": "CVE XYZ investigation",
    "updated": 1741344876825,
    "updatedBy": "casetester",
    "eventIdToNoteIds": [
      {
        "created": 1587468588922,
        "createdBy": "casetester",
        "updated": 1741344876825,
        "updatedBy": "casetester",
        "eventId": "d3a1d35a3e84a81b2f8f3859e064c224cdee1b4bc",
        "note": "This is an example text",
        "timelineId": "15c1929b-0af7-42bd-85a8-56e234cc7c4e",
        "noteId": "709f99c6-89b6-4953-9160-35945c8e174e",
        "version": "WzQ2LDFd"
      }
    ],
    "noteIds": [
      "string"
    ],
    "notes": [
      {
        "created": 1587468588922,
        "createdBy": "casetester",
        "updated": 1741344876825,
        "updatedBy": "casetester",
        "eventId": "d3a1d35a3e84a81b2f8f3859e064c224cdee1b4bc",
        "note": "This is an example text",
        "timelineId": "15c1929b-0af7-42bd-85a8-56e234cc7c4e",
        "noteId": "709f99c6-89b6-4953-9160-35945c8e174e",
        "version": "WzQ2LDFd"
      }
    ],
    "pinnedEventIds": [
      "string"
    ],
    "pinnedEventsSaveObject": [
      {
        "created": 1587468588922,
        "createdBy": "casetester",
        "updated": 1741344876825,
        "updatedBy": "casetester",
        "eventId": "d3a1d35a3e84a81b2f8f3859e064c224cdee1b4bc",
        "timelineId": "15c1929b-0af7-42bd-85a8-56e234cc7c4e",
        "pinnedEventId": "10r1929b-0af7-42bd-85a8-56e234f98h2f3",
        "version": "WzQ2LDFe"
      }
    ],
    "savedObjectId": "string",
    "version": "string"
  }
}

Get a short URL Technical Preview

GET /api/short_url/{id}

Api key auth Basic auth

Get a single Kibana short URL.

Path parameters

id string Required

The identifier for the short URL.

Responses

200 application/json

Indicates a successful call.
Hide response attributes Show response attributes object
- accessCount integer
- accessDate string
- createDate string
- id string
  
  The identifier for the short URL.
- locator object
  
  Hide locator attributes Show locator attributes object
  
  id string
  
  The identifier for the locator.
  
  state object
  
  The locator parameters.
  
  version string
  
  The version of Kibana when the short URL was created.
- slug string
  
  A random human-readable slug is automatically generated if the humanReadableSlug parameter is set to true. If it is set to false, a random short string is generated.

GET /api/short_url/{id}

curl \
 --request GET 'https://localhost:5601/api/short_url/{id}' \
 --header "Authorization: $API_KEY"

Response examples (200)

{
  "accessCount": 42,
  "accessDate": "string",
  "createDate": "string",
  "id": "string",
  "locator": {
    "id": "string",
    "state": {},
    "version": "string"
  },
  "slug": "string"
}

Copy saved objects between spaces

POST /api/spaces/_copy_saved_objects

Api key auth Basic auth

It also allows you to automatically copy related objects, so when you copy a dashboard, this can automatically copy over the associated visualizations, data views, and saved Discover sessions, as required. You can request to overwrite any objects that already exist in the target space if they share an identifier or you can use the resolve copy saved objects conflicts API to do this on a per-object basis.

[Required authorization] Route required privileges: copySavedObjectsToSpaces.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

application/json

Body

compatibilityMode boolean

Apply various adjustments to the saved objects that are being copied to maintain compatibility between different Kibana versions. Use this option only if you encounter issues with copied saved objects. This option cannot be used with the createNewCopies option.

Default value is false.
createNewCopies boolean

Create new copies of saved objects, regenerate each object identifier, and reset the origin. When used, potential conflict errors are avoided. This option cannot be used with the overwrite and compatibilityMode options.

Default value is true.
includeReferences boolean

When set to true, all saved objects related to the specified saved objects will also be copied into the target spaces.

Default value is false.
objects array[object] Required
Hide objects attributes Show objects attributes object
- id string Required
  
  The identifier of the saved object to copy.
- type string Required
  
  The type of the saved object to copy.
overwrite boolean

When set to true, all conflicts are automatically overridden. When a saved object with a matching type and identifier exists in the target space, that version is replaced with the version from the source space. This option cannot be used with the createNewCopies option.

Default value is false.
spaces array[string] Required

The identifiers of the spaces where you want to copy the specified objects.

Responses

200 application/json

POST /api/spaces/_copy_saved_objects

curl \
 --request POST 'https://localhost:5601/api/spaces/_copy_saved_objects' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"spaces":["marketing"],"objects":[{"id":"my-dashboard","type":"dashboard"}],"includeReferences":true}'

Request examples

Copy a dashboard with the my-dashboard ID, including all references from the default space to the marketing space. In this example, the dashboard has a reference to a visualization and that has a reference to a data view.

{
  "spaces": [
    "marketing"
  ],
  "objects": [
    {
      "id": "my-dashboard",
      "type": "dashboard"
    }
  ],
  "includeReferences": true
}

Copy a dashboard with the my-dashboard ID, including all references from the default space to the marketing space. In this example, the dashboard has a reference to a visualization and that has a reference to a data view.

{
  "spaces": [
    "marketing"
  ],
  "objects": [
    {
      "id": "my-dashboard",
      "type": "dashboard"
    }
  ],
  "createNewCopies": false,
  "includeReferences": true
}

Response examples (200)

The response for successfully copying a dashboard with the my-dashboard ID, including all references from the default space to the marketing space. The result indicates a successful copy and all three objects are created. Since these objects were created as new copies, each entry in the successResults array includes a destinationId attribute.

{
  "marketing": {
    "success": true,
    "successCount": 3,
    "successResults": [
      {
        "id": "my-dashboard",
        "meta": {
          "icon": "dashboardApp",
          "title": "Look at my dashboard"
        },
        "type": "dashboard",
        "destinationId": "1e127098-5b80-417f-b0f1-c60c8395358f"
      },
      {
        "id": "my-vis",
        "meta": {
          "icon": "visualizeApp",
          "title": "Look at my visualization"
        },
        "type": "visualization",
        "destinationId": "a610ed80-1c73-4507-9e13-d3af736c8e04"
      },
      {
        "id": "my-index-pattern",
        "meta": {
          "icon": "indexPatternApp",
          "title": "my-pattern-*"
        },
        "type": "index-pattern",
        "destinationId": "bc3c9c70-bf6f-4bec-b4ce-f4189aa9e26b"
      }
    ]
  }
}

The response for successfully copying a dashboard with the my-dashboard ID with createNewCopies turned off. The result indicates a successful copy and all three objects are created.

{
  "marketing": {
    "success": true,
    "successCount": 3,
    "successResults": [
      {
        "id": "my-dashboard",
        "meta": {
          "icon": "dashboardApp",
          "title": "Look at my dashboard"
        },
        "type": "dashboard"
      },
      {
        "id": "my-vis",
        "meta": {
          "icon": "visualizeApp",
          "title": "Look at my visualization"
        },
        "type": "visualization"
      },
      {
        "id": "my-index-pattern",
        "meta": {
          "icon": "indexPatternApp",
          "title": "my-pattern-*"
        },
        "type": "index-pattern"
      }
    ]
  }
}

A response for a failed copy of a dashboard with the my-dashboard ID including all references from the default space to the marketing and sales spaces. In this example, the dashboard has a reference to a visualization and a Canvas workpad and the visualization has a reference to an index pattern. The result indicates a successful copy for the marketing space and an unsuccessful copy for the sales space because the data view, visualization, and Canvas workpad each resulted in a conflict error. Objects are created when the error is resolved using the resolve copy conflicts API.

{
  "sales": {
    "errors": [
      {
        "id": "my-pattern",
        "meta": {
          "icon": "indexPatternApp",
          "title": "my-pattern-*"
        },
        "type": "index-pattern",
        "error": {
          "type": "conflict"
        },
        "title": "my-pattern-*"
      },
      {
        "id": "my-visualization",
        "meta": {
          "icon": "visualizeApp",
          "title": "Look at my visualization"
        },
        "type": "my-vis",
        "error": {
          "type": "conflict",
          "destinationId": "another-vis"
        },
        "title": "Look at my visualization"
      },
      {
        "id": "my-canvas",
        "meta": {
          "icon": "canvasApp",
          "title": "Look at my canvas"
        },
        "type": "canvas-workpad",
        "error": {
          "type": "ambiguous_conflict",
          "destinations": [
            {
              "id": "another-canvas",
              "title": "Look at another canvas",
              "updatedAt": "2020-07-08T16:36:32.377Z"
            },
            {
              "id": "yet-another-canvas",
              "title": "Look at yet another canvas",
              "updatedAt": "2020-07-05T12:29:54.849Z"
            }
          ]
        },
        "title": "Look at my canvas"
      }
    ],
    "success": false,
    "successCount": "1,",
    "successResults\"": [
      {
        "id": "my-dashboard",
        "meta": {
          "icon": "dashboardApp",
          "title": "Look at my dashboard"
        },
        "type": "dashboard"
      }
    ]
  },
  "marketing": {
    "success": true,
    "successCount": 4,
    "successResults": [
      {
        "id": "my-dashboard",
        "meta": {
          "icon": "dashboardApp",
          "title": "Look at my dashboard"
        },
        "type": "dashboard"
      },
      {
        "id": "my-vis",
        "meta": {
          "icon": "visualizeApp",
          "title": "Look at my visualization"
        },
        "type": "visualization"
      },
      {
        "id": "my-canvas",
        "meta": {
          "icon": "canvasApp",
          "title": "Look at my canvas"
        },
        "type": "canvas-workpad"
      },
      {
        "id": "my-index-pattern",
        "meta": {
          "icon": "indexPatternApp",
          "title": "my-pattern-*"
        },
        "type": "index-pattern"
      }
    ]
  }
}

The response for successfully copying a dashboard with the my-dashboard ID, including all references from the default space to the marketing space. In this example, the dashboard has a reference to a visualization and a Canvas workpad and the visualization has a reference to a data view. The result indicates an unsuccessful copy because the visualization resulted in a missing references error. Objects are created when the errors are resolved using the resolve copy conflicts API.

{
  "marketing": {
    "errors": [
      {
        "id": "my-vis",
        "meta": {
          "icon": "visualizeApp",
          "title": "Look at my visualization"
        },
        "type": "visualization",
        "error": {
          "type": "missing_references",
          "references": [
            {
              "id": "my-pattern-*",
              "type": "index-pattern"
            }
          ]
        },
        "title": "Look at my visualization"
      }
    ],
    "success": false,
    "successCount": 2,
    "successResults": [
      {
        "id": "my-dashboard",
        "meta": {
          "icon": "dashboardApp",
          "title": "Look at my dashboard"
        },
        "type": "dashboard"
      },
      {
        "id": "my-canvas",
        "meta": {
          "icon": "canvasApp",
          "title": "Look at my canvas"
        },
        "type": "canvas-workpad"
      }
    ]
  }
}

Bulk update dashboards Technical Preview

POST /api/streams/{name}/dashboards/_bulk

Api key auth Basic auth

Bulk update dashboards linked to a stream. Can link new dashboards and delete existing ones.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Path parameters

name string Required

application/json

Body

operations array[object] Required
Any of:
object-1 object object-2 object
Hide attribute Show attribute

index object Required

Additional properties are NOT allowed.

Hide index attribute Show index attribute object

id string Required
Hide attribute Show attribute

delete object Required

Additional properties are NOT allowed.

Hide delete attribute Show delete attribute object

id string Required

POST /api/streams/{name}/dashboards/_bulk

curl \
 --request POST 'https://localhost:5601/api/streams/{name}/dashboards/_bulk' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"operations":[{"index":{"id":"string"}}]}'

Request examples

# Headers
kbn-xsrf: true

# Payload
{
  "operations": [
    {
      "index": {
        "id": "string"
      }
    }
  ]
}

params object

Body Required

Body Required

item string | object Required

Body object

inputs array[object] | object Required

vars object

Body Required

Body Required

Body Required

Body Required

Body Required

value string | null | array[string]

value string | null | array[string]

Get a short URL Technical Preview

Bulk update dashboards Technical Preview