[Security solution] Generative AI Connector API specification (#158423)

Co-authored-by: Steph Milovic <stephanie.milovic@elastic.co>

docs/api-generated/connectors/connector-apis-passthru.asciidoc

@@ -1001,6 +1001,7 @@ Any modifications made to this file will be overwritten.
     <li><a href="#Update_connector_request_body_properties"><code>Update_connector_request_body_properties</code> - Update connector request body properties</a></li>
     <li><a href="#action_response_properties"><code>action_response_properties</code> - Action response properties</a></li>
     <li><a href="#config_properties_cases_webhook"><code>config_properties_cases_webhook</code> - Connector request properties for Webhook - Case Management connector</a></li>
+    <li><a href="#config_properties_genai"><code>config_properties_genai</code> - Connector request properties for a generative AI connector</a></li>
     <li><a href="#config_properties_index"><code>config_properties_index</code> - Connector request properties for an index connector</a></li>
     <li><a href="#config_properties_jira"><code>config_properties_jira</code> - Connector request properties for a Jira connector</a></li>
     <li><a href="#config_properties_opsgenie"><code>config_properties_opsgenie</code> - Connector request properties for an Opsgenie connector</a></li>
@@ -1030,6 +1031,7 @@ Any modifications made to this file will be overwritten.
     <li><a href="#connector_types"><code>connector_types</code> - Connector types</a></li>
     <li><a href="#create_connector_request_cases_webhook"><code>create_connector_request_cases_webhook</code> - Create Webhook - Case Managment connector request</a></li>
     <li><a href="#create_connector_request_email"><code>create_connector_request_email</code> - Create email connector request</a></li>
+    <li><a href="#create_connector_request_genai"><code>create_connector_request_genai</code> - Create generative AI connector request</a></li>
     <li><a href="#create_connector_request_index"><code>create_connector_request_index</code> - Create index connector request</a></li>
     <li><a href="#create_connector_request_jira"><code>create_connector_request_jira</code> - Create Jira connector request</a></li>
     <li><a href="#create_connector_request_opsgenie"><code>create_connector_request_opsgenie</code> - Create Opsgenie connector request</a></li>
@@ -1082,6 +1084,7 @@ Any modifications made to this file will be overwritten.
     <li><a href="#run_connector_subaction_pushtoservice_subActionParams_incident_malware_url"><code>run_connector_subaction_pushtoservice_subActionParams_incident_malware_url</code> - </a></li>
     <li><a href="#run_connector_subaction_pushtoservice_subActionParams_incident_source_ip"><code>run_connector_subaction_pushtoservice_subActionParams_incident_source_ip</code> - </a></li>
     <li><a href="#secrets_properties_cases_webhook"><code>secrets_properties_cases_webhook</code> - Connector secrets properties for Webhook - Case Management connector</a></li>
+    <li><a href="#secrets_properties_genai"><code>secrets_properties_genai</code> - Connector secrets properties for a generative AI connector</a></li>
     <li><a href="#secrets_properties_jira"><code>secrets_properties_jira</code> - Connector secrets properties for a Jira connector</a></li>
     <li><a href="#secrets_properties_opsgenie"><code>secrets_properties_opsgenie</code> - Connector secrets properties for an Opsgenie connector</a></li>
     <li><a href="#secrets_properties_resilient"><code>secrets_properties_resilient</code> - Connector secrets properties for IBM Resilient connector</a></li>
@@ -1370,6 +1373,14 @@ Any modifications made to this file will be overwritten.
 <div class="param">viewIncidentUrl </div><div class="param-desc"><span class="param-type"><a href="#string">String</a></span> The URL to view the case in the external system. You can use variables to add the external system ID or external system title to the URL. </div>
     </div>  <!-- field-items -->
   </div>
+  <div class="model">
+    <h3><a name="config_properties_genai"><code>config_properties_genai</code> - Connector request properties for a generative AI connector</a> <a class="up" href="#__Models">Up</a></h3>
+    <div class='model-description'>Defines properties for connectors when type is <code>.gen-ai</code>.</div>
+    <div class="field-items">
+      <div class="param">apiProvider (optional)</div><div class="param-desc"><span class="param-type"><a href="#string">String</a></span> The OpenAI API provider. </div>
+<div class="param">apiUrl (optional)</div><div class="param-desc"><span class="param-type"><a href="#string">String</a></span> The OpenAI API endpoint. </div>
+    </div>  <!-- field-items -->
+  </div>
   <div class="model">
     <h3><a name="config_properties_index"><code>config_properties_index</code> - Connector request properties for an index connector</a> <a class="up" href="#__Models">Up</a></h3>
     <div class='model-description'>Defines properties for connectors when type is <code>.index</code>.</div>
@@ -1749,6 +1760,18 @@ Any modifications made to this file will be overwritten.
 <div class="param">secrets </div><div class="param-desc"><span class="param-type"><a href="#AnyType">map[String, oas_any_type_not_mapped]</a></span> Defines secrets for connectors when type is <code>.email</code>. </div>
     </div>  <!-- field-items -->
   </div>
+  <div class="model">
+    <h3><a name="create_connector_request_genai"><code>create_connector_request_genai</code> - Create generative AI connector request</a> <a class="up" href="#__Models">Up</a></h3>
+    <div class='model-description'>The generative AI connector uses axios to send a POST request to either OpenAI or Azure OpenAPI.</div>
+    <div class="field-items">
+      <div class="param">config </div><div class="param-desc"><span class="param-type"><a href="#config_properties_genai">config_properties_genai</a></span>  </div>
+<div class="param">connector_type_id </div><div class="param-desc"><span class="param-type"><a href="#string">String</a></span> The type of connector. </div>
+        <div class="param-enum-header">Enum:</div>
+        <div class="param-enum">.gen-ai</div>
+<div class="param">name </div><div class="param-desc"><span class="param-type"><a href="#string">String</a></span> The display name for the connector. </div>
+<div class="param">secrets </div><div class="param-desc"><span class="param-type"><a href="#secrets_properties_genai">secrets_properties_genai</a></span>  </div>
+    </div>  <!-- field-items -->
+  </div>
   <div class="model">
     <h3><a name="create_connector_request_index"><code>create_connector_request_index</code> - Create index connector request</a> <a class="up" href="#__Models">Up</a></h3>
     <div class='model-description'>The index connector indexes a document into Elasticsearch.</div>
@@ -2286,6 +2309,13 @@ Any modifications made to this file will be overwritten.
 <div class="param">user (optional)</div><div class="param-desc"><span class="param-type"><a href="#string">String</a></span> The username for HTTP basic authentication. If <code>hasAuth</code> is set to <code>true</code>, this property is required. </div>
     </div>  <!-- field-items -->
   </div>
+  <div class="model">
+    <h3><a name="secrets_properties_genai"><code>secrets_properties_genai</code> - Connector secrets properties for a generative AI connector</a> <a class="up" href="#__Models">Up</a></h3>
+    <div class='model-description'>Defines secrets for connectors when type is <code>.gen-ai</code>.</div>
+    <div class="field-items">
+      <div class="param">apiKey (optional)</div><div class="param-desc"><span class="param-type"><a href="#string">String</a></span> The OpenAI API key. </div>
+    </div>  <!-- field-items -->
+  </div>
   <div class="model">
     <h3><a name="secrets_properties_jira"><code>secrets_properties_jira</code> - Connector secrets properties for a Jira connector</a> <a class="up" href="#__Models">Up</a></h3>
     <div class='model-description'>Defines secrets for connectors when type is <code>.jira</code>.</div>

x-pack/plugins/actions/docs/openapi/bundled.json

@@ -55,6 +55,9 @@
                   {
                     "$ref": "#/components/schemas/create_connector_request_email"
                   },
+                  {
+                    "$ref": "#/components/schemas/create_connector_request_genai"
+                  },
                   {
                     "$ref": "#/components/schemas/create_connector_request_index"
                   },
@@ -309,6 +312,9 @@
                   {
                     "$ref": "#/components/schemas/create_connector_request_email"
                   },
+                  {
+                    "$ref": "#/components/schemas/create_connector_request_genai"
+                  },
                   {
                     "$ref": "#/components/schemas/create_connector_request_index"
                   },
@@ -1569,6 +1575,64 @@
           }
         }
       },
+      "config_properties_genai": {
+        "title": "Connector request properties for a generative AI connector",
+        "description": "Defines properties for connectors when type is `.gen-ai`.",
+        "type": "object",
+        "properties": {
+          "apiProvider": {
+            "type": "string",
+            "description": "The OpenAI API provider."
+          },
+          "apiUrl": {
+            "type": "string",
+            "description": "The OpenAI API endpoint."
+          }
+        }
+      },
+      "secrets_properties_genai": {
+        "title": "Connector secrets properties for a generative AI connector",
+        "description": "Defines secrets for connectors when type is `.gen-ai`.",
+        "type": "object",
+        "properties": {
+          "apiKey": {
+            "type": "string",
+            "description": "The OpenAI API key."
+          }
+        }
+      },
+      "create_connector_request_genai": {
+        "title": "Create generative AI connector request",
+        "description": "The generative AI connector uses axios to send a POST request to either OpenAI or Azure OpenAPI.\n",
+        "type": "object",
+        "required": [
+          "config",
+          "connector_type_id",
+          "name",
+          "secrets"
+        ],
+        "properties": {
+          "config": {
+            "$ref": "#/components/schemas/config_properties_genai"
+          },
+          "connector_type_id": {
+            "type": "string",
+            "description": "The type of connector.",
+            "enum": [
+              ".gen-ai"
+            ],
+            "example": ".gen-ai"
+          },
+          "name": {
+            "type": "string",
+            "description": "The display name for the connector.",
+            "example": "my-connector"
+          },
+          "secrets": {
+            "$ref": "#/components/schemas/secrets_properties_genai"
+          }
+        }
+      },
       "config_properties_index": {
         "title": "Connector request properties for an index connector",
         "required": [
@@ -3640,6 +3704,7 @@
         "enum": [
           ".cases-webhook",
           ".email",
+          ".gen-ai",
           ".index",
           ".jira",
           ".opsgenie",

x-pack/plugins/actions/docs/openapi/bundled.yaml

@@ -36,6 +36,7 @@ paths:
               oneOf:
                 - $ref: '#/components/schemas/create_connector_request_cases_webhook'
                 - $ref: '#/components/schemas/create_connector_request_email'
+                - $ref: '#/components/schemas/create_connector_request_genai'
                 - $ref: '#/components/schemas/create_connector_request_index'
                 - $ref: '#/components/schemas/create_connector_request_jira'
                 - $ref: '#/components/schemas/create_connector_request_opsgenie'
@@ -175,6 +176,7 @@ paths:
               oneOf:
                 - $ref: '#/components/schemas/create_connector_request_cases_webhook'
                 - $ref: '#/components/schemas/create_connector_request_email'
+                - $ref: '#/components/schemas/create_connector_request_genai'
                 - $ref: '#/components/schemas/create_connector_request_index'
                 - $ref: '#/components/schemas/create_connector_request_jira'
                 - $ref: '#/components/schemas/create_connector_request_opsgenie'
@@ -965,6 +967,50 @@ components:
           example: my-connector
         secrets:
           $ref: '#/components/schemas/secrets_properties_email'
+    config_properties_genai:
+      title: Connector request properties for a generative AI connector
+      description: Defines properties for connectors when type is `.gen-ai`.
+      type: object
+      properties:
+        apiProvider:
+          type: string
+          description: The OpenAI API provider.
+        apiUrl:
+          type: string
+          description: The OpenAI API endpoint.
+    secrets_properties_genai:
+      title: Connector secrets properties for a generative AI connector
+      description: Defines secrets for connectors when type is `.gen-ai`.
+      type: object
+      properties:
+        apiKey:
+          type: string
+          description: The OpenAI API key.
+    create_connector_request_genai:
+      title: Create generative AI connector request
+      description: |
+        The generative AI connector uses axios to send a POST request to either OpenAI or Azure OpenAPI.
+      type: object
+      required:
+        - config
+        - connector_type_id
+        - name
+        - secrets
+      properties:
+        config:
+          $ref: '#/components/schemas/config_properties_genai'
+        connector_type_id:
+          type: string
+          description: The type of connector.
+          enum:
+            - .gen-ai
+          example: .gen-ai
+        name:
+          type: string
+          description: The display name for the connector.
+          example: my-connector
+        secrets:
+          $ref: '#/components/schemas/secrets_properties_genai'
     config_properties_index:
       title: Connector request properties for an index connector
       required:
@@ -2498,6 +2544,7 @@ components:
       enum:
         - .cases-webhook
         - .email
+        - .gen-ai
         - .index
         - .jira
         - .opsgenie

x-pack/plugins/actions/docs/openapi/components/schemas/config_properties_genai.yaml

@@ -0,0 +1,10 @@
+title: Connector request properties for a generative AI connector
+description: Defines properties for connectors when type is `.gen-ai`.
+type: object
+properties:
+    apiProvider:
+        type: string
+        description: The OpenAI API provider.
+    apiUrl:
+        type: string
+        description: The OpenAI API endpoint.

x-pack/plugins/actions/docs/openapi/components/schemas/connector_response_properties_genai.yaml

@@ -0,0 +1,29 @@
+title: Connector response properties for a generative AI connector
+type: object
+required:
+  - config
+  - connector_type_id
+  - id
+  - is_deprecated
+  - is_preconfigured
+  - name
+properties:
+  config:
+    $ref: 'config_properties_genai.yaml'
+  connector_type_id:
+    type: string
+    description: The type of connector.
+    enum:
+      - .gen-ai
+  id:
+    type: string
+    description: The identifier for the connector.
+  is_deprecated:
+   $ref: 'is_deprecated.yaml'
+  is_missing_secrets:
+    $ref: 'is_missing_secrets.yaml'
+  is_preconfigured:
+    $ref: 'is_preconfigured.yaml'
+  name:
+    type: string
+    description: The display name for the connector.

x-pack/plugins/actions/docs/openapi/components/schemas/connector_types.yaml

@@ -4,6 +4,7 @@ description: The type of connector. For example, `.email`, `.index`, `.jira`, `.
 enum:
   - .cases-webhook
   - .email
+  - .gen-ai
   - .index
   - .jira
   - .opsgenie

x-pack/plugins/actions/docs/openapi/components/schemas/create_connector_request_genai.yaml

@@ -0,0 +1,25 @@
+title: Create generative AI connector request
+description: >
+  The generative AI connector uses axios to send a POST request to either
+  OpenAI or Azure OpenAPI.
+type: object
+required:
+  - config
+  - connector_type_id
+  - name
+  - secrets
+properties:
+  config:
+    $ref: 'config_properties_genai.yaml'
+  connector_type_id:
+    type: string
+    description: The type of connector.
+    enum:
+      - .gen-ai
+    example: .gen-ai
+  name:
+    type: string
+    description: The display name for the connector.
+    example: my-connector
+  secrets:
+    $ref: 'secrets_properties_genai.yaml' 

x-pack/plugins/actions/docs/openapi/components/schemas/secrets_properties_genai.yaml

@@ -0,0 +1,7 @@
+title: Connector secrets properties for a generative AI connector
+description: Defines secrets for connectors when type is `.gen-ai`.
+type: object
+properties:
+    apiKey:
+        type: string
+        description: The OpenAI API key.

x-pack/plugins/actions/docs/openapi/paths/s@{spaceid}@api@actions@connector.yaml

@@ -18,6 +18,7 @@ post:
           oneOf:
             - $ref: '../components/schemas/create_connector_request_cases_webhook.yaml'
             - $ref: '../components/schemas/create_connector_request_email.yaml'
+            - $ref: '../components/schemas/create_connector_request_genai.yaml'
             - $ref: '../components/schemas/create_connector_request_index.yaml'
             - $ref: '../components/schemas/create_connector_request_jira.yaml'
             - $ref: '../components/schemas/create_connector_request_opsgenie.yaml'

x-pack/plugins/actions/docs/openapi/paths/s@{spaceid}@api@actions@connector@{connectorid}.yaml

@@ -102,6 +102,7 @@ post:
           oneOf:
             - $ref: '../components/schemas/create_connector_request_cases_webhook.yaml'
             - $ref: '../components/schemas/create_connector_request_email.yaml'
+            - $ref: '../components/schemas/create_connector_request_genai.yaml'
             - $ref: '../components/schemas/create_connector_request_index.yaml'
             - $ref: '../components/schemas/create_connector_request_jira.yaml'
             - $ref: '../components/schemas/create_connector_request_opsgenie.yaml'
@@ -158,7 +159,8 @@ put:
           description: The properties vary depending on the connector type.
           oneOf:
             - $ref: '../components/schemas/update_connector_request_cases_webhook.yaml'
-#            - $ref: '../components/schemas/update_connector_request_email.yaml' 
+#            - $ref: '../components/schemas/update_connector_request_email.yaml'
+#            - $ref: '../components/schemas/create_connector_request_genai.yaml'
             - $ref: '../components/schemas/update_connector_request_index.yaml'  
             - $ref: '../components/schemas/update_connector_request_jira.yaml'
             - $ref: '../components/schemas/update_connector_request_opsgenie.yaml'