[8.15] Security AI Assistant APIs (backport #5620)

docs/AI-for-security/api/ai-for-security-index.asciidoc

@@ -0,0 +1,14 @@
+include::assistant-api-overview.asciidoc[]
+
+include::chat-complete-api.asciidoc[]
+
+include::conversation-api-create.asciidoc[]
+
+include::conversation-api-delete.asciidoc[]
+
+include::conversation-api-find.asciidoc[]
+
+include::conversation-api-get.asciidoc[]
+
+include::conversation-api-update.asciidoc[]
+

docs/AI-for-security/api/assistant-api-overview.asciidoc

@@ -0,0 +1,5 @@
+[[assistant-api-overview]]
+[role="xpack"]
+== Elastic AI Assistant API
+
+The Elastic AI Assistant API allows you to interact with and manage Elastic AI Assistant.

docs/AI-for-security/api/conversation-api-create.asciidoc

@@ -0,0 +1,148 @@
+[[conversation-api-create]]
+=== Create conversation
+
+Create a new Elastic AI Assistant conversation.
+
+[discrete]
+=== Request URL
+
+`POST <kibana host>:<port>/api/security_ai_assistant/current_user/conversations`
+
+[discrete]
+=== Request body
+
+[width="100%",options="header"]
+|==============================================
+|Name |Type |Description |Required
+
+|`title` |String |Conversation title. If you set it to "New chat", the AI will generate a title. |Yes
+|`category` |String |Can be "assistant", "insights", or not defined. |No
+|`isDefault` |Boolean |Define if conversation is a system conversation which cannot be deleted. Defaults to false. |No
+|`excludeFromLastConversationStorage` |Boolean |Defines if conversation can appear as the latest conversation. |No
+|`apiConfig` |<<create-apiconfig-obj,apiConfig object>> |Conversation configuration. |No
+|`messages` |<<create-message-obj,messages object>> |Array of conversation messages. |No
+|`replacements` |Key, Value(String, String)|List of the fields with anonymization. |No
+|==============================================
+
+[discrete]
+[[create-apiconfig-obj]]
+== `apiConfig` object
+
+[width="100%",options="header"]
+|==============================================
+|Name |Type |Description |Required
+
+|`connectorId` |String |Kibana connector ID. |Yes
+|`actionTypeId` |String |Kibana connector action type ID. |Yes
+|`defaultSystemPromptId` |String |Default system prompt ID. |Yes
+|`model` |String |Specific LLM name. |No
+|==============================================
+
+[discrete]
+[[create-message-obj]]
+== `messages` object
+
+[width="100%",options="header"]
+|==============================================
+|Name |Type |Description |Required
+
+|`role` |String |Message role. Can be "user", "assistant", or "system". |Yes
+|`content` |String |Message content to send to LLM. |Yes
+|`isError` |Boolean |Define if the message is an error message instead of an LLM response. |No
+|`timestamp` |String |Timestamp when the message was sent. |No
+|==============================================
+
+[discrete]
+=== Example requests
+
+*Example 1*
+
+Creates a new conversation.
+
+[source,console]
+--------------------------------------------------
+POST api/security_ai_assistant/current_user/conversations
+{
+  "title": "The conversation title.",
+  "category": "assistant",
+  "messages": [
+    {
+      "content": "test content",
+      "role": "user",
+      "isError": false,
+      "timestamp": "2019-12-13T16:40:33.400Z",
+      "traceData": {
+        "traceId": "1234",
+        "transactionId": "2"
+      }
+    }
+  ],
+  "apiConfig": {
+    "actionTypeId": ".gen-ai",
+    "connectorId": "86ab-471c-a00b-25b7e20c2d12",
+    "defaultSystemPromptId": "Default",
+    "model": "gpt-4o"
+  },
+  "isDefault": false,
+  "excludeFromLastConversationStorage": true,
+  "replacements": {
+    "field1": "914beb92-86ab-471c-a00b"
+  }
+}
+--------------------------------------------------
+
+[discrete]
+=== Response code
+
+`200`
+    Indicates a successful call.
+
+[discrete]
+=== Response payload
+
+A JSON conversation object with a unique `id`.
+
+*Example 1*
+
+Conversation response payload:
+
+[source,json]
+--------------------------------------------------
+{
+  "id": "07805df2-6462-451a-b534-78da47873c42",
+  "title": "The conversation title.",
+  "category": "assistant",
+  "timestamp": "2024-07-29T06:58:15.670Z",
+  "updatedAt": "2024-07-29T06:58:15.670Z",
+  "createdAt": "2024-07-29T06:58:15.670Z",
+  "replacements": {
+    "field1": "914beb92-86ab-471c-a00b"
+  },
+  "users": [
+    {
+      "name": "elastic"
+    }
+  ],
+  "messages": [
+    {
+      "content": "test content",
+      "role": "user",
+      "timestamp": "2019-12-13T16:40:33.400Z",
+      "traceData": {
+        "transactionId": "2",
+        "traceId": "1234"
+      }
+    }
+  ],
+  "apiConfig": {
+    "connectorId": "86ab-471c-a00b-25b7e20c2d12",
+    "actionTypeId": ".gen-ai",
+    "defaultSystemPromptId": "Default",
+    "model": "gpt-4o"
+  },
+  "isDefault": false,
+  "excludeFromLastConversationStorage": true,
+  "namespace": "default"
+}
+--------------------------------------------------
+

docs/AI-for-security/api/conversation-api-delete.asciidoc

@@ -0,0 +1,44 @@
+[[conversation-api-delete]]
+=== Delete conversation
+
+Delete an existing Elastic AI Assistant conversation by conversation ID.
+
+[discrete]
+=== Request URL
+
+`DELETE <kibana host>:<port>/api/security_ai_assistant/current_user/conversations/{id}`
+
+
+[discrete]
+=== Example requests
+
+*Example 1*
+
+Deletes an Elastic AI Assistant conversation with an `id` value of `df071e68-3c8e-4c0d-b0e7-1557e80c0319`:
+
+[source,console]
+--------------------------------------------------
+DELETE api/security_ai_assistant/current_user/conversations/df071e68-3c8e-4c0d-b0e7-1557e80c0319
+
+--------------------------------------------------
+
+[discrete]
+=== Response code
+
+`200`
+    Indicates a successful call.
+
+[discrete]
+=== Response payload
+
+An empty JSON object.
+
+*Example 1*
+
+Response payload:
+
+[source,json]
+--------------------------------------------------
+{} 
+--------------------------------------------------
+

docs/AI-for-security/api/conversation-api-find.asciidoc

@@ -0,0 +1,110 @@
+[[conversation-api-find]]
+=== Find conversations
+
+Retrieve a list of Elastic AI Assistant conversations for the current user.
+
+[discrete]
+=== Request URL
+
+`GET <kibana host>:<port>/api/security_ai_assistant/current_user/conversations/_find`
+
+==== URL query parameters
+
+[width="100%",options="header"]
+|==============================================
+|Name |Type |Description |Required
+
+|`page` |Number |The page number to return. Defaults to `1`.
+|No
+|`per_page` |Number |The number of items to return per page. Defaults to `10`.
+|No
+|`filter` |String |The filter query to apply on the request.
+|No
+|`sort_field` |String a|The field to sort the results by. Valid values are:
+
+* `title`
+* `description`
+* `updated`
+* `created`
+
+|No
+|`sort_order` |String a|The order to sort the results in. Valid values are:
+
+* `asc`
+* `desc`
+
+|No
+|`fields` |String a|Defines the fields of the document to return in the response.
+
+|No
+
+|==============================================
+
+[discrete]
+=== Example requests
+
+*Example 1*
+
+Get a list of the current user's conversations.
+
+[source,console]
+--------------------------------------------------
+GET api/security_ai_assistant/current_user/conversations/_find?page=1&per_page=100
+--------------------------------------------------
+
+[discrete]
+=== Response code
+
+`200`
+    Indicates a successful call.
+
+[discrete]
+=== Response payload
+
+A JSON conversation object with a unique `id`.
+
+*Example 1*
+
+Conversation response payload:
+
+[source,json]
+--------------------------------------------------
+{
+  "perPage": 20,
+  "page": 1,
+  "total": 1,
+  "data": [
+    {
+      "timestamp": "2024-08-02T07:19:08.124Z",
+      "createdAt": "2024-08-02T07:19:08.124Z",
+      "users": [
+        {
+          "id": "u_mGBROF_q5bmFCATbLXAcCwKa0k8JvONAwSruelyKA5E_0",
+          "name": "elastic"
+        }
+      ],
+      "title": "The conversation title.",
+      "category": "assistant",
+      "apiConfig": {
+        "connectorId": "86ab-471c-a00b-25b7e20c2d12",
+        "actionTypeId": ".gen-ai",
+        "defaultSystemPromptId": "Default",
+        "model": "gpt-4o"
+      },
+      "isDefault": true,
+      "messages": [
+        {
+          "timestamp": "2019-12-13T16:40:33.400Z",
+          "content": "test content",
+          "role": "user"
+        }
+      ],
+      "updatedAt": "2024-08-02T07:39:45.129Z",
+      "replacements": {},
+      "namespace": "default",
+      "id": "a696901d-efff-4871-acbe-8123af841932"
+    }
+  ]
+}
+--------------------------------------------------
+

docs/AI-for-security/api/conversation-api-get.asciidoc

@@ -0,0 +1,63 @@
+[[conversation-api-get]]
+=== Get conversation
+
+Retrieve an existing Elastic AI Assistant conversation by conversation ID.
+
+[discrete]
+=== Request URL
+
+`GET <kibana host>:<port>/api/security_ai_assistant/current_user/conversations/{id}`
+
+[discrete]
+=== Example requests
+
+*Example 1*
+
+Retrieves an Elastic AI Assistant conversation with an `id` value of `a696901d-efff-4871-acbe-8123af841932`:
+
+[source,console]
+--------------------------------------------------
+GET api/security_ai_assistant/current_user/conversations/a696901d-efff-4871-acbe-8123af841932
+--------------------------------------------------
+
+[discrete]
+=== Response code
+
+`200`
+    Indicates a successful call.
+
+[discrete]
+=== Response payload
+
+A JSON conversation object with a unique `id`.
+
+*Example 1*
+
+Conversation response payload:
+
+[source,json]
+--------------------------------------------------
+{
+  "timestamp": "2024-08-02T07:19:08.124Z",
+  "createdAt": "2024-08-02T07:19:08.124Z",
+  "users": [
+    {
+      "id": "u_mGBROF_q5bmFCATbLXAcCwKa0k8JvONAwSruelyKA5E_0",
+      "name": "elastic"
+    }
+  ],
+  "title": "Welcome",
+  "category": "assistant",
+  "apiConfig": {
+    "connectorId": "my-gpt4o-ai",
+    "actionTypeId": ".gen-ai"
+  },
+  "isDefault": true,
+  "messages": [],
+  "updatedAt": "2024-08-02T07:19:08.124Z",
+  "replacements": {},
+  "namespace": "default",
+  "id": "a696901d-efff-4871-acbe-8123af841932"
+}
+--------------------------------------------------
+