Alerting enables you to define rules, which detect complex conditions within your data. When a condition is met, the rule tracks it as an alert and runs the actions that are defined in the rule. Actions typically involve the use of connectors to interact with Kibana services or third party integrations.
openapi: 3.0.3
info:
contact:
name: Kibana Team
description: 'The Kibana REST APIs enable you to manage resources such as connectors, data views, and saved objects.
The API calls are stateless.
Each request that you make happens in isolation from other calls and must include all of the necessary information for Kibana to fulfill the
request.
API requests return JSON output, which is a format that is machine-readable and works well for automation.
To interact with Kibana APIs, use the following operations:
- GET: Fetches the information.
- PATCH: Applies partial modifications to the existing information.
- POST: Adds new information.
- PUT: Updates the existing information.
- DELETE: Removes the information.
You can prepend any Kibana API endpoint with `kbn:` and run the request in **Dev Tools → Console**.
For example:
```
GET kbn:/api/data_views
```
For more information about the console, refer to [Run API requests](https://www.elastic.co/docs/explore-analyze/query-filter/tools/console).
NOTE: Access to internal Kibana API endpoints will be restricted in Kibana version 9.0. Please move any integrations to publicly documented APIs.
## Documentation source and versions
This documentation is derived from the `main` branch of the [kibana](https://github.com/elastic/kibana) repository.
It is provided under license [Attribution-NonCommercial-NoDerivatives 4.0 International](https://creativecommons.org/licenses/by-nc-nd/4.0/).
This documentation contains work-in-progress information for future Elastic Stack releases.
'
title: Kibana APIs Actions alerting API
version: ''
x-doc-license:
name: Attribution-NonCommercial-NoDerivatives 4.0 International
url: https://creativecommons.org/licenses/by-nc-nd/4.0/
x-feedbackLink:
label: Feedback
url: https://github.com/elastic/docs-content/issues/new?assignees=&labels=feedback%2Ccommunity&projects=&template=api-feedback.yaml&title=%5BFeedback%5D%3A+
servers:
- url: https://{kibana_url}
variables:
kibana_url:
default: localhost:5601
security:
- apiKeyAuth: []
- basicAuth: []
tags:
- name: alerting
description: 'Alerting enables you to define rules, which detect complex conditions within your data. When a condition is met, the rule tracks it as an alert and runs the actions that are defined in the rule. Actions typically involve the use of connectors to interact with Kibana services or third party integrations.
'
externalDocs:
description: Alerting documentation
url: https://www.elastic.co/docs/explore-analyze/alerts-cases/alerts
x-displayName: Alerting
paths:
/api/alerting/_health:
get:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb get">get</span> <span class="operation-path">/s/{space_id}/api/alerting/_health</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
You must have `read` privileges for the **Management > Stack Rules** feature or for at least one of the **Analytics > Discover**, **Analytics > Machine Learning**, **Observability**, or **Security** features.
'
operationId: getAlertingHealth
responses:
'200':
content:
application/json:
examples:
getAlertingHealthResponse:
$ref: '#/components/examples/Alerting_get_health_response'
schema:
type: object
properties:
alerting_framework_health:
description: 'Three substates identify the health of the alerting framework: `decryption_health`, `execution_health`, and `read_health`.
'
type: object
properties:
decryption_health:
description: The timestamp and status of the rule decryption.
type: object
properties:
status:
enum:
- error
- ok
- warn
example: ok
type: string
timestamp:
example: '2023-01-13T01:28:00.280Z'
format: date-time
type: string
execution_health:
description: The timestamp and status of the rule run.
type: object
properties:
status:
enum:
- error
- ok
- warn
example: ok
type: string
timestamp:
example: '2023-01-13T01:28:00.280Z'
format: date-time
type: string
read_health:
description: The timestamp and status of the rule reading events.
type: object
properties:
status:
enum:
- error
- ok
- warn
example: ok
type: string
timestamp:
example: '2023-01-13T01:28:00.280Z'
format: date-time
type: string
has_permanent_encryption_key:
description: If `false`, the encrypted saved object plugin does not have a permanent encryption key.
example: true
type: boolean
is_sufficiently_secure:
description: If `false`, security is enabled but TLS is not.
example: true
type: boolean
description: Indicates a successful call.
'401':
content:
application/json:
examples:
healthUnauthorizedResponse:
$ref: '#/components/examples/Alerting_401_health_response'
schema:
$ref: '#/components/schemas/Alerting_401_response'
description: Authorization information is missing or invalid.
summary: Get the alerting framework health
tags:
- alerting
x-metaTags:
- content: Kibana
name: product_name
/api/alerting/rule_types:
get:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb get">get</span> <span class="operation-path">/s/{space_id}/api/alerting/rule_types</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
If you have `read` privileges for one or more Kibana features, the API response contains information about the appropriate rule types. For example, there are rule types associated with the **Management > Stack Rules** feature, **Analytics > Discover** and **Machine Learning** features, **Observability** features, and **Security** features. To get rule types associated with the **Stack Monitoring** feature, use the `monitoring_user` built-in role.
'
operationId: getRuleTypes
responses:
'200':
content:
application/json:
examples:
getRuleTypesResponse:
$ref: '#/components/examples/Alerting_get_rule_types_response'
schema:
items:
type: object
properties:
action_groups:
description: 'An explicit list of groups for which the rule type can schedule actions, each with the action group''s unique ID and human readable name. Rule actions validation uses this configuration to ensure that groups are valid.
'
items:
type: object
properties:
id:
type: string
name:
type: string
type: array
action_variables:
description: 'A list of action variables that the rule type makes available via context and state in action parameter templates, and a short human readable description. When you create a rule in Kibana, it uses this information to prompt you for these variables in action parameter editors.
'
type: object
properties:
context:
items:
type: object
properties:
description:
type: string
name:
type: string
useWithTripleBracesInTemplates:
type: boolean
type: array
params:
items:
type: object
properties:
description:
type: string
name:
type: string
type: array
state:
items:
type: object
properties:
description:
type: string
name:
type: string
type: array
alerts:
description: 'Details for writing alerts as data documents for this rule type.
'
type: object
properties:
context:
description: 'The namespace for this rule type.
'
enum:
- ml.anomaly-detection
- observability.apm
- observability.logs
- observability.metrics
- observability.slo
- observability.threshold
- observability.uptime
- security
- stack
type: string
dynamic:
description: Indicates whether new fields are added dynamically.
enum:
- 'false'
- runtime
- strict
- 'true'
type: string
isSpaceAware:
description: 'Indicates whether the alerts are space-aware. If true, space-specific alert indices are used.
'
type: boolean
mappings:
type: object
properties:
fieldMap:
additionalProperties:
$ref: '#/components/schemas/Alerting_fieldmap_properties'
description: 'Mapping information for each field supported in alerts as data documents for this rule type. For more information about mapping parameters, refer to the Elasticsearch documentation.
'
type: object
secondaryAlias:
description: 'A secondary alias. It is typically used to support the signals alias for detection rules.
'
type: string
shouldWrite:
description: 'Indicates whether the rule should write out alerts as data.
'
type: boolean
useEcs:
description: 'Indicates whether to include the ECS component template for the alerts.
'
type: boolean
useLegacyAlerts:
default: false
description: 'Indicates whether to include the legacy component template for the alerts.
'
type: boolean
authorized_consumers:
description: The list of the plugins IDs that have access to the rule type.
type: object
properties:
alerts:
type: object
properties:
all:
type: boolean
read:
type: boolean
apm:
type: object
properties:
all:
type: boolean
read:
type: boolean
discover:
type: object
properties:
all:
type: boolean
read:
type: boolean
infrastructure:
type: object
properties:
all:
type: boolean
read:
type: boolean
logs:
type: object
properties:
all:
type: boolean
read:
type: boolean
ml:
type: object
properties:
all:
type: boolean
read:
type: boolean
monitoring:
type: object
properties:
all:
type: boolean
read:
type: boolean
siem:
type: object
properties:
all:
type: boolean
read:
type: boolean
slo:
type: object
properties:
all:
type: boolean
read:
type: boolean
stackAlerts:
type: object
properties:
all:
type: boolean
read:
type: boolean
uptime:
type: object
properties:
all:
type: boolean
read:
type: boolean
category:
description: The rule category, which is used by features such as category-specific maintenance windows.
enum:
- management
- observability
- securitySolution
type: string
default_action_group_id:
description: The default identifier for the rule type group.
type: string
does_set_recovery_context:
description: Indicates whether the rule passes context variables to its recovery action.
type: boolean
enabled_in_license:
description: Indicates whether the rule type is enabled or disabled based on the subscription.
type: boolean
has_alerts_mappings:
description: Indicates whether the rule type has custom mappings for the alert data.
type: boolean
has_fields_for_a_a_d:
type: boolean
id:
description: The unique identifier for the rule type.
type: string
is_exportable:
description: Indicates whether the rule type is exportable in **Stack Management > Saved Objects**.
type: boolean
minimum_license_required:
description: The subscriptions required to use the rule type.
example: basic
type: string
name:
description: The descriptive name of the rule type.
type: string
producer:
description: An identifier for the application that produces this rule type.
example: stackAlerts
type: string
recovery_action_group:
description: An action group to use when an alert goes from an active state to an inactive one.
type: object
properties:
id:
type: string
name:
type: string
rule_task_timeout:
example: 5m
type: string
type: array
description: Indicates a successful call.
'401':
content:
application/json:
examples:
ruleTypesUnauthorizedResponse:
$ref: '#/components/examples/Alerting_401_rule_types_response'
schema:
$ref: '#/components/schemas/Alerting_401_response'
description: Authorization information is missing or invalid.
summary: Get the rule types
tags:
- alerting
x-metaTags:
- content: Kibana
name: product_name
/api/alerting/rule/{id}:
delete:
operationId: delete-alerting-rule-id
parameters:
- description: A required header to protect against CSRF attacks
in: header
name: kbn-xsrf
required: true
schema:
example: 'true'
type: string
- description: The identifier for the rule.
in: path
name: id
required: true
schema:
type: string
responses:
'204':
description: Indicates a successful call.
'400':
description: Indicates an invalid schema or parameters.
'403':
description: Indicates that this call is forbidden.
'404':
description: Indicates a rule with the given ID does not exist.
summary: Delete a rule
tags:
- alerting
x-metaTags:
- content: Kibana
name: product_name
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb delete">delete</span> <span class="operation-path">/s/{space_id}/api/alerting/rule/{id}</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.'
get:
operationId: get-alerting-rule-id
parameters:
- description: The identifier for the rule.
in: path
name: id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
examples:
getRuleResponse:
description: A response that contains information about an index threshold rule.
summary: Get an index threshold rule
value:
actions: []
api_key_owner: elastic
consumer: alerts
created_at: '2022-12-05T23:40:33.132Z'
created_by: elastic
enabled: true
id: 3583a470-74f6-11ed-9801-35303b735aef
mute_all: false
muted_alert_ids: []
name: my alert
notify_when: onActionGroupChange
params:
aggField: sheet.version
aggType: avg
groupBy: top
index:
- test-index
termField: name.keyword
termSize: 6
threshold:
- 1000
thresholdComparator: '>'
timeField: '@timestamp'
timeWindowSize: 5
timeWindowUnit: m
revision: 0
rule_type_id: .index-threshold
schedule:
interval: 1m
tags:
- cpu
throttle: null
updated_at: '2022-12-05T23:40:33.132Z'
updated_by: elastic
schema:
additionalProperties: false
type: object
properties:
actions:
items:
additionalProperties: false
type: object
properties:
alerts_filter:
additionalProperties: false
description: Defines a period that limits whether the action runs.
type: object
properties:
query:
additionalProperties: false
type: object
properties:
dsl:
description: A filter written in Elasticsearch Query Domain Specific Language (DSL).
type: string
filters:
description: A filter written in Elasticsearch Query Domain Specific Language (DSL) as defined in the `kbn-es-query` package.
items:
additionalProperties: false
type: object
properties:
$state:
additionalProperties: false
type: object
properties:
store:
description: A filter can be either specific to an application context or applied globally.
enum:
- appState
- globalState
type: string
required:
- store
meta:
additionalProperties:
description: An object with fields such as "controlledBy", "disabled", "field", "group", "index", "isMultiIndex", "key", "negate", "params", "type", "value"
nullable: true
type: object
query:
additionalProperties:
description: A query for the filter.
nullable: true
type: object
required:
- meta
type: array
kql:
description: A filter written in Kibana Query Language (KQL).
type: string
required:
- kql
- filters
timeframe:
additionalProperties: false
type: object
properties:
days:
description: 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.
items:
enum:
- 1
- 2
- 3
- 4
- 5
- 6
- 7
type: integer
type: array
hours:
additionalProperties: false
type: object
properties:
end:
description: The end of the time frame in 24-hour notation (`hh:mm`).
type: string
start:
description: The start of the time frame in 24-hour notation (`hh:mm`).
type: string
required:
- start
- end
timezone:
description: 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.
type: string
required:
- days
- hours
- timezone
connector_type_id:
description: The type of connector. This property appears in responses but cannot be set in requests.
type: string
frequency:
additionalProperties: false
type: object
properties:
notify_when:
description: '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.'
enum:
- onActionGroupChange
- onActiveAlert
- onThrottleInterval
type: string
summary:
description: Indicates whether the action is a summary.
type: boolean
throttle:
description: '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.'
nullable: true
type: string
required:
- summary
- notify_when
- throttle
group:
description: 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`.
type: string
id:
description: The identifier for the connector saved object.
type: string
params:
additionalProperties:
nullable: true
description: 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.
type: object
use_alert_data_for_template:
description: Indicates whether to use alert data as a template.
type: boolean
uuid:
description: A universally unique identifier (UUID) for the action.
type: string
required:
- id
- connector_type_id
- params
type: array
active_snoozes:
items:
description: List of active snoozes for the rule.
type: string
type: array
alert_delay:
additionalProperties: false
description: Indicates that an alert occurs only when the specified number of consecutive runs met the rule conditions.
type: object
properties:
active:
description: The number of consecutive runs that must meet the rule conditions.
type: number
required:
- active
api_key_created_by_user:
description: Indicates whether the API key that is associated with the rule was created by the user.
nullable: true
type: boolean
api_key_owner:
description: The owner of the API key that is associated with the rule and used to run background tasks.
nullable: true
type: string
artifacts:
additionalProperties: false
type: object
properties:
# --- truncated at 32 KB (810 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/kibana/refs/heads/main/openapi/kibana-alerting-api-openapi.yml