Alerting V2 is an ES|QL-first alerting API for managing rules, alert actions, and action policies. Use these endpoints to create and manage detection rules, act on alerts, and control when and how notifications are delivered. These APIs are experimental.
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-v2-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 V2 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-v2
description: 'Alerting V2 is an ES|QL-first alerting API for managing rules, alert actions, and action policies. Use these endpoints to create and manage detection rules, act on alerts, and control when and how notifications are delivered. These APIs are experimental.
'
x-displayName: Alerting V2
paths:
/api/alerting/v2/action_policies:
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/v2/action_policies</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Get a paginated list of action policies with optional filtering and sorting.<br/><br/>[Required authorization] Route required privileges: read_alerting-v2-action-policies.'
operationId: get-alerting-v2-action-policies
parameters:
- description: The page number to return. Defaults to 1.
in: query
name: page
required: false
schema:
minimum: 1
type: number
- description: The number of action policies to return per page. Defaults to 20.
in: query
name: per_page
required: false
schema:
maximum: 100
minimum: 1
type: number
- description: A text string to search across action policy fields.
in: query
name: search
required: false
schema:
maxLength: 256
minLength: 1
type: string
- description: Filter by tags. Accepts a single string or an array.
in: query
name: tags
required: false
schema:
items:
maxLength: 128
minLength: 1
type: string
maxItems: 10
type: array
- description: Filter by enabled status. Accepts the strings true or false.
in: query
name: enabled
required: false
schema:
enum:
- 'true'
- 'false'
type: string
- description: The field to sort action policies by.
in: query
name: sort_field
required: false
schema:
enum:
- name
- created_at
- updated_at
type: string
- description: The sort direction.
in: query
name: sort_order
required: false
schema:
enum:
- asc
- desc
type: string
responses:
'200':
content:
application/json:
examples:
listActionPoliciesResponse:
summary: A page of action policies
value:
items:
- auth:
created_by_user: true
owner: elastic
created_at: '2026-01-15T12:00:00.000Z'
created_by: elastic
description: Sends a workflow notification when matching host alerts fire.
destinations:
- id: workflow-1
type: workflow
enabled: true
group_by: null
grouping_mode: per_episode
id: action-policy-1
matcher: 'host.name: "web-*"'
name: Notify on host alerts
snoozed_until: null
tags:
- production
throttle:
interval: null
strategy: on_status_change
updated_at: '2026-01-15T12:00:00.000Z'
updated_by: elastic
version: WzAsMV0=
page: 1
per_page: 20
total: 1
schema:
$ref: '#/components/schemas/Kibana_HTTP_APIs_alerting_action_policy_list_response'
description: Returns a paginated list of action policies.
'400':
content:
application/json:
examples:
invalidRequest:
summary: Indicates an invalid schema or parameters.
value:
code: BAD_REQUEST
details:
errors:
errors: []
properties:
page:
errors:
- 'Too small: expected number to be >=1'
error: Bad Request
message: 'page: Too small: expected number to be >=1'
schema:
$ref: '#/components/schemas/Kibana_HTTP_APIs_alerting_error_response'
description: Indicates an invalid schema or parameters.
'401':
content:
application/json:
examples:
unauthorized:
summary: Request was not authenticated
value:
code: UNAUTHORIZED
error: Unauthorized
message: Authentication required to access this API.
schema:
$ref: '#/components/schemas/Kibana_HTTP_APIs_alerting_error_response'
description: Indicates the request was not authenticated.
'403':
content:
application/json:
examples:
forbidden:
summary: Caller lacks required privileges
value:
code: FORBIDDEN
error: Forbidden
message: The current user does not have the required privileges for this request.
schema:
$ref: '#/components/schemas/Kibana_HTTP_APIs_alerting_error_response'
description: Indicates the user does not have the required privileges to perform the request.
'500':
content:
application/json:
examples:
internalServerError:
summary: Unexpected server-side error
value:
code: INTERNAL_SERVER_ERROR
error: Internal Server Error
message: An unexpected error occurred.
schema:
$ref: '#/components/schemas/Kibana_HTTP_APIs_alerting_error_response'
description: Indicates an unexpected server-side error.
'503':
content:
application/json:
examples:
alertingDisabled:
summary: Alerting engine is disabled
value:
code: ALERTING_DISABLED
error: Service Unavailable
message: Alerting is disabled.
schema:
$ref: '#/components/schemas/Kibana_HTTP_APIs_alerting_error_response'
description: Indicates the alerting engine is disabled by the `alerting:v2:enabled` advanced setting.
summary: List action policies
tags:
- alerting-v2
x-state: Experimental; added in 9.5.0
x-metaTags:
- content: Kibana
name: product_name
post:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb post">post</span> <span class="operation-path">/s/{space_id}/api/alerting/v2/action_policies</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Creates an action policy with a server-generated identifier. To create or replace an action policy with a client-supplied identifier, use PUT /api/alerting/v2/action_policies/.<br/><br/>[Required authorization] Route required privileges: manage_alerting-v2-action-policies AND read_alerting-v2-rules.'
operationId: post-alerting-v2-action-policies
parameters:
- description: A required header to protect against CSRF attacks
in: header
name: kbn-xsrf
required: true
schema:
example: 'true'
type: string
requestBody:
content:
application/json:
examples:
createActionPolicyRequest:
summary: Workflow notification for matching host alerts
value:
description: Sends a workflow notification when matching host alerts fire.
destinations:
- id: workflow-1
type: workflow
grouping_mode: per_episode
matcher: 'host.name: "web-*"'
name: Notify on host alerts
tags:
- production
throttle:
strategy: on_status_change
schema:
$ref: '#/components/schemas/Kibana_HTTP_APIs_alerting_new_action_policy'
responses:
'201':
content:
application/json:
examples:
createActionPolicyResponse:
summary: Newly created action policy
value:
auth:
created_by_user: true
owner: elastic
created_at: '2026-01-15T12:00:00.000Z'
created_by: elastic
description: Sends a workflow notification when matching host alerts fire.
destinations:
- id: workflow-1
type: workflow
enabled: true
group_by: null
grouping_mode: per_episode
id: action-policy-1
matcher: 'host.name: "web-*"'
name: Notify on host alerts
snoozed_until: null
tags:
- production
throttle:
interval: null
strategy: on_status_change
updated_at: '2026-01-15T12:00:00.000Z'
updated_by: elastic
version: WzAsMV0=
schema:
$ref: '#/components/schemas/Kibana_HTTP_APIs_alerting_action_policy_response'
description: Returns the newly created action policy.
'400':
content:
application/json:
examples:
invalidRequest:
summary: Indicates an invalid schema or parameters.
value:
code: INVALID_ACTION_POLICY_DATA
details:
context: create
errors:
errors: []
properties:
name:
errors:
- 'Invalid input: expected string, received undefined'
error: Bad Request
message: 'Error validating create action policy data - name: Invalid input: expected string, received undefined'
schema:
$ref: '#/components/schemas/Kibana_HTTP_APIs_alerting_error_response'
description: Indicates an invalid schema or parameters.
'401':
content:
application/json:
examples:
unauthorized:
summary: Request was not authenticated
value:
code: UNAUTHORIZED
error: Unauthorized
message: Authentication required to access this API.
schema:
$ref: '#/components/schemas/Kibana_HTTP_APIs_alerting_error_response'
description: Indicates the request was not authenticated.
'403':
content:
application/json:
examples:
forbidden:
summary: Caller lacks required privileges
value:
code: FORBIDDEN
error: Forbidden
message: The current user does not have the required privileges for this request.
schema:
$ref: '#/components/schemas/Kibana_HTTP_APIs_alerting_error_response'
description: Indicates the user does not have the required privileges to perform the request.
'500':
content:
application/json:
examples:
internalServerError:
summary: Unexpected server-side error
value:
code: INTERNAL_SERVER_ERROR
error: Internal Server Error
message: An unexpected error occurred.
schema:
$ref: '#/components/schemas/Kibana_HTTP_APIs_alerting_error_response'
description: Indicates an unexpected server-side error.
'503':
content:
application/json:
examples:
alertingDisabled:
summary: Alerting engine is disabled
value:
code: ALERTING_DISABLED
error: Service Unavailable
message: Alerting is disabled.
schema:
$ref: '#/components/schemas/Kibana_HTTP_APIs_alerting_error_response'
description: Indicates the alerting engine is disabled by the `alerting:v2:enabled` advanced setting.
summary: Create an action policy
tags:
- alerting-v2
x-state: Experimental; added in 9.5.0
x-metaTags:
- content: Kibana
name: product_name
/api/alerting/v2/action_policies/_bulk_delete:
post:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb post">post</span> <span class="operation-path">/s/{space_id}/api/alerting/v2/action_policies/_bulk_delete</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
[Required authorization] Route required privileges: manage_alerting-v2-action-policies.'
operationId: post-alerting-v2-action-policies-bulk-delete
parameters:
- description: A required header to protect against CSRF attacks
in: header
name: kbn-xsrf
required: true
schema:
example: 'true'
type: string
requestBody:
content:
application/json:
examples:
bulkDeleteActionPoliciesRequest:
summary: Delete two action policies by ID
value:
ids:
- action-policy-1
- action-policy-2
schema:
$ref: '#/components/schemas/Kibana_HTTP_APIs_alerting_bulk_by_ids_request'
responses:
'200':
content:
application/json:
examples:
bulkDeleteActionPoliciesResponse:
summary: All targeted policies deleted
value:
affected_count: 2
errors: []
schema:
$ref: '#/components/schemas/Kibana_HTTP_APIs_alerting_bulk_operation_response'
description: Returns the result of the bulk delete operation.
'400':
content:
application/json:
examples:
invalidRequest:
summary: Indicates an invalid schema or parameters.
value:
code: BAD_REQUEST
details:
errors:
errors: []
properties:
ids:
errors:
- 'Invalid input: expected array, received undefined'
error: Bad Request
message: 'ids: Invalid input: expected array, received undefined'
schema:
$ref: '#/components/schemas/Kibana_HTTP_APIs_alerting_error_response'
description: Indicates an invalid schema or parameters.
'401':
content:
application/json:
examples:
unauthorized:
summary: Request was not authenticated
value:
code: UNAUTHORIZED
error: Unauthorized
message: Authentication required to access this API.
schema:
$ref: '#/components/schemas/Kibana_HTTP_APIs_alerting_error_response'
description: Indicates the request was not authenticated.
'403':
content:
application/json:
examples:
forbidden:
summary: Caller lacks required privileges
value:
code: FORBIDDEN
error: Forbidden
message: The current user does not have the required privileges for this request.
schema:
$ref: '#/components/schemas/Kibana_HTTP_APIs_alerting_error_response'
description: Indicates the user does not have the required privileges to perform the request.
'500':
content:
application/json:
examples:
internalServerError:
summary: Unexpected server-side error
value:
code: INTERNAL_SERVER_ERROR
error: Internal Server Error
message: An unexpected error occurred.
schema:
$ref: '#/components/schemas/Kibana_HTTP_APIs_alerting_error_response'
description: Indicates an unexpected server-side error.
'503':
content:
application/json:
examples:
alertingDisabled:
summary: Alerting engine is disabled
value:
code: ALERTING_DISABLED
error: Service Unavailable
message: Alerting is disabled.
schema:
$ref: '#/components/schemas/Kibana_HTTP_APIs_alerting_error_response'
description: Indicates the alerting engine is disabled by the `alerting:v2:enabled` advanced setting.
summary: Delete action policies in bulk by ID
tags:
- alerting-v2
x-state: Experimental; added in 9.5.0
x-metaTags:
- content: Kibana
name: product_name
/api/alerting/v2/action_policies/_bulk_disable:
post:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb post">post</span> <span class="operation-path">/s/{space_id}/api/alerting/v2/action_policies/_bulk_disable</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
[Required authorization] Route required privileges: manage_alerting-v2-action-policies.'
operationId: post-alerting-v2-action-policies-bulk-disable
parameters:
- description: A required header to protect against CSRF attacks
in: header
name: kbn-xsrf
required: true
schema:
example: 'true'
type: string
requestBody:
content:
application/json:
examples:
bulkDisableActionPoliciesRequest:
summary: Disable two action policies by ID
value:
ids:
- action-policy-1
- action-policy-2
schema:
$ref: '#/components/schemas/Kibana_HTTP_APIs_alerting_bulk_by_ids_request'
responses:
'200':
content:
application/json:
examples:
bulkDisableActionPoliciesResponse:
summary: All targeted policies disabled
value:
affected_count: 2
errors: []
schema:
$ref: '#/components/schemas/Kibana_HTTP_APIs_alerting_bulk_operation_response'
description: Returns the result of the bulk disable operation.
'400':
content:
application/json:
examples:
invalidRequest:
summary: Indicates an invalid schema or parameters.
value:
code: BAD_REQUEST
details:
errors:
errors: []
properties:
ids:
errors:
- 'Invalid input: expected array, received undefined'
error: Bad Request
message: 'ids: Invalid input: expected array, received undefined'
schema:
$ref: '#/components/schemas/Kibana_HTTP_APIs_alerting_error_response'
description: Indicates an invalid schema or parameters.
'401':
content:
application/json:
examples:
unauthorized:
summary: Request was not authenticated
value:
code: UNAUTHORIZED
error: Unauthorized
message: Authentication required to access this API.
schema:
$ref: '#/components/schemas/Kibana_HTTP_APIs_alerting_error_response'
description: Indicates the request was not authenticated.
'403':
content:
application/json:
examples:
forbidden:
summary: Caller lacks required privileges
value:
code: FORBIDDEN
error: Forbidden
message: The current user does not have the required privileges for this request.
schema:
$ref: '#/components/schemas/Kibana_HTTP_APIs_alerting_error_response'
description: Indicates the user does not have the required privileges to perform the request.
'500':
content:
application/json:
examples:
internalServerError:
summary: Unexpected server-side error
value:
code: INTERNAL_SERVER_ERROR
error: Internal Server Error
message: An unexpected error occurred.
schema:
$ref: '#/components/schemas/Kibana_HTTP_APIs_alerting_error_response'
description: Indicates an unexpected server-side error.
'503':
content:
application/json:
examples:
alertingDisabled:
summary: Alerting engine is disabled
value:
code: ALERTING_DISABLED
error: Service Unavailable
message: Alerting is disabled.
schema:
$ref: '#/components/schemas/Kibana_HTTP_APIs_alerting_error_response'
description: Indicates the alerting engine is disabled by the `alerting:v2:enabled` advanced setting.
summary: Disable action policies in bulk by ID
tags:
- alerting-v2
x-state: Experimental; added in 9.5.0
x-metaTags:
- content: Kibana
name: product_name
/api/alerting/v2/action_policies/_bulk_enable:
post:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb post">post</span> <span class="operation-path">/s/{space_id}/api/alerting/v2/action_policies/_bulk_enable</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
[Required authorization] Route required privileges: manage_alerting-v2-action-policies.'
operationId: post-alerting-v2-action-policies-bulk-enable
parameters:
- description: A required header to protect against CSRF attacks
in: header
name: kbn-xsrf
required: true
schema:
example: 'true'
type: string
requestBody:
content:
application/json:
examples:
bulkEnableActionPoliciesRequest:
summary: Enable two action policies by ID
value:
ids:
- action-policy-1
- action-policy-2
schema:
$ref: '#/components/schemas/Kibana_HTTP_APIs_alerting_bulk_by_ids_request'
responses:
'200':
content:
application/json:
examples:
bulkEnableActionPoliciesResponse:
summary: All targeted policies enabled
value:
affected_count: 2
errors: []
schema:
$ref: '#/components/schemas/Kibana_HTTP_APIs_alerting_bulk_operation_response'
description: Returns the result of the bulk enable operation.
'400':
content:
application/json:
examples:
invalidRequest:
summary: Indicates an invalid schema or parameters.
value:
code: BAD_REQUEST
details:
errors:
errors: []
properties:
ids:
errors:
- 'Invalid input: expected array, received undefined'
error: Bad Request
message: 'ids: Invalid input: expected array, received undefined'
schema:
$ref: '#/components/schemas/Kibana_HTTP_APIs_alerting_error_response'
description: Indicates an invalid schema or parameters.
'401':
content:
application/json:
examples:
unauthorized:
summary: Request was not authenticated
value:
code: UNAUTHORIZED
error: Unauthorized
message: Authentication required to access this API.
schema:
$ref: '#/components/schemas/Kibana_HTTP_APIs_alerting_error_response'
description: Indicates the request was not authenticated.
'403':
content:
application/json:
examples:
forbidden:
summary: Caller lacks required privileges
value:
code: FORBIDDEN
error: Forbidden
message: The current user does not have the required privileges for this request.
schema:
$ref: '#/components/schemas/Kibana_HTTP_APIs_alerting_error_response'
description: Indicates the user does not have the required privileges to perform the request.
'500':
content:
application/json:
examples:
internalServerError:
summary: Unexpected server-side error
value:
code: INTERNAL_SERVER_ERROR
error: Internal Server Error
message: An unexpected error occurred.
schema:
$ref: '#/components/schemas/Kibana_HTTP_APIs_alerting_error_response'
description: Indicates an unexpected server-side error.
'503':
content:
application/json:
examples:
alertingDisabled:
summary: Alerting engine is disabled
value:
code: ALERTING_DISABLED
error: Service Unavailable
message: Alerting is disabled.
schema:
$ref: '#/components/schemas/Kibana_HTTP_APIs_alerting_error_response'
description: Indicates the alerting engine is disabled by the `alerting:v2:enabled` advanced setting.
summary: Enable action policies in bulk by ID
tags:
- alerting-v2
x-state: Experimental; added in 9.5.0
x-metaTags:
- content: Kibana
name: product_name
/api/alerting/v2/action_policies/_bulk_snooze:
post:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb post">post</span> <span class="operation-path">/s/{space_id}/api/alerting/v2/action_policies/_bulk_snooze</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
[Required authorization] Route required privileges: manage_alerting-v2-action-policies.'
operationId: post-alerting-v2-action-policies-bulk-snooze
parameters:
- description: A required header to protect against CSRF attacks
in: header
name: kbn-xsrf
required: true
schema:
example: 'true'
type: string
requestBody:
content:
application/json:
examples:
bulkSnoozeActionPoliciesRequest:
summary: Snooze two action policies until a specific timestamp
value:
ids:
- action-policy-1
- action-policy-2
snoozed_until: '2026-01-16T12:00:00.000Z'
schema:
$ref: '#/components/schemas/Kibana_HTTP_APIs_alerting_bulk_snooze_action_policies_request'
responses:
'200':
content:
application/json:
examples:
bulkSnoozeActionPoliciesResponse:
summary: All targeted policies snoozed
value:
affected_count: 2
errors: []
schema:
$ref: '#/components/schemas/Kibana_HTTP_APIs_alerting_bulk_operation_response'
description: Returns the result of the bulk snooze operation.
'400':
content:
application/json:
examples:
invalidR
# --- truncated at 32 KB (368 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/elk-stack/refs/heads/main/openapi/elk-stack-alerting-v2-api-openapi.yml