diff --git a/docs/api/alerts.asciidoc b/docs/api/alerts.asciidoc new file mode 100644 index 00000000000000..a19c538bcb4d7b --- /dev/null +++ b/docs/api/alerts.asciidoc @@ -0,0 +1,42 @@ +[[alerts-api]] +== Alerts APIs + +The following APIs are available for managing {kib} alerts. + +* <> to create an alert + +* <> to update the attributes for existing alerts + +* <> to retrieve a single alert by ID + +* <> to permanently remove an alert + +* <> to retrieve a paginated set of alerts by condition + +* <> to retrieve a list of all alert types + +* <> to enable a single alert by ID + +* <> to disable a single alert by ID + +* <> to mute alert instances for a single alert by ID + +* <> to unmute alert instances for a single alert by ID + +* <> to unmute all alert instances for a single alert by ID + +* <> to retrieve the health of the alerts framework + +include::alerts/create.asciidoc[] +include::alerts/update.asciidoc[] +include::alerts/get.asciidoc[] +include::alerts/delete.asciidoc[] +include::alerts/find.asciidoc[] +include::alerts/list.asciidoc[] +include::alerts/enable.asciidoc[] +include::alerts/disable.asciidoc[] +include::alerts/mute_all.asciidoc[] +include::alerts/mute.asciidoc[] +include::alerts/unmute_all.asciidoc[] +include::alerts/unmute.asciidoc[] +include::alerts/health.asciidoc[] diff --git a/docs/api/alerts/create.asciidoc b/docs/api/alerts/create.asciidoc new file mode 100644 index 00000000000000..9e188b971c9b54 --- /dev/null +++ b/docs/api/alerts/create.asciidoc @@ -0,0 +1,189 @@ +[[alerts-api-create]] +=== Create alert API +++++ +Create alert +++++ + +Create {kib} alerts. + +[[alerts-api-create-request]] +==== Request + +`POST :/api/alerts/alert` + +[[alerts-api-create-request-body]] +==== Request body + +`name`:: + (Required, string) A name to reference and search. + +`tags`:: + (Optional, string array) A list of keywords to reference and search. + +`alertTypeId`:: + (Required, string) The ID of the alert type that you want to call when the alert is scheduled to run. + +`schedule`:: + (Required, object) The schedule specifying when this alert should be run, using one of the available schedule formats specified under ++ +._Schedule Formats_. +[%collapsible%open] +===== +A schedule is structured such that the key specifies the format you wish to use and its value specifies the schedule. + +We currently support the _Interval format_ which specifies the interval in seconds, minutes, hours or days at which the alert should execute. +Example: `{ interval: "10s" }`, `{ interval: "5m" }`, `{ interval: "1h" }`, `{ interval: "1d" }`. + +There are plans to support multiple other schedule formats in the near future. +===== + +`throttle`:: + (Optional, string) How often this alert should fire the same actions. This will prevent the alert from sending out the same notification over and over. For example, if an alert with a `schedule` of 1 minute stays in a triggered state for 90 minutes, setting a `throttle` of `10m` or `1h` will prevent it from sending 90 notifications during this period. + +`notifyWhen`:: + (Required, string) The condition for throttling the notification: `onActionGroupChange`, `onActiveAlert`, or `onThrottleInterval`. + +`enabled`:: + (Optional, boolean) Indicates if you want to run the alert on an interval basis after it is created. + +`consumer`:: + (Required, string) The name of the application that owns the alert. This name has to match the Kibana Feature name, as that dictates the required RBAC privileges. + +`params`:: + (Required, object) The parameters to pass to the alert type executor `params` value. This will also validate against the alert type params validator, if defined. + +`actions`:: + (Optional, object array) An array of the following action objects. ++ +.Properties of the action objects: +[%collapsible%open] +===== + `group`::: + (Required, string) Grouping actions is recommended for escalations for different types of alert instances. If you don't need this, set this value to `default`. + + `id`::: + (Required, string) The ID of the action saved object to execute. + + `actionTypeId`::: + (Required, string) The ID of the <>. + + `params`::: + (Required, object) The map to the `params` that the <> will receive. ` params` are handled as Mustache templates and passed a default set of context. +===== + + +[[alerts-api-create-request-codes]] +==== Response code + +`200`:: + Indicates a successful call. + +[[alerts-api-create-example]] +==== Example + +[source,sh] +-------------------------------------------------- +$ curl -X POST api/alerts/alert -H 'kbn-xsrf: true' -H 'Content-Type: application/json' -d ' +{ + "params":{ + "aggType":"avg", + "termSize":6, + "thresholdComparator":">", + "timeWindowSize":5, + "timeWindowUnit":"m", + "groupBy":"top", + "threshold":[ + 1000 + ], + "index":[ + ".test-index" + ], + "timeField":"@timestamp", + "aggField":"sheet.version", + "termField":"name.keyword" + }, + "consumer":"alerts", + "alertTypeId":".index-threshold", + "schedule":{ + "interval":"1m" + }, + "actions":[ + { + "id":"dceeb5d0-6b41-11eb-802b-85b0c1bc8ba2", + "actionTypeId":".server-log", + "group":"threshold met", + "params":{ + "level":"info", + "message":"alert '{{alertName}}' is active for group '{{context.group}}':\n\n- Value: {{context.value}}\n- Conditions Met: {{context.conditions}} over {{params.timeWindowSize}}{{params.timeWindowUnit}}\n- Timestamp: {{context.date}}" + } + } + ], + "tags":[ + "cpu" + ], + "notifyWhen":"onActionGroupChange", + "name":"my alert" +}' +-------------------------------------------------- +// KIBANA + +The API returns the following: + +[source,sh] +-------------------------------------------------- +{ + "id": "41893910-6bca-11eb-9e0d-85d233e3ee35", + "notifyWhen": "onActionGroupChange", + "params": { + "aggType": "avg", + "termSize": 6, + "thresholdComparator": ">", + "timeWindowSize": 5, + "timeWindowUnit": "m", + "groupBy": "top", + "threshold": [ + 1000 + ], + "index": [ + ".kibana" + ], + "timeField": "@timestamp", + "aggField": "sheet.version", + "termField": "name.keyword" + }, + "consumer": "alerts", + "alertTypeId": ".index-threshold", + "schedule": { + "interval": "1m" + }, + "actions": [ + { + "actionTypeId": ".server-log", + "group": "threshold met", + "params": { + "level": "info", + "message": "alert {{alertName}} is active for group {{context.group}}:\n\n- Value: {{context.value}}\n- Conditions Met: {{context.conditions}} over {{params.timeWindowSize}}{{params.timeWindowUnit}}\n- Timestamp: {{context.date}}" + }, + "id": "dceeb5d0-6b41-11eb-802b-85b0c1bc8ba2" + } + ], + "tags": [ + "cpu" + ], + "name": "my alert", + "enabled": true, + "throttle": null, + "apiKeyOwner": "elastic", + "createdBy": "elastic", + "updatedBy": "elastic", + "muteAll": false, + "mutedInstanceIds": [], + "updatedAt": "2021-02-10T18:03:19.961Z", + "createdAt": "2021-02-10T18:03:19.961Z", + "scheduledTaskId": "425b0800-6bca-11eb-9e0d-85d233e3ee35", + "executionStatus": { + "lastExecutionDate": "2021-02-10T18:03:19.966Z", + "status": "pending" + } +} +-------------------------------------------------- diff --git a/docs/api/alerts/delete.asciidoc b/docs/api/alerts/delete.asciidoc new file mode 100644 index 00000000000000..b51005daae658d --- /dev/null +++ b/docs/api/alerts/delete.asciidoc @@ -0,0 +1,36 @@ +[[alerts-api-delete]] +=== Delete alert API +++++ +Delete alert +++++ + +Permanently remove an alert. + +WARNING: Once you delete an alert, you cannot recover it. + +[[alerts-api-delete-request]] +==== Request + +`DELETE :/api/alerts/alert/` + +[[alerts-api-delete-path-params]] +==== Path parameters + +`id`:: + (Required, string) The ID of the alert that you want to remove. + +[[alerts-api-delete-response-codes]] +==== Response code + +`200`:: + Indicates a successful call. + +==== Example + +Delete an alert with ID: + +[source,sh] +-------------------------------------------------- +$ curl -X DELETE api/alerts/alert/41893910-6bca-11eb-9e0d-85d233e3ee35 +-------------------------------------------------- +// KIBANA diff --git a/docs/api/alerts/disable.asciidoc b/docs/api/alerts/disable.asciidoc new file mode 100644 index 00000000000000..5f74c333794095 --- /dev/null +++ b/docs/api/alerts/disable.asciidoc @@ -0,0 +1,34 @@ +[[alerts-api-disable]] +=== Disable alert API +++++ +Disable alert +++++ + +Disable an alert. + +[[alerts-api-disable-request]] +==== Request + +`POST :/api/alerts/alert//_disable` + +[[alerts-api-disable-path-params]] +==== Path parameters + +`id`:: + (Required, string) The ID of the alert that you want to disable. + +[[alerts-api-disable-response-codes]] +==== Response code + +`200`:: + Indicates a successful call. + +==== Example + +Disable an alert with ID: + +[source,sh] +-------------------------------------------------- +$ curl -X POST api/alerts/alert/41893910-6bca-11eb-9e0d-85d233e3ee35/_disable +-------------------------------------------------- +// KIBANA diff --git a/docs/api/alerts/enable.asciidoc b/docs/api/alerts/enable.asciidoc new file mode 100644 index 00000000000000..a10383f2a440d1 --- /dev/null +++ b/docs/api/alerts/enable.asciidoc @@ -0,0 +1,34 @@ +[[alerts-api-enable]] +=== Enable alert API +++++ +Enable alert +++++ + +Enable an alert. + +[[alerts-api-enable-request]] +==== Request + +`POST :/api/alerts/alert//_enable` + +[[alerts-api-enable-path-params]] +==== Path parameters + +`id`:: + (Required, string) The ID of the alert that you want to enable. + +[[alerts-api-enable-response-codes]] +==== Response code + +`200`:: + Indicates a successful call. + +==== Example + +Enable an alert with ID: + +[source,sh] +-------------------------------------------------- +$ curl -X POST api/alerts/alert/41893910-6bca-11eb-9e0d-85d233e3ee35/_enable +-------------------------------------------------- +// KIBANA diff --git a/docs/api/alerts/find.asciidoc b/docs/api/alerts/find.asciidoc new file mode 100644 index 00000000000000..97cd9f4c19ba75 --- /dev/null +++ b/docs/api/alerts/find.asciidoc @@ -0,0 +1,117 @@ +[[alerts-api-find]] +=== Find alerts API +++++ +Find alerts +++++ + +Retrieve a paginated set of alerts based on condition. + +[[alerts-api-find-request]] +==== Request + +`GET :/api/alerts/_find` + +[[alerts-api-find-query-params]] +==== Query Parameters + +`per_page`:: + (Optional, number) The number of alerts to return per page. + +`page`:: + (Optional, number) The page number. + +`search`:: + (Optional, string) An Elasticsearch {ref}/query-dsl-simple-query-string-query.html[simple_query_string] query that filters the alerts in the response. + +`default_search_operator`:: + (Optional, string) The operator to use for the `simple_query_string`. The default is 'OR'. + +`search_fields`:: + (Optional, array|string) The fields to perform the `simple_query_string` parsed query against. + +`fields`:: + (Optional, array|string) The fields to return in the `attributes` key of the response. + +`sort_field`:: + (Optional, string) Sorts the response. Could be an alert fields returned in the `attributes` key of the response. + +`sort_order`:: + (Optional, string) Sort direction, either `asc` or `desc`. + +`has_reference`:: + (Optional, object) Filters the alerts that have a relations with the reference objects with the specific "type" and "ID". + +`filter`:: + (Optional, string) A <> string that you filter with an attribute from your saved object. + It should look like savedObjectType.attributes.title: "myTitle". However, If you used a direct attribute of a saved object, such as `updatedAt`, + you will have to define your filter, for example, savedObjectType.updatedAt > 2018-12-22. + +NOTE: As alerts change in {kib}, the results on each page of the response also +change. Use the find API for traditional paginated results, but avoid using it to export large amounts of data. + +[[alerts-api-find-request-codes]] +==== Response code + +`200`:: + Indicates a successful call. + +==== Examples + +Find alerts with names that start with `my`: + +[source,sh] +-------------------------------------------------- +$ curl -X GET api/alerts/_find?search_fields=name&search=my* +-------------------------------------------------- +// KIBANA + +The API returns the following: + +[source,sh] +-------------------------------------------------- +{ + "page": 1, + "perPage": 10, + "total": 1, + "data": [ + { + "id": "0a037d60-6b62-11eb-9e0d-85d233e3ee35", + "notifyWhen": "onActionGroupChange", + "params": { + "aggType": "avg", + }, + "consumer": "alerts", + "alertTypeId": "test.alert.type", + "schedule": { + "interval": "1m" + }, + "actions": [], + "tags": [], + "name": "test alert", + "enabled": true, + "throttle": null, + "apiKeyOwner": "elastic", + "createdBy": "elastic", + "updatedBy": "elastic", + "muteAll": false, + "mutedInstanceIds": [], + "updatedAt": "2021-02-10T05:37:19.086Z", + "createdAt": "2021-02-10T05:37:19.086Z", + "scheduledTaskId": "0b092d90-6b62-11eb-9e0d-85d233e3ee35", + "executionStatus": { + "lastExecutionDate": "2021-02-10T17:55:14.262Z", + "status": "ok" + } + }, + ] +} +-------------------------------------------------- + +For parameters that accept multiple values (e.g. `fields`), repeat the +query parameter for each value: + +[source,sh] +-------------------------------------------------- +$ curl -X GET api/alerts/_find?fields=id&fields=name +-------------------------------------------------- +// KIBANA diff --git a/docs/api/alerts/get.asciidoc b/docs/api/alerts/get.asciidoc new file mode 100644 index 00000000000000..934d7466dec3d7 --- /dev/null +++ b/docs/api/alerts/get.asciidoc @@ -0,0 +1,70 @@ +[[alerts-api-get]] +=== Get alert API +++++ +Get alert +++++ + +Retrieve an alert by ID. + +[[alerts-api-get-request]] +==== Request + +`GET :/api/alerts/alert/` + +[[alerts-api-get-params]] +==== Path parameters + +`id`:: + (Required, string) The ID of the alert to retrieve. + +[[alerts-api-get-codes]] +==== Response code + +`200`:: + Indicates a successful call. + +[[alerts-api-get-example]] +==== Example + +Retrieve the alert object with the ID `41893910-6bca-11eb-9e0d-85d233e3ee35`: + +[source,sh] +-------------------------------------------------- +$ curl -X GET api/alerts/alert/41893910-6bca-11eb-9e0d-85d233e3ee35 +-------------------------------------------------- +// KIBANA + +The API returns the following: + +[source,sh] +-------------------------------------------------- +{ + "id": "0a037d60-6b62-11eb-9e0d-85d233e3ee35", + "notifyWhen": "onActionGroupChange", + "params": { + "aggType": "avg", + }, + "consumer": "alerts", + "alertTypeId": "test.alert.type", + "schedule": { + "interval": "1m" + }, + "actions": [], + "tags": [], + "name": "test alert", + "enabled": true, + "throttle": null, + "apiKeyOwner": "elastic", + "createdBy": "elastic", + "updatedBy": "elastic", + "muteAll": false, + "mutedInstanceIds": [], + "updatedAt": "2021-02-10T05:37:19.086Z", + "createdAt": "2021-02-10T05:37:19.086Z", + "scheduledTaskId": "0b092d90-6b62-11eb-9e0d-85d233e3ee35", + "executionStatus": { + "lastExecutionDate": "2021-02-10T17:55:14.262Z", + "status": "ok" + } +} +-------------------------------------------------- diff --git a/docs/api/alerts/health.asciidoc b/docs/api/alerts/health.asciidoc new file mode 100644 index 00000000000000..3710ccf4249454 --- /dev/null +++ b/docs/api/alerts/health.asciidoc @@ -0,0 +1,85 @@ +[[alerts-api-health]] +=== Get Alerting framework health API +++++ +Get Alerting framework health +++++ + +Retrieve the health status of the Alerting framework. + +[[alerts-api-health-request]] +==== Request + +`GET :/api/alerts/_health` + +[[alerts-api-health-codes]] +==== Response code + +`200`:: + Indicates a successful call. + +[[alerts-api-health-example]] +==== Example + +Retrieve the health status of the Alerting framework: + +[source,sh] +-------------------------------------------------- +$ curl -X GET api/alerts/_health +-------------------------------------------------- +// KIBANA + +The API returns the following: + +[source,sh] +-------------------------------------------------- +{ + "isSufficientlySecure":true, + "hasPermanentEncryptionKey":true, + "alertingFrameworkHeath":{ + "decryptionHealth":{ + "status":"ok", + "timestamp":"2021-02-10T23:35:04.949Z" + }, + "executionHealth":{ + "status":"ok", + "timestamp":"2021-02-10T23:35:04.949Z" + }, + "readHealth":{ + "status":"ok", + "timestamp":"2021-02-10T23:35:04.949Z" + } + } +} +-------------------------------------------------- + +The health API response contains the following properties: + +[cols="2*<"] +|=== + +| `isSufficientlySecure` +| Returns `false` if security is enabled, but TLS is not. + +| `hasPermanentEncryptionKey` +| Return the state `false` if Encrypted Saved Object plugin has not a permanent encryption Key. + +| `alertingFrameworkHeath` +| This state property has three substates that identify the health of the alerting framework API: `decryptionHealth`, `executionHealth`, and `readHealth`. + +|=== + +`alertingFrameworkHeath` consists of the following properties: + +[cols="2*<"] +|=== + +| `decryptionHealth` +| Returns the timestamp and status of the alert decryption: `ok`, `warn` or `error` . + +| `executionHealth` +| Returns the timestamp and status of the alert execution: `ok`, `warn` or `error`. + +| `readHealth` +| Returns the timestamp and status of the alert reading events: `ok`, `warn` or `error`. + +|=== diff --git a/docs/api/alerts/list.asciidoc b/docs/api/alerts/list.asciidoc new file mode 100644 index 00000000000000..0bc3e158ec2634 --- /dev/null +++ b/docs/api/alerts/list.asciidoc @@ -0,0 +1,127 @@ +[[alerts-api-list]] +=== List alert types API +++++ +List all alert types API +++++ + +Retrieve a list of all alert types. + +[[alerts-api-list-request]] +==== Request + +`GET :/api/alerts/list_alert_types` + +[[alerts-api-list-codes]] +==== Response code + +`200`:: + Indicates a successful call. + +[[alerts-api-list-example]] +==== Example + +[source,sh] +-------------------------------------------------- +$ curl -X GET api/alerts/list_alert_types +-------------------------------------------------- +// KIBANA + +The API returns the following: + +[source,sh] +-------------------------------------------------- +[ + { + "id":".index-threshold", + "name":"Index threshold", + "actionGroups":[ + { + "id":"threshold met", + "name":"Threshold met" + }, + { + "id":"recovered", + "name":"Recovered" + } + ], + "recoveryActionGroup":{ + "id":"recovered", + "name":"Recovered" + }, + "defaultActionGroupId":"threshold met", + "actionVariables":{ + "context":[ + { + "name":"message", + "description":"A pre-constructed message for the alert." + }, + ], + "state":[], + "params":[ + { + "name":"threshold", + "description":"An array of values to use as the threshold; 'between' and 'notBetween' require two values, the others require one." + }, + { + "name":"index", + "description":"index" + }, + ] + }, + "producer":"stackAlerts", + "minimumLicenseRequired":"basic", + "enabledInLicense":true, + "authorizedConsumers":{ + "alerts":{ + "read":true, + "all":true + }, + "stackAlerts":{ + "read":true, + "all":true + }, + "uptime":{ + "read":true, + "all":true + } + } + } +] +-------------------------------------------------- + +Each alert type contains the following properties: + +[cols="2*<"] +|=== + +| `name` +| The descriptive name of the alert type. + +| `id` +| The unique ID of the alert type. + +| `minimumLicenseRequired` +| The license required to use the alert type. + +| `enabledInLicense` +| Whether the alert type is enabled or disabled based on the license. + +| `actionGroups` +| An explicit list of groups for which the alert type can schedule actions, each with the action group's unique ID and human readable name. Alert `actions` validation will use this configuration to ensure that groups are valid. Use `kbn-i18n` to translate the names of the action group when registering the alert type. + +| `recoveryActionGroup` +| An action group to use when an alert instance goes from an active state, to an inactive one. Do not specify this action group under the `actionGroups` property. If `recoveryActionGroup` is not specified, the default `recovered` action group is used. + +| `defaultActionGroupId` +| The default ID for the alert type group. + +| `actionVariables` +| An explicit list of action variables that the alert type makes available via context and state in action parameter templates, and a short human readable description. The Alert UI will use this information to prompt users for these variables in action parameter editors. Use `kbn-i18n` to translate the descriptions. + +| `producer` +| The ID of the application producing this alert type. + +| `authorizedConsumers` +| The list of the plugins IDs that have access to the alert type. + +|=== diff --git a/docs/api/alerts/mute.asciidoc b/docs/api/alerts/mute.asciidoc new file mode 100644 index 00000000000000..9279786deae4cf --- /dev/null +++ b/docs/api/alerts/mute.asciidoc @@ -0,0 +1,37 @@ +[[alerts-api-mute]] +=== Mute alert instance API +++++ +Mute alert instance +++++ + +Mute an alert instance. + +[[alerts-api-mute-request]] +==== Request + +`POST :/api/alerts/alert//alert_instance//_mute` + +[[alerts-api-mute-path-params]] +==== Path parameters + +`id`:: + (Required, string) The ID of the alert whose instance you want to mute. + +`alert_instance_id`:: + (Required, string) The ID of the alert instance that you want to mute. + +[[alerts-api-mute-response-codes]] +==== Response code + +`200`:: + Indicates a successful call. + +==== Example + +Mute alert instance with ID: + +[source,sh] +-------------------------------------------------- +$ curl -X POST api/alerts/alert/41893910-6bca-11eb-9e0d-85d233e3ee35/alert_instance/dceeb5d0-6b41-11eb-802b-85b0c1bc8ba2/_mute +-------------------------------------------------- +// KIBANA diff --git a/docs/api/alerts/mute_all.asciidoc b/docs/api/alerts/mute_all.asciidoc new file mode 100644 index 00000000000000..f8a8c137240c6b --- /dev/null +++ b/docs/api/alerts/mute_all.asciidoc @@ -0,0 +1,34 @@ +[[alerts-api-mute-all]] +=== Mute all alert instances API +++++ +Mute all alert instances +++++ + +Mute all alert instances. + +[[alerts-api-mute-all-request]] +==== Request + +`POST :/api/alerts/alert//_mute_all` + +[[alerts-api-mute-all-path-params]] +==== Path parameters + +`id`:: + (Required, string) The ID of the alert whose instances you want to mute. + +[[alerts-api-mute-all-response-codes]] +==== Response code + +`200`:: + Indicates a successful call. + +==== Example + +Mute all alert instances with ID: + +[source,sh] +-------------------------------------------------- +$ curl -X POST api/alerts/alert/41893910-6bca-11eb-9e0d-85d233e3ee35/_mute_all +-------------------------------------------------- +// KIBANA diff --git a/docs/api/alerts/unmute.asciidoc b/docs/api/alerts/unmute.asciidoc new file mode 100644 index 00000000000000..f091ae3f453257 --- /dev/null +++ b/docs/api/alerts/unmute.asciidoc @@ -0,0 +1,37 @@ +[[alerts-api-unmute]] +=== Unmute alert instance API +++++ +Unmute alert instance +++++ + +Unmute an alert instance. + +[[alerts-api-unmute-request]] +==== Request + +`POST :/api/alerts/alert//alert_instance//_unmute` + +[[alerts-api-unmute-path-params]] +==== Path parameters + +`id`:: + (Required, string) The ID of the alert whose instance you want to mute.. + +`alert_instance_id`:: + (Required, string) The ID of the alert instance that you want to unmute. + +[[alerts-api-unmute-response-codes]] +==== Response code + +`200`:: + Indicates a successful call. + +==== Example + +Unmute alert instance with ID: + +[source,sh] +-------------------------------------------------- +$ curl -X POST api/alerts/alert/41893910-6bca-11eb-9e0d-85d233e3ee35/alert_instance/dceeb5d0-6b41-11eb-802b-85b0c1bc8ba2/_unmute +-------------------------------------------------- +// KIBANA diff --git a/docs/api/alerts/unmute_all.asciidoc b/docs/api/alerts/unmute_all.asciidoc new file mode 100644 index 00000000000000..2359d120cf2602 --- /dev/null +++ b/docs/api/alerts/unmute_all.asciidoc @@ -0,0 +1,34 @@ +[[alerts-api-unmute-all]] +=== Unmute all alert instances API +++++ +Unmute all alert instances +++++ + +Unmute all alert instances. + +[[alerts-api-unmute-all-request]] +==== Request + +`POST :/api/alerts/alert//_unmute_all` + +[[alerts-api-unmute-all-path-params]] +==== Path parameters + +`id`:: + (Required, string) The ID of the alert whose instances you want to unmute. + +[[alerts-api-unmute-all-response-codes]] +==== Response code + +`200`:: + Indicates a successful call. + +==== Example + +Unmute all alert instances with ID: + +[source,sh] +-------------------------------------------------- +$ curl -X POST api/alerts/alert/41893910-6bca-11eb-9e0d-85d233e3ee35/_unmute_all +-------------------------------------------------- +// KIBANA diff --git a/docs/api/alerts/update.asciidoc b/docs/api/alerts/update.asciidoc new file mode 100644 index 00000000000000..aee2dd049a66f7 --- /dev/null +++ b/docs/api/alerts/update.asciidoc @@ -0,0 +1,134 @@ +[[alerts-api-update]] +=== Update alert API +++++ +Update alert +++++ + +Update the attributes for an existing alert. + +[[alerts-api-update-request]] +==== Request + +`PUT :/api/alerts/alert/` + +[[alerts-api-update-path-params]] +==== Path parameters + +`id`:: + (Required, string) The ID of the alert that you want to update. + +[[alerts-api-update-request-body]] +==== Request body + +`name`:: + (Required, string) A name to reference and search. + +`tags`:: + (Optional, string array) A list of keywords to reference and search. + +`schedule`:: + (Required, object) When to run this alert. Use one of the available schedule formats. ++ +._Schedule Formats_. +[%collapsible%open] +===== +A schedule uses a key: value format. {kib} currently supports the _Interval format_ , which specifies the interval in seconds, minutes, hours, or days at which to execute the alert. + +Example: `{ interval: "10s" }`, `{ interval: "5m" }`, `{ interval: "1h" }`, `{ interval: "1d" }`. + +===== + +`throttle`:: + (Optional, string) How often this alert should fire the same actions. This will prevent the alert from sending out the same notification over and over. For example, if an alert with a `schedule` of 1 minute stays in a triggered state for 90 minutes, setting a `throttle` of `10m` or `1h` will prevent it from sending 90 notifications during this period. + +`notifyWhen`:: + (Required, string) The condition for throttling the notification: `onActionGroupChange`, `onActiveAlert`, or `onThrottleInterval`. + +`params`:: + (Required, object) The parameters to pass to the alert type executor `params` value. This will also validate against the alert type params validator, if defined. + +`actions`:: + (Optional, object array) An array of the following action objects. ++ +.Properties of the action objects: +[%collapsible%open] +===== + `group`::: + (Required, string) Grouping actions is recommended for escalations for different types of alert instances. If you don't need this, set the value to `default`. + + `id`::: + (Required, string) The ID of the action that saved object executes. + + `actionTypeId`::: + (Required, string) The id of the <>. + + `params`::: + (Required, object) The map to the `params` that the <> will receive. `params` are handled as Mustache templates and passed a default set of context. +===== + + +[[alerts-api-update-errors-codes]] +==== Response code + +`200`:: + Indicates a successful call. + +[[alerts-api-update-example]] +==== Example + +Update an alert with ID `ac4e6b90-6be7-11eb-ba0d-9b1c1f912d74` with a different name: + +[source,sh] +-------------------------------------------------- +$ curl -X PUT api/alerts/alert/ac4e6b90-6be7-11eb-ba0d-9b1c1f912d74 + +{ + "notifyWhen": "onActionGroupChange", + "params": { + "aggType": "avg", + }, + "schedule": { + "interval": "1m" + }, + "actions": [], + "tags": [], + "name": "new name", + "throttle": null, +} +-------------------------------------------------- +// KIBANA + +The API returns the following: + +[source,sh] +-------------------------------------------------- +{ + "id": "ac4e6b90-6be7-11eb-ba0d-9b1c1f912d74", + "notifyWhen": "onActionGroupChange", + "params": { + "aggType": "avg", + }, + "consumer": "alerts", + "alertTypeId": "test.alert.type", + "schedule": { + "interval": "1m" + }, + "actions": [], + "tags": [], + "name": "new name", + "enabled": true, + "throttle": null, + "apiKeyOwner": "elastic", + "createdBy": "elastic", + "updatedBy": "elastic", + "muteAll": false, + "mutedInstanceIds": [], + "updatedAt": "2021-02-10T05:37:19.086Z", + "createdAt": "2021-02-10T05:37:19.086Z", + "scheduledTaskId": "0b092d90-6b62-11eb-9e0d-85d233e3ee35", + "executionStatus": { + "lastExecutionDate": "2021-02-10T17:55:14.262Z", + "status": "ok" + } +} +-------------------------------------------------- diff --git a/docs/user/api.asciidoc b/docs/user/api.asciidoc index 2ae83bee1e06c7..9916ab42186dc6 100644 --- a/docs/user/api.asciidoc +++ b/docs/user/api.asciidoc @@ -36,6 +36,7 @@ include::{kib-repo-dir}/api/features.asciidoc[] include::{kib-repo-dir}/api/spaces-management.asciidoc[] include::{kib-repo-dir}/api/role-management.asciidoc[] include::{kib-repo-dir}/api/saved-objects.asciidoc[] +include::{kib-repo-dir}/api/alerts.asciidoc[] include::{kib-repo-dir}/api/actions-and-connectors.asciidoc[] include::{kib-repo-dir}/api/dashboard-api.asciidoc[] include::{kib-repo-dir}/api/logstash-configuration-management.asciidoc[]