[8.15] [Security Assistant] Aligning API Schemas (#188704) (#189077)

# Backport

This will backport the following commits from `main` to `8.15`:
- [[Security Assistant] Aligning API Schemas
(#188704)](#188704)

<!--- Backport version: 9.4.3 -->

### Questions ?
Please refer to the [Backport tool
documentation](https://github.com/sqren/backport)

<!--BACKPORT [{"author":{"name":"Garrett
Spong","email":"[email protected]"},"sourceCommit":{"committedDate":"2024-07-24T14:03:46Z","message":"[Security
Assistant] Aligning API Schemas (#188704)\n\n## Summary\r\n\r\nThis PR
aims to address https://github.com/elastic/kibana/issues/183825\r\nto
ensure all our public API's have a corresponding OpenAPI spec and
to\r\nensure that they are documented as intended.\r\n\r\nI've updated
the kbn-elastic-assistant-common `yarn openapi:bundle`\r\nscript to
generate both `ess` and `serverless` artifacts (as per
[this\r\nissue](elastic/security-team#9516),
which are\r\nnow created within the package (instead of `target`), and
so are checked\r\nin to
`x-pack/packages/kbn-elastic-assistant-common/docs/openapi/`.\r\n\r\n\r\nThis
also includes:\r\n\r\n- [X] Create OpenAPI specs for the endpoints
listed above
(see\r\n[issue](https://github.com/elastic/kibana/issues/183825)).\r\n -
They had already existed \r\n- [X] Check if there are any other public
endpoints that you own that\r\ndon't have OpenAPI specs and add them to
the list above.\r\n- All endpoints (public/internal) had specs, but did
need to update the\r\n`path`'s to make sure they were consistent with
what was registered.\r\n- [X] Make sure the specs you add are valid
OpenAPI documents.\r\n- [X] Make sure the specs you add match the actual
API contract defined\r\nin the code.\r\n- [X] Mark the endpoints as
available in ESS, or Serverless, or in
both\r\nofferings.\r\n\r\n---\r\nInitial evaluation of routes listed as
missing specs
in\r\nhttps://github.com//issues/183825:\r\n\r\n- [X]
`POST\r\n/api/elastic_assistant/current_user/conversations/{id}/messages`\r\nLatest/Actual
Route:\r\n`/internal/elastic_assistant/current_user/conversations/{id}/messages`\r\nRoute
Handler:\r\nhttps://github.com/elastic/kibana/blob/bae84d4569870dcecfd0cef346d2e0d38ac92160/x-pack/plugins/elastic_assistant/server/routes/user_conversations/append_conversation_messages_route.ts#L22\r\nSchema:\r\nhttps://github.com/elastic/kibana/blob/bae84d4569870dcecfd0cef346d2e0d38ac92160/x-pack/packages/kbn-elastic-assistant-common/impl/schemas/conversations/crud_conversation_route.schema.yaml#L151-L191\r\n\r\n\r\n-
[X] `POST /api/elastic_assistant/current_user/conversations`\r\nUpdated
Route: `/api/security_ai_assistant/current_user/conversations`\r\nRoute
Handler:\r\nhttps://github.com/elastic/kibana/blob/1d4e9b9b53b5b6dcdc88c08ae5d9858daa483fe0/x-pack/plugins/elastic_assistant/server/routes/user_conversations/create_route.ts#L21\r\nSchema:\r\nhttps://github.com/elastic/kibana/blob/bae84d4569870dcecfd0cef346d2e0d38ac92160/x-pack/packages/kbn-elastic-assistant-common/impl/schemas/conversations/crud_conversation_route.schema.yaml#L6-L39\r\n\r\n-
[X] GET
/api/elastic_assistant/current_user/conversations/_find\r\nUpdated
Route:\r\n`/api/security_ai_assistant/current_user/conversations/_find`\r\nRoute
Handler:\r\nhttps://github.com/elastic/kibana/blob/1d4e9b9b53b5b6dcdc88c08ae5d9858daa483fe0/x-pack/plugins/elastic_assistant/server/routes/user_conversations/find_route.ts#L26\r\nSchema:\r\nhttps://github.com/elastic/kibana/blob/1b872fbf9dc90d3c82a569a9faef9e360fc41171/x-pack/packages/kbn-elastic-assistant-common/impl/schemas/conversations/find_conversations_route.schema.yaml#L94-L180\r\n\r\n-
[X] DELETE
/api/elastic_assistant/current_user/conversations/{id}\r\nUpdated
Route:\r\n`/api/security_ai_assistant/current_user/conversations/{id}`\r\nRoute
Handler:\r\nhttps://github.com/elastic/kibana/blob/1d5cf48a9700ee769f64256c23278fcfd8cecc5d/x-pack/plugins/elastic_assistant/server/routes/user_conversations/delete_route.ts#L19\r\nSchema:\r\nhttps://github.com/elastic/kibana/blob/bae84d4569870dcecfd0cef346d2e0d38ac92160/x-pack/packages/kbn-elastic-assistant-common/impl/schemas/conversations/crud_conversation_route.schema.yaml#L116-L149\r\n\r\n-
[X] GET
/api/elastic_assistant/current_user/conversations/{id}\r\nUpdated
Route:\r\n`/api/security_ai_assistant/current_user/conversations/{id}`\r\nRoute
Handler:\r\nhttps://github.com/elastic/kibana/blob/1d5cf48a9700ee769f64256c23278fcfd8cecc5d/x-pack/plugins/elastic_assistant/server/routes/user_conversations/read_route.ts#L21\r\nSchema:\r\nhttps://github.com/elastic/kibana/blob/bae84d4569870dcecfd0cef346d2e0d38ac92160/x-pack/packages/kbn-elastic-assistant-common/impl/schemas/conversations/crud_conversation_route.schema.yaml#L42-L75\r\n\r\n-
[X] PUT
/api/elastic_assistant/current_user/conversations/{id}\r\nUpdated
Route:\r\n`/api/security_ai_assistant/current_user/conversations/{id}`\r\nRoute
Handler:\r\nhttps://github.com/elastic/kibana/blob/1d5cf48a9700ee769f64256c23278fcfd8cecc5d/x-pack/plugins/elastic_assistant/server/routes/user_conversations/update_route.ts#L24\r\nSchema:\r\nhttps://github.com/elastic/kibana/blob/bae84d4569870dcecfd0cef346d2e0d38ac92160/x-pack/packages/kbn-elastic-assistant-common/impl/schemas/conversations/crud_conversation_route.schema.yaml#L76-L115\r\n\r\n\r\nTo
continue with remaining public
routes....\r\n\r\n---------\r\n\r\nCo-authored-by: kibanamachine
<[email protected]>","sha":"a51b775391af09b6ba2ee9456489ef3351f8875a","branchLabelMapping":{"^v8.16.0$":"main","^v(\\d+).(\\d+).\\d+$":"$1.$2"}},"sourcePullRequest":{"labels":["release_note:skip","Feature:Security
Assistant","Team:Security Generative
AI","v8.15.0","v8.16.0"],"title":"[Security Assistant] Aligning API
Schemas","number":188704,"url":"https://github.com/elastic/kibana/pull/188704","mergeCommit":{"message":"[Security
Assistant] Aligning API Schemas (#188704)\n\n## Summary\r\n\r\nThis PR
aims to address https://github.com/elastic/kibana/issues/183825\r\nto
ensure all our public API's have a corresponding OpenAPI spec and
to\r\nensure that they are documented as intended.\r\n\r\nI've updated
the kbn-elastic-assistant-common `yarn openapi:bundle`\r\nscript to
generate both `ess` and `serverless` artifacts (as per
[this\r\nissue](elastic/security-team#9516),
which are\r\nnow created within the package (instead of `target`), and
so are checked\r\nin to
`x-pack/packages/kbn-elastic-assistant-common/docs/openapi/`.\r\n\r\n\r\nThis
also includes:\r\n\r\n- [X] Create OpenAPI specs for the endpoints
listed above
(see\r\n[issue](https://github.com/elastic/kibana/issues/183825)).\r\n -
They had already existed \r\n- [X] Check if there are any other public
endpoints that you own that\r\ndon't have OpenAPI specs and add them to
the list above.\r\n- All endpoints (public/internal) had specs, but did
need to update the\r\n`path`'s to make sure they were consistent with
what was registered.\r\n- [X] Make sure the specs you add are valid
OpenAPI documents.\r\n- [X] Make sure the specs you add match the actual
API contract defined\r\nin the code.\r\n- [X] Mark the endpoints as
available in ESS, or Serverless, or in
both\r\nofferings.\r\n\r\n---\r\nInitial evaluation of routes listed as
missing specs
in\r\nhttps://github.com//issues/183825:\r\n\r\n- [X]
`POST\r\n/api/elastic_assistant/current_user/conversations/{id}/messages`\r\nLatest/Actual
Route:\r\n`/internal/elastic_assistant/current_user/conversations/{id}/messages`\r\nRoute
Handler:\r\nhttps://github.com/elastic/kibana/blob/bae84d4569870dcecfd0cef346d2e0d38ac92160/x-pack/plugins/elastic_assistant/server/routes/user_conversations/append_conversation_messages_route.ts#L22\r\nSchema:\r\nhttps://github.com/elastic/kibana/blob/bae84d4569870dcecfd0cef346d2e0d38ac92160/x-pack/packages/kbn-elastic-assistant-common/impl/schemas/conversations/crud_conversation_route.schema.yaml#L151-L191\r\n\r\n\r\n-
[X] `POST /api/elastic_assistant/current_user/conversations`\r\nUpdated
Route: `/api/security_ai_assistant/current_user/conversations`\r\nRoute
Handler:\r\nhttps://github.com/elastic/kibana/blob/1d4e9b9b53b5b6dcdc88c08ae5d9858daa483fe0/x-pack/plugins/elastic_assistant/server/routes/user_conversations/create_route.ts#L21\r\nSchema:\r\nhttps://github.com/elastic/kibana/blob/bae84d4569870dcecfd0cef346d2e0d38ac92160/x-pack/packages/kbn-elastic-assistant-common/impl/schemas/conversations/crud_conversation_route.schema.yaml#L6-L39\r\n\r\n-
[X] GET
/api/elastic_assistant/current_user/conversations/_find\r\nUpdated
Route:\r\n`/api/security_ai_assistant/current_user/conversations/_find`\r\nRoute
Handler:\r\nhttps://github.com/elastic/kibana/blob/1d4e9b9b53b5b6dcdc88c08ae5d9858daa483fe0/x-pack/plugins/elastic_assistant/server/routes/user_conversations/find_route.ts#L26\r\nSchema:\r\nhttps://github.com/elastic/kibana/blob/1b872fbf9dc90d3c82a569a9faef9e360fc41171/x-pack/packages/kbn-elastic-assistant-common/impl/schemas/conversations/find_conversations_route.schema.yaml#L94-L180\r\n\r\n-
[X] DELETE
/api/elastic_assistant/current_user/conversations/{id}\r\nUpdated
Route:\r\n`/api/security_ai_assistant/current_user/conversations/{id}`\r\nRoute
Handler:\r\nhttps://github.com/elastic/kibana/blob/1d5cf48a9700ee769f64256c23278fcfd8cecc5d/x-pack/plugins/elastic_assistant/server/routes/user_conversations/delete_route.ts#L19\r\nSchema:\r\nhttps://github.com/elastic/kibana/blob/bae84d4569870dcecfd0cef346d2e0d38ac92160/x-pack/packages/kbn-elastic-assistant-common/impl/schemas/conversations/crud_conversation_route.schema.yaml#L116-L149\r\n\r\n-
[X] GET
/api/elastic_assistant/current_user/conversations/{id}\r\nUpdated
Route:\r\n`/api/security_ai_assistant/current_user/conversations/{id}`\r\nRoute
Handler:\r\nhttps://github.com/elastic/kibana/blob/1d5cf48a9700ee769f64256c23278fcfd8cecc5d/x-pack/plugins/elastic_assistant/server/routes/user_conversations/read_route.ts#L21\r\nSchema:\r\nhttps://github.com/elastic/kibana/blob/bae84d4569870dcecfd0cef346d2e0d38ac92160/x-pack/packages/kbn-elastic-assistant-common/impl/schemas/conversations/crud_conversation_route.schema.yaml#L42-L75\r\n\r\n-
[X] PUT
/api/elastic_assistant/current_user/conversations/{id}\r\nUpdated
Route:\r\n`/api/security_ai_assistant/current_user/conversations/{id}`\r\nRoute
Handler:\r\nhttps://github.com/elastic/kibana/blob/1d5cf48a9700ee769f64256c23278fcfd8cecc5d/x-pack/plugins/elastic_assistant/server/routes/user_conversations/update_route.ts#L24\r\nSchema:\r\nhttps://github.com/elastic/kibana/blob/bae84d4569870dcecfd0cef346d2e0d38ac92160/x-pack/packages/kbn-elastic-assistant-common/impl/schemas/conversations/crud_conversation_route.schema.yaml#L76-L115\r\n\r\n\r\nTo
continue with remaining public
routes....\r\n\r\n---------\r\n\r\nCo-authored-by: kibanamachine
<[email protected]>","sha":"a51b775391af09b6ba2ee9456489ef3351f8875a"}},"sourceBranch":"main","suggestedTargetBranches":["8.15"],"targetPullRequestStates":[{"branch":"8.15","label":"v8.15.0","branchLabelMappingKey":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"state":"NOT_CREATED"},{"branch":"main","label":"v8.16.0","branchLabelMappingKey":"^v8.16.0$","isSourceBranch":true,"state":"MERGED","url":"https://github.com/elastic/kibana/pull/188704","number":188704,"mergeCommit":{"message":"[Security
Assistant] Aligning API Schemas (#188704)\n\n## Summary\r\n\r\nThis PR
aims to address https://github.com/elastic/kibana/issues/183825\r\nto
ensure all our public API's have a corresponding OpenAPI spec and
to\r\nensure that they are documented as intended.\r\n\r\nI've updated
the kbn-elastic-assistant-common `yarn openapi:bundle`\r\nscript to
generate both `ess` and `serverless` artifacts (as per
[this\r\nissue](elastic/security-team#9516),
which are\r\nnow created within the package (instead of `target`), and
so are checked\r\nin to
`x-pack/packages/kbn-elastic-assistant-common/docs/openapi/`.\r\n\r\n\r\nThis
also includes:\r\n\r\n- [X] Create OpenAPI specs for the endpoints
listed above
(see\r\n[issue](https://github.com/elastic/kibana/issues/183825)).\r\n -
They had already existed \r\n- [X] Check if there are any other public
endpoints that you own that\r\ndon't have OpenAPI specs and add them to
the list above.\r\n- All endpoints (public/internal) had specs, but did
need to update the\r\n`path`'s to make sure they were consistent with
what was registered.\r\n- [X] Make sure the specs you add are valid
OpenAPI documents.\r\n- [X] Make sure the specs you add match the actual
API contract defined\r\nin the code.\r\n- [X] Mark the endpoints as
available in ESS, or Serverless, or in
both\r\nofferings.\r\n\r\n---\r\nInitial evaluation of routes listed as
missing specs
in\r\nhttps://github.com//issues/183825:\r\n\r\n- [X]
`POST\r\n/api/elastic_assistant/current_user/conversations/{id}/messages`\r\nLatest/Actual
Route:\r\n`/internal/elastic_assistant/current_user/conversations/{id}/messages`\r\nRoute
Handler:\r\nhttps://github.com/elastic/kibana/blob/bae84d4569870dcecfd0cef346d2e0d38ac92160/x-pack/plugins/elastic_assistant/server/routes/user_conversations/append_conversation_messages_route.ts#L22\r\nSchema:\r\nhttps://github.com/elastic/kibana/blob/bae84d4569870dcecfd0cef346d2e0d38ac92160/x-pack/packages/kbn-elastic-assistant-common/impl/schemas/conversations/crud_conversation_route.schema.yaml#L151-L191\r\n\r\n\r\n-
[X] `POST /api/elastic_assistant/current_user/conversations`\r\nUpdated
Route: `/api/security_ai_assistant/current_user/conversations`\r\nRoute
Handler:\r\nhttps://github.com/elastic/kibana/blob/1d4e9b9b53b5b6dcdc88c08ae5d9858daa483fe0/x-pack/plugins/elastic_assistant/server/routes/user_conversations/create_route.ts#L21\r\nSchema:\r\nhttps://github.com/elastic/kibana/blob/bae84d4569870dcecfd0cef346d2e0d38ac92160/x-pack/packages/kbn-elastic-assistant-common/impl/schemas/conversations/crud_conversation_route.schema.yaml#L6-L39\r\n\r\n-
[X] GET
/api/elastic_assistant/current_user/conversations/_find\r\nUpdated
Route:\r\n`/api/security_ai_assistant/current_user/conversations/_find`\r\nRoute
Handler:\r\nhttps://github.com/elastic/kibana/blob/1d4e9b9b53b5b6dcdc88c08ae5d9858daa483fe0/x-pack/plugins/elastic_assistant/server/routes/user_conversations/find_route.ts#L26\r\nSchema:\r\nhttps://github.com/elastic/kibana/blob/1b872fbf9dc90d3c82a569a9faef9e360fc41171/x-pack/packages/kbn-elastic-assistant-common/impl/schemas/conversations/find_conversations_route.schema.yaml#L94-L180\r\n\r\n-
[X] DELETE
/api/elastic_assistant/current_user/conversations/{id}\r\nUpdated
Route:\r\n`/api/security_ai_assistant/current_user/conversations/{id}`\r\nRoute
Handler:\r\nhttps://github.com/elastic/kibana/blob/1d5cf48a9700ee769f64256c23278fcfd8cecc5d/x-pack/plugins/elastic_assistant/server/routes/user_conversations/delete_route.ts#L19\r\nSchema:\r\nhttps://github.com/elastic/kibana/blob/bae84d4569870dcecfd0cef346d2e0d38ac92160/x-pack/packages/kbn-elastic-assistant-common/impl/schemas/conversations/crud_conversation_route.schema.yaml#L116-L149\r\n\r\n-
[X] GET
/api/elastic_assistant/current_user/conversations/{id}\r\nUpdated
Route:\r\n`/api/security_ai_assistant/current_user/conversations/{id}`\r\nRoute
Handler:\r\nhttps://github.com/elastic/kibana/blob/1d5cf48a9700ee769f64256c23278fcfd8cecc5d/x-pack/plugins/elastic_assistant/server/routes/user_conversations/read_route.ts#L21\r\nSchema:\r\nhttps://github.com/elastic/kibana/blob/bae84d4569870dcecfd0cef346d2e0d38ac92160/x-pack/packages/kbn-elastic-assistant-common/impl/schemas/conversations/crud_conversation_route.schema.yaml#L42-L75\r\n\r\n-
[X] PUT
/api/elastic_assistant/current_user/conversations/{id}\r\nUpdated
Route:\r\n`/api/security_ai_assistant/current_user/conversations/{id}`\r\nRoute
Handler:\r\nhttps://github.com/elastic/kibana/blob/1d5cf48a9700ee769f64256c23278fcfd8cecc5d/x-pack/plugins/elastic_assistant/server/routes/user_conversations/update_route.ts#L24\r\nSchema:\r\nhttps://github.com/elastic/kibana/blob/bae84d4569870dcecfd0cef346d2e0d38ac92160/x-pack/packages/kbn-elastic-assistant-common/impl/schemas/conversations/crud_conversation_route.schema.yaml#L76-L115\r\n\r\n\r\nTo
continue with remaining public
routes....\r\n\r\n---------\r\n\r\nCo-authored-by: kibanamachine
<[email protected]>","sha":"a51b775391af09b6ba2ee9456489ef3351f8875a"}}]}]
BACKPORT-->

Co-authored-by: Garrett Spong <[email protected]>

x-pack/packages/kbn-elastic-assistant-common/docs/openapi/ess/elastic_assistant_api_2023_10_31.bundled.schema.yaml

@@ -0,0 +1,114 @@
+openapi: 3.0.3
+info:
+  description: Manage and interact with Security Assistant resources.
+  title: Security AI Assistant API (Elastic Cloud & self-hosted)
+  version: '2023-10-31'
+servers:
+  - url: 'http://{kibana_host}:{port}'
+    variables:
+      kibana_host:
+        default: localhost
+      port:
+        default: '5601'
+paths:
+  /api/security_ai_assistant/chat/complete:
+    post:
+      description: Creates a model response for the given chat conversation.
+      operationId: ChatComplete
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/ChatCompleteProps'
+        required: true
+      responses:
+        '200':
+          content:
+            application/octet-stream:
+              schema:
+                format: binary
+                type: string
+          description: Indicates a successful call.
+        '400':
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  error:
+                    type: string
+                  message:
+                    type: string
+                  statusCode:
+                    type: number
+          description: Generic Error
+      summary: Creates a model response for the given chat conversation.
+      tags:
+        - Chat Complete API
+components:
+  schemas:
+    ChatCompleteProps:
+      type: object
+      properties:
+        connectorId:
+          type: string
+        conversationId:
+          type: string
+        isStream:
+          type: boolean
+        langSmithApiKey:
+          type: string
+        langSmithProject:
+          type: string
+        messages:
+          items:
+            $ref: '#/components/schemas/ChatMessage'
+          type: array
+        model:
+          type: string
+        persist:
+          type: boolean
+        promptId:
+          type: string
+        responseLanguage:
+          type: string
+      required:
+        - messages
+        - persist
+        - connectorId
+    ChatMessage:
+      description: AI assistant message.
+      type: object
+      properties:
+        content:
+          description: Message content.
+          type: string
+        data:
+          $ref: '#/components/schemas/MessageData'
+          description: ECS object to attach to the context of the message.
+        fields_to_anonymize:
+          items:
+            type: string
+          type: array
+        role:
+          $ref: '#/components/schemas/ChatMessageRole'
+          description: Message role.
+      required:
+        - role
+    ChatMessageRole:
+      description: Message role.
+      enum:
+        - system
+        - user
+        - assistant
+      type: string
+    MessageData:
+      additionalProperties: true
+      type: object
+  securitySchemes:
+    BasicAuth:
+      scheme: basic
+      type: http
+security:
+  - BasicAuth: []
+tags: !<tag:yaml.org,2002:js/undefined> ''