[Actions][Docs] Actions and Connectors API Docs (#90974)

* Stubbing out asciidocs

* wip

* Finishing connector API docs

* Cleanup

* Removing experimental label

* PR fixes

* PR fixes

* PR fixes

docs/api/actions-and-connectors.asciidoc

@@ -0,0 +1,30 @@
+[[actions-and-connectors-api]]
+== Action and connector APIs
+
+Manage Actions and Connectors.
+
+The following action APIs are available:
+
+* <<actions-and-connectors-api-get, Get action API>> to retrieve a single action by ID
+
+* <<actions-and-connectors-api-get-all, Get all actions API>> to retrieve all actions
+
+* <<actions-and-connectors-api-list, List all action types API>> to retrieve a list of all action types
+
+* <<actions-and-connectors-api-create, Create action API>> to create actions
+
+* <<actions-and-connectors-api-update, Update action API>> to update the attributes for an existing action
+
+* <<actions-and-connectors-api-execute, Execute action API>> to execute an action by ID
+
+* <<actions-and-connectors-api-delete, Delete action API>> to delete an action by ID
+
+For information about the actions and connectors that {kib} supports, refer to <<action-types,Action and connector types>>.
+
+include::actions-and-connectors/get.asciidoc[]
+include::actions-and-connectors/get_all.asciidoc[]
+include::actions-and-connectors/list.asciidoc[]
+include::actions-and-connectors/create.asciidoc[]
+include::actions-and-connectors/update.asciidoc[]
+include::actions-and-connectors/execute.asciidoc[]
+include::actions-and-connectors/delete.asciidoc[]

docs/api/actions-and-connectors/create.asciidoc

@@ -0,0 +1,68 @@
+[[actions-and-connectors-api-create]]
+=== Create action API
+++++
+<titleabbrev>Create action API</titleabbrev>
+++++
+
+Creates an action.
+
+[[actions-and-connectors-api-create-request]]
+==== Request
+
+`POST <kibana host>:<port>/api/actions/action`
+
+[[actions-and-connectors-api-create-request-body]]
+==== Request body
+
+`name`::
+  (Required, string) The display name for the action.
+
+`actionTypeId`::
+  (Required, string) The action type ID for the action.
+
+`config`::
+  (Required, object) The configuration for the action. Configuration properties vary depending on
+  the action type. For information about the configuration properties, refer to <<action-types,Action and connector types>>.
+
+`secrets`::
+  (Required, object) The secrets configuration for the action. Secrets configuration properties vary
+  depending on the action type. For information about the secrets configuration properties, refer to <<action-types,Action and connector types>>.
+
+[[actions-and-connectors-api-create-request-codes]]
+==== Response code
+
+`200`::
+    Indicates a successful call.
+
+[[actions-and-connectors-api-create-example]]
+==== Example
+
+[source,sh]
+--------------------------------------------------
+$ curl -X POST api/actions/action  -H 'kbn-xsrf: true' -H 'Content-Type: application/json' -d '
+{
+  "name": "my-action",
+  "actionTypeId": ".index",
+  "config": {
+    "index": "test-index"
+  }
+}'
+--------------------------------------------------
+// KIBANA
+
+The API returns the following:
+
+[source,sh]
+--------------------------------------------------
+{
+  "id": "c55b6eb0-6bad-11eb-9f3b-611eebc6c3ad",
+  "actionTypeId": ".index",
+  "name": "my-action",
+  "config": {
+    "index": "test-index",
+    "refresh": false,
+    "executionTimeField": null
+  },
+  "isPreconfigured": false
+}
+--------------------------------------------------

docs/api/actions-and-connectors/delete.asciidoc

@@ -0,0 +1,35 @@
+[[actions-and-connectors-api-delete]]
+=== Delete action API
+++++
+<titleabbrev>Delete action API</titleabbrev>
+++++
+
+Deletes an action by ID.
+
+WARNING: When you delete an action, _it cannot be recovered_.
+
+[[actions-and-connectors-api-delete-request]]
+==== Request
+
+`DELETE <kibana host>:<port>/api/actions/action/<id>`
+
+[[actions-and-connectors-api-delete-path-params]]
+==== Path parameters
+
+`id`::
+  (Required, string) The ID of the action.
+
+[[actions-and-connectors-api-delete-response-codes]]
+==== Response code
+
+`200`::
+  Indicates a successful call.
+
+==== Example
+
+[source,sh]
+--------------------------------------------------
+$ curl -X DELETE api/actions/action/c55b6eb0-6bad-11eb-9f3b-611eebc6c3ad
+--------------------------------------------------
+// KIBANA
+

docs/api/actions-and-connectors/execute.asciidoc

@@ -0,0 +1,83 @@
+[[actions-and-connectors-api-execute]]
+=== Execute action API
+++++
+<titleabbrev>Execute action API</titleabbrev>
+++++
+
+Executes an action by ID.
+
+[[actions-and-connectors-api-execute-request]]
+==== Request
+
+`POST <kibana host>:<port>/api/actions/action/<id>/_execute`
+
+[[actions-and-connectors-api-execute-params]]
+==== Path parameters
+
+`id`::
+  (Required, string) The ID of the action.
+
+[[actions-and-connectors-api-execute-request-body]]
+==== Request body
+
+`params`::
+  (Required, object) The parameters of the action. Parameter properties vary depending on
+  the action type. For information about the parameter properties, refer to <<action-types,Action and connector types>>.
+
+[[actions-and-connectors-api-execute-codes]]
+==== Response code
+
+`200`::
+    Indicates a successful call.
+
+[[actions-and-connectors-api-execute-example]]
+==== Example
+
+[source,sh]
+--------------------------------------------------
+$ curl -X POST api/actions/action/c55b6eb0-6bad-11eb-9f3b-611eebc6c3ad/_execute  -H 'kbn-xsrf: true' -H 'Content-Type: application/json' -d '
+{
+  "params": {
+    "documents": [
+      {
+        "id": "test_doc_id",
+        "name": "test_doc_name",
+        "message": "hello, world"
+      }
+    ]
+  }
+}'
+--------------------------------------------------
+// KIBANA
+
+The API returns the following:
+
+[source,sh]
+--------------------------------------------------
+{
+  "status": "ok",
+  "data": {
+    "took": 197,
+    "errors": false,
+    "items": [
+      {
+        "index": {
+          "_index": "updated-index",
+          "_id": "iKyijHcBKCsmXNFrQe3T",
+          "_version": 1,
+          "result": "created",
+          "_shards": {
+            "total": 2,
+            "successful": 1,
+            "failed": 0
+          },
+          "_seq_no": 0,
+          "_primary_term": 1,
+          "status": 201
+        }
+      }
+    ]
+  },
+  "actionId": "c55b6eb0-6bad-11eb-9f3b-611eebc6c3ad"
+}
+--------------------------------------------------

docs/api/actions-and-connectors/get.asciidoc

@@ -0,0 +1,50 @@
+[[actions-and-connectors-api-get]]
+=== Get action API
+++++
+<titleabbrev>Get action API</titleabbrev>
+++++
+
+Retrieves an action by ID.
+
+[[actions-and-connectors-api-get-request]]
+==== Request
+
+`GET <kibana host>:<port>/api/actions/action/<id>`
+
+[[actions-and-connectors-api-get-params]]
+==== Path parameters
+
+`id`::
+  (Required, string) The ID of the action.
+
+[[actions-and-connectors-api-get-codes]]
+==== Response code
+
+`200`::
+    Indicates a successful call.
+
+[[actions-and-connectors-api-get-example]]
+==== Example
+
+[source,sh]
+--------------------------------------------------
+$ curl -X GET api/actions/action/c55b6eb0-6bad-11eb-9f3b-611eebc6c3ad
+--------------------------------------------------
+// KIBANA
+
+The API returns the following:
+
+[source,sh]
+--------------------------------------------------
+{
+  "id": "c55b6eb0-6bad-11eb-9f3b-611eebc6c3ad",
+  "actionTypeId": ".index",
+  "name": "my-action",
+  "config": {
+    "index": "test-index",
+    "refresh": false,
+    "executionTimeField": null
+  },
+  "isPreconfigured": false
+}
+--------------------------------------------------

docs/api/actions-and-connectors/get_all.asciidoc

@@ -0,0 +1,52 @@
+[[actions-and-connectors-api-get-all]]
+=== Get all actions API
+++++
+<titleabbrev>Get all actions API</titleabbrev>
+++++
+
+Retrieves all actions.
+
+[[actions-and-connectors-api-get-all-request]]
+==== Request
+
+`GET <kibana host>:<port>/api/actions`
+
+[[actions-and-connectors-api-get-all-codes]]
+==== Response code
+
+`200`::
+    Indicates a successful call.
+
+[[actions-and-connectors-api-get-all-example]]
+==== Example
+
+[source,sh]
+--------------------------------------------------
+$ curl -X GET api/actions
+--------------------------------------------------
+// KIBANA
+
+The API returns the following:
+
+[source,sh]
+--------------------------------------------------
+[
+  {
+    "id": "preconfigured-mail-action",
+    "actionTypeId": ".email",
+    "name": "email: preconfigured-mail-action",
+    "isPreconfigured": true
+  },
+  {
+    "id": "c55b6eb0-6bad-11eb-9f3b-611eebc6c3ad",
+    "actionTypeId": ".index",
+    "name": "my-action",
+    "config": {
+      "index": "test-index",
+      "refresh": false,
+      "executionTimeField": null
+    },
+    "isPreconfigured": false
+  }
+]
+--------------------------------------------------

docs/api/actions-and-connectors/list.asciidoc

@@ -0,0 +1,59 @@
+[[actions-and-connectors-api-list]]
+=== List action types API
+++++
+<titleabbrev>List all action types API</titleabbrev>
+++++
+
+Retrieves a list of all action types.
+
+[[actions-and-connectors-api-list-request]]
+==== Request
+
+`GET <kibana host>:<port>/api/actions/list_action_types`
+
+[[actions-and-connectors-api-list-codes]]
+==== Response code
+
+`200`::
+    Indicates a successful call.
+
+[[actions-and-connectors-api-list-example]]
+==== Example
+
+[source,sh]
+--------------------------------------------------
+$ curl -X GET api/actions/list_action_types
+--------------------------------------------------
+// KIBANA
+
+The API returns the following:
+
+[source,sh]
+--------------------------------------------------
+[
+  {
+    "id": ".email", <1>
+    "name": "Email", <2>
+    "minimumLicenseRequired": "gold", <3>
+    "enabled": false, <4>
+    "enabledInConfig": true, <5>
+    "enabledInLicense": false <6>
+  },
+  {
+    "id": ".index",
+    "name": "Index",
+    "minimumLicenseRequired": "basic",
+    "enabled": true,
+    "enabledInConfig": true,
+    "enabledInLicense": true
+  }
+]
+--------------------------------------------------
+
+
+<1> `id` - The unique ID of the action type.
+<2> `name` - The name of the action type.
+<3> `minimumLicenseRequired` - The license required to use the action type.
+<4> `enabled` - Specifies if the action type is enabled or disabled in {kib}.
+<5> `enabledInConfig` - Specifies if the action type is enabled or enabled in the {kib} .yml file.
+<6> `enabledInLicense` - Specifies if the action type is enabled or disabled in the license.

docs/api/actions-and-connectors/update.asciidoc

@@ -0,0 +1,68 @@
+[[actions-and-connectors-api-update]]
+=== Update action API
+++++
+<titleabbrev>Update action API</titleabbrev>
+++++
+
+Updates the attributes for an existing action.
+
+[[actions-and-connectors-api-update-request]]
+==== Request
+
+`PUT <kibana host>:<port>/api/actions/action/<id>`
+
+[[actions-and-connectors-api-update-params]]
+==== Path parameters
+
+`id`::
+  (Required, string) The ID of the action.
+
+[[actions-and-connectors-api-update-request-body]]
+==== Request body
+
+`name`::
+  (Required, string) The new name of the action.
+
+`config`::
+  (Required, object) The new action configuration. Configuration properties vary depending on the action type. For information about the configuration properties, refer to <<action-types,Action and connector types>>.
+
+`secrets`::
+  (Required, object) The updated secrets configuration for the action. Secrets properties vary depending on the action type. For information about the secrets configuration properties, refer to <<action-types,Action and connector types>>.
+
+[[actions-and-connectors-api-update-codes]]
+==== Response code
+
+`200`::
+    Indicates a successful call.
+
+[[actions-and-connectors-api-update-example]]
+==== Example
+
+[source,sh]
+--------------------------------------------------
+$ curl -X PUT api/actions/action/c55b6eb0-6bad-11eb-9f3b-611eebc6c3ad  -H 'kbn-xsrf: true' -H 'Content-Type: application/json' -d '
+{
+  "name": "updated-action",
+  "config": {
+    "index": "updated-index"
+  }
+}'
+--------------------------------------------------
+// KIBANA
+
+The API returns the following:
+
+[source,sh]
+--------------------------------------------------
+{
+  "id": "c55b6eb0-6bad-11eb-9f3b-611eebc6c3ad",
+  "actionTypeId": ".index",
+  "name": "updated-action",
+  "config": {
+    "index": "updated-index",
+    "refresh": false,
+    "executionTimeField": null
+  },
+  "isPreconfigured": false
+}
+--------------------------------------------------

docs/user/alerting/action-types/email.asciidoc

@@ -37,6 +37,7 @@ Password::  password for 'login' type authentication.
      password: passwordkeystorevalue
 --
 
+[[email-connector-config-properties]]
 `config` defines the action type specific to the configuration and contains the following properties:
 
 [cols="2*<"]

docs/user/alerting/action-types/index.asciidoc

@@ -30,6 +30,7 @@ Execution time field::  This field will be automatically set to the time the ale
      executionTimeField: somedate
 --
 
+[[index-connector-config-properties]]
 `config` defines the action type specific to the configuration and contains the following properties:
 
 [cols="2*<"]

docs/user/alerting/action-types/jira.asciidoc

@@ -33,6 +33,7 @@ API token (or password)::  Jira API authentication token (or password) for HTTP
      apiToken: tokenkeystorevalue
 --
 
+[[jira-connector-config-properties]]
 `config` defines the action type specific to the configuration and contains the following properties:
 
 [cols="2*<"]

docs/user/alerting/action-types/pagerduty.asciidoc

@@ -150,6 +150,7 @@ Integration Key::   A 32 character PagerDuty Integration Key for an integration
      routingKey: testroutingkey
 --
 
+[[pagerduty-connector-config-properties]]
 `config` defines the action type specific to the configuration.
 `config` contains
 `apiURL`, a string that corresponds to *API URL*.

docs/user/alerting/action-types/resilient.asciidoc

@@ -33,6 +33,7 @@ API key secret::  The authentication key secret for HTTP Basic authentication.
      apiKeySecret: tokenkeystorevalue
 --
 
+[[resilient-connector-config-properties]]
 `config` defines the action type specific to the configuration and contains the following properties:
 
 [cols="2*<"]

docs/user/alerting/action-types/servicenow.asciidoc

@@ -31,6 +31,7 @@ Password::  Password for HTTP Basic authentication.
      password: passwordkeystorevalue
 --
 
+[[servicenow-connector-config-properties]]
 `config` defines the action type specific to the configuration and contains the following properties:
 
 [cols="2*<"]

docs/user/alerting/action-types/slack.asciidoc

@@ -26,6 +26,7 @@ Webhook URL::   The URL of the incoming webhook. See https://api.slack.com/messa
      webhookUrl: 'https://hooks.slack.com/services/abcd/efgh/ijklmnopqrstuvwxyz'
 --
 
+[[slack-connector-config-properties]]
 `config` defines the action type specific to the configuration.
 `config` contains
 `webhookUrl`, a string that corresponds to *Webhook URL*.

docs/user/alerting/action-types/teams.asciidoc

@@ -26,6 +26,7 @@ Webhook URL::   The URL of the incoming webhook. See https://docs.microsoft.com/
      webhookUrl: 'https://outlook.office.com/webhook/abcd@0123456/IncomingWebhook/abcdefgh/ijklmnopqrstuvwxyz'
 --
 
+[[teams-connector-config-properties]]
 `config` defines the action type specific to the configuration.
 `config` contains
 `webhookUrl`, a string that corresponds to *Webhook URL*.

docs/user/alerting/action-types/webhook.asciidoc

@@ -36,6 +36,7 @@ Password::  An optional password. If set, HTTP basic authentication is used. Cur
      password: passwordkeystorevalue
 --
 
+[[webhook-connector-config-properties]]
 `config` defines the action type specific to the configuration and contains the following properties:
 
 [cols="2*<"]

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/actions-and-connectors.asciidoc[]
 include::{kib-repo-dir}/api/dashboard-api.asciidoc[]
 include::{kib-repo-dir}/api/logstash-configuration-management.asciidoc[]
 include::{kib-repo-dir}/api/url-shortening.asciidoc[]