openapi: 3.0.3
info:
  title: Cluster Settings REST API
  version: '2.1'
  description: |
    This API enables you to view or set cluster-level Enterprise Analytics settings.
servers:
  - url: '{scheme}://{host}:{port}'
    description: The URL scheme, host, and port are as follows.
    variables:
      scheme:
        default: http
        description: |-
          The URL scheme.
          Use `https` for secure access.
        enum:
          - http
          - https
      host:
        default: localhost
        description: The host name or IP address of a node.
      port:
        default: '8091'
        description: |-
          The Cluster administration REST port.
          Use `18091` for secure access.

          Note that the port numbers for this REST API are different to the port numbers used by the other Enterprise Analytics Service REST APIs.
        enum:
          - '8091'
          - '18091'
paths:
  /settings/analytics:
    get:
      operationId: get_settings
      summary: View Enterprise Analytics Settings
      description: |
        Retrieves cluster-level Analytics settings.
      security:
        - ClusterRead: []
      responses:
        '200':
          description: The operation was successful.
          content: &ref_1
            application/json:
              schema:
                type: object
                properties: &ref_0
                  blobStorageScheme:
                    type: string
                    description: |
                      The storage scheme (provider) to use. Supported values:
                      - `s3` — AWS S3 or an S3-compatible storage service.
                      - `azblob` — Azure Blob Storage.
                    enum:
                      - s3
                      - azblob
                    x-has-example: true
                    example: s3
                  blobStorageBucket:
                    type: string
                    description: |
                      The name of the blob storage bucket (S3) or container (Azure Blob Storage) where Enterprise Analytics will store its data.
                    x-has-example: true
                    example: enterprise-analytics-bucket
                  blobStorageRegion:
                    type: string
                    description: |
                      The region of the blob storage bucket. Applies only when `blobStorageScheme` is `s3`.
                    x-has-example: true
                    example: us-west-2
                  blobStoragePrefix:
                    type: string
                    description: |
                      Optional. The path prefix within the bucket (S3) or container (Azure Blob Storage) where Enterprise Analytics will store its data. If not specified, the data is stored in the root of the bucket /
                    x-has-example: true
                    example: analytics-data/
                  blobStorageAnonymousAuth:
                    type: boolean
                    description: |
                      Applies only when `blobStorageScheme` is `s3`.
                      If `true`, the storage bucket will be accessed without any credentials (anonymous access).
                      See also `blobStorageAccessKeyId` and `blobStorageSecretAccessKey` for static credentials,
                      or omit all credential fields to use the Standard Credential Chain.
                    x-has-example: true
                    example: false
                  blobStorageForcePathStyle:
                    type: boolean
                    description: |
                      (Deprecated) Use `blobStoragePathStyleAddressing` instead.
                    deprecated: true
                    x-has-example: true
                    example: false
                  blobStoragePathStyleAddressing:
                    type: boolean
                    description: |
                      Applies only when `blobStorageScheme` is `s3` and a custom `blobStorageEndpoint` is configured (S3-compatible storage).
                      If `true`, path-style URLs are used (e.g., `https://s3.example.com/bucket-name/key`).
                      If `false`, virtual-hosted-style URLs are used (e.g., `https://bucket-name.s3.example.com/key`).
                      Some S3-compatible storage services require path-style addressing.
                      Replaces the deprecated `blobStorageForcePathStyle`.
                    x-has-example: true
                    example: false
                  blobStorageEndpoint:
                    type: string
                    description: |
                      The endpoint URL for the blob storage service. Required when using S3-compatible storage or Azure Blob Storage.
                      - For `s3` (S3-compatible): the URL of your S3-compatible storage service (e.g., `https://my-object-storage:18082`).
                      - For `azblob`: the Blob service endpoint for your Azure storage account (e.g., `https://mycompany.blob.core.windows.net/`).
                    x-has-example: true
                    example: https://my-object-storage:18082
                  blobStorageDisableSslVerify:
                    type: boolean
                    description: |
                      If `true`, disables certificate verification for SSL/TLS connections to the blob storage endpoint.
                      Useful for testing or when using self-signed certificates, but **not recommended for production**.
                      Warning: Disabling SSL verification in a production environment is highly insecure and exposes the system
                      to serious risks, including Man-in-the-Middle (MITM) attacks.
                    x-has-example: true
                    example: false
                  blobStorageCertificates:
                    type: array
                    items:
                      type: string
                    description: |
                      One or more PEM-encoded certificates to trust when connecting to the blob storage endpoint.
                      Only required if the endpoint is signed by a certificate authority (CA) other than a well-known public CA
                      (e.g., for self-signed or private/internal CA certificates).
                      Multiple certificates can be provided to support certificate rotation.

                      **Available from Enterprise Analytics 2.1.1.**
                    x-has-example: true
                    example:
                      - |-
                        -----BEGIN CERTIFICATE-----
                        ...
                        -----END CERTIFICATE-----
                  blobStorageAccessKeyId:
                    type: string
                    description: |
                      Optional. Applies only when `blobStorageScheme` is `s3`.
                      The Access Key ID for static credential authentication. If provided, must be supplied together with `blobStorageSecretAccessKey`.
                      If omitted, the Standard Credential Chain is used (instance profile, environment variables, etc.) to obtain credentials automatically.
                      See also `blobStorageAnonymousAuth` for anonymous access.

                      **Available from Enterprise Analytics 2.1.1.**
                    x-has-example: true
                    example: AKIAIOSFODNN7EXAMPLE
                  blobStorageSecretAccessKey:
                    type: string
                    description: |
                      Optional. Applies only when `blobStorageScheme` is `s3`.
                      The Secret Access Key for static credential authentication. If provided, must be supplied together with `blobStorageAccessKeyId`.
                      If omitted, the Standard Credential Chain is used (instance profile, environment variables, etc.) to obtain credentials automatically.
                      This value is masked as `***` in logs and when returned from the API for security reasons.

                      **Available from Enterprise Analytics 2.1.1.**
                    x-has-example: true
                    example: '***'
                  numStoragePartitions:
                    type: integer
                    minimum: 1
                    maximum: 1024
                    description: Specifies the number of partitions that will be used when storing the data in the blob storage bucket.
                    x-has-example: true
                    example: 128
        '401':
          description: |
            Unauthorized. The user name or password may be incorrect.
          content: &ref_2
            application/json:
              schema:
                type: object
    post:
      operationId: post_settings
      summary: Modify Enterprise Analytics Settings
      description: |
        Sets cluster-level Analytics settings.
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties: *ref_0
      security:
        - ClusterWrite: []
      responses:
        '200':
          description: The operation was successful.
          content: *ref_1
        '400':
          description: |
            Bad request. A parameter has an incorrect value.
          content: &ref_3
            application/json:
              schema:
                type: object
        '401':
          description: |
            Unauthorized. The user name or password may be incorrect.
          content: *ref_2
components:
  schemas:
    Settings:
      type: object
      properties: *ref_0
  responses:
    OK:
      description: The operation was successful.
      content: *ref_1
    BadRequest:
      description: |
        Bad request. A parameter has an incorrect value.
      content: *ref_3
    Unauthorized:
      description: |
        Unauthorized. The user name or password may be incorrect.
      content: *ref_2
  securitySchemes:
    ClusterRead:
      type: http
      scheme: basic
      description: |
        For the [View Enterprise Analytics Settings](#operation/get_settings) operation, users must have one of the following RBAC roles:

        * Full Admin
        * Cluster Admin
        * Read-Only Admin
    ClusterWrite:
      type: http
      scheme: basic
      description: |
        For the [Modify Enterprise Analytics Settings](#operation/post_settings) operation, users must have one of the following RBAC roles:

        * Full Admin
        * Cluster Admin
