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.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/elk-stack-alerting-api"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
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 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:
$ref: '#/components/schemas/Kibana_HTTP_APIs_rule_response'
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: Get rule details
tags:
- alerting
x-metaTags:
- content: Kibana
name: product_name
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/{id}</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.'
post:
operationId: post-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. If it is omitted, an ID is randomly generated.
in: path
name: id
required: true
schema:
type: string
requestBody:
content:
application/json:
examples:
createEsQueryEsqlRuleRequest:
description: 'Create an Elasticsearch query rule that uses Elasticsearch Query Language (ES|QL) to define its query and a server log connector to send notifications.
'
summary: Elasticsearch query rule (ES|QL)
value:
actions:
- frequency:
notify_when: onActiveAlert
summary: false
group: query matched
id: d0db1fe0-78d6-11ee-9177-f7d404c8c945
params:
level: info
message: 'Elasticsearch query rule ''{{rule.name}}'' is active:
- Value: {{context.value}} - Conditions Met: {{context.conditions}} over {{rule.params.timeWindowSize}}{{rule.params.timeWindowUnit}} - Timestamp: {{context.date}} - Link: {{context.link}}'
consumer: stackAlerts
name: my Elasticsearch query ESQL rule
params:
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
searchType: esqlQuery
size: 0
threshold:
- 0
thresholdComparator: '>'
timeField: '@timestamp'
timeWindowSize: 1
timeWindowUnit: d
rule_type_id: .es-query
schedule:
interval: 1d
createEsQueryKqlRuleRequest:
description: Create an Elasticsearch query rule that uses Kibana query language (KQL).
summary: Elasticsearch query rule (KQL)
value:
consumer: alerts
name: my Elasticsearch query KQL rule
params:
aggType: count
excludeHitsFromPreviousRun: true
groupBy: all
searchConfiguration:
index: 90943e30-9a47-11e8-b64d-95841ca0b247
query:
language: kuery
query: '""geo.src : "US" ""'
searchType: searchSource
size: 100
threshold:
- 1000
thresholdComparator: '>'
timeWindowSize: 5
timeWindowUnit: m
rule_type_id: .es-query
schedule:
interval: 1m
createEsQueryRuleRequest:
description: '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.
'
summary: Elasticsearch query rule (DSL)
value:
actions:
- frequency:
notify_when: onThrottleInterval
summary: true
throttle: 1d
group: query matched
id: fdbece50-406c-11ee-850e-c71febc4ca7f
params:
level: info
message: The system has detected {{alerts.new.count}} new, {{alerts.ongoing.count}} ongoing, and {{alerts.recovered.count}} recovered alerts.
- frequency:
notify_when: onActionGroupChange
summary: false
group: recovered
id: fdbece50-406c-11ee-850e-c71febc4ca7f
params:
level: info
message: Recovered
consumer: alerts
name: my Elasticsearch query rule
params:
esQuery: '"""{"query":{"match_all" : {}}}"""'
index:
- kibana_sample_data_logs
size: 100
threshold:
- 100
thresholdComparator: '>'
timeField: '@timestamp'
timeWindowSize: 1
timeWindowUnit: d
rule_type_id: .es-query
schedule:
interval: 1d
createIndexThresholdRuleRequest:
description: 'Create an index threshold rule that uses a server log connector to send notifications when the threshold is met.
'
summary: Index threshold rule
value:
actions:
- frequency:
notify_when: onActionGroupChange
summary: false
group: threshold met
id: 48de3460-f401-11ed-9f8e-399c75a2deeb
params:
level: info
message: 'Rule ''{{rule.name}}'' is active for group ''{{context.group}}'':
- Value: {{context.value}}
- Conditions Met: {{context.conditions}} over {{rule.params.timeWindowSize}}{{rule.params.timeWindowUnit}}
- Timestamp: {{context.date}}'
alert_delay:
active: 3
consumer: alerts
name: my rule
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
rule_type_id: .index-threshold
schedule:
interval: 1m
tags:
- cpu
createTrackingContainmentRuleRequest:
description: 'Create a tracking containment rule that checks when an entity is contained or no longer contained within a boundary.
'
summary: Tracking containment rule
value:
consumer: alerts
name: my tracking rule
params:
boundaryGeoField: location
boundaryIndexId: 0cd90abf-abe7-44c7-909a-f621bbbcfefc
boundaryIndexTitle: boundary*
boundaryNameField: name
boundaryType: entireIndex
dateField": '@timestamp'
entity: agent.keyword
geoField: geo.coordinates
index: kibana_sample_data_logs
indexId: 90943e30-9a47-11e8-b64d-95841ca0b247
rule_type_id: .geo-containment
schedule:
interval: 1h
schema:
anyOf:
- discriminator:
mapping:
.es-query: '#/components/schemas/Kibana_HTTP_APIs_es-query-create-rule-body-alerting'
.geo-containment: '#/components/schemas/Kibana_HTTP_APIs_geo-containment-create-rule-body-alerting'
.index-threshold: '#/components/schemas/Kibana_HTTP_APIs_index-threshold-create-rule-body-alerting'
apm.anomaly: '#/components/schemas/Kibana_HTTP_APIs_apm-anomaly-create-rule-body-alerting'
apm.error_rate: '#/components/schemas/Kibana_HTTP_APIs_apm-error-rate-create-rule-body-alerting'
apm.transaction_duration: '#/components/schemas/Kibana_HTTP_APIs_apm-transaction-duration-create-rule-body-alerting'
apm.transaction_error_rate: '#/components/schemas/Kibana_HTTP_APIs_apm-transaction-error-rate-create-rule-body-alerting'
datasetQuality.degradedDocs: '#/components/schemas/Kibana_HTTP_APIs_datasetquality-degradeddocs-create-rule-body-alerting'
logs.alert.document.count: '#/components/schemas/Kibana_HTTP_APIs_logs-alert-document-count-create-rule-body-alerting'
metrics.alert.inventory.threshold: '#/components/schemas/Kibana_HTTP_APIs_metrics-alert-inventory-threshold-create-rule-body-alerting'
metrics.alert.threshold: '#/components/schemas/Kibana_HTTP_APIs_metrics-alert-threshold-create-rule-body-alerting'
monitoring_alert_cluster_health: '#/components/schemas/Kibana_HTTP_APIs_monitoring-alert-cluster-hea
# --- truncated at 32 KB (395 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/elk-stack/refs/heads/main/openapi/elk-stack-alerting-api-openapi.yml