H2O.ai Configurations API

openapi: 3.2.0
info:
  title: h2oGPTe REST Configurations API
  description: "\n# Overview \n\nUsers can easily interact with the h2oGPTe API through its REST API, allowing HTTP requests from any programming language.\n\n## Authorization: Getting an API key\n\nSign up/in at Enterprise h2oGPTe and generate one of the following two types of API keys: \n\n- **Global API key**: If a Collection is not specified when creating a new API Key, that key is considered to be a global API Key. Use global API Keys to grant full user impersonation and system-wide access to all of your work. Anyone with access to one of your global API Keys can create, delete, or interact with any of your past, current, and future Collections, Documents, Chats, and settings.\n\n- **Collection-specific API key**: Use Collection-specific API Keys to grant external access to only Chat with a specified Collection and make related API calls to it. Collection-specific API keys do not allow other API calls, such as creation, deletion, or access to other Collections or Chats.\n \nAccess Enterprise h2oGPTe through your [H2O Generative AI](https://genai.h2o.ai/appstore) app store account, available with a freemium tier.\n\n## Authorization: Using an API key \n\nAll h2oGPTe REST API requests must include an API Key in the \"Authorization\" HTTP header, formatted as follows:\n\n```\nAuthorization: Bearer sk-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n```\n\n```sh\ncurl -X 'POST' \\\n  'https://h2ogpte.genai.h2o.ai/api/v1/collections' \\\n  -H 'accept: application/json' \\\n  -H 'Content-Type: application/json' \\\n  -H 'Authorization: Bearer sk-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' \\\n  -d '{\n    \"name\": \"The name of my Collection\",\n    \"description\": \"The description of my Collection\",\n    \"embedding_model\": \"BAAI/bge-large-en-v1.5\"\n  }'\n```\n    \n## Interactive h2oGPTe API testing\n\nThis page only showcases the h2oGPTe REST API; you can test it directly in the [Swagger UI](https://h2ogpte.genai.h2o.ai/swagger-ui/). Ensure that you are logged into your Enterprise h2oGPTe account.\n"
  version: v1.0.0
servers:
- url: https://h2ogpte.genai.h2o.ai/api/v1
security:
- bearerAuth: []
tags:
- name: Configurations
paths:
  /roles/{role_id}/configurations:
    get:
      operationId: list_role_configurations
      summary: Gets configurations for a given role.
      description: Gets configurations for a given role.
      tags:
      - Configurations
      parameters:
      - name: role_id
        in: path
        description: The unique identifier of an role.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserConfigurationItem'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/Unexpected'
  /roles/{role_id}/configurations/{key_name}:
    put:
      operationId: set_role_configuration
      summary: Sets configuration item for a given role.
      description: Sets configuration item for a given role.
      tags:
      - Configurations
      parameters:
      - name: role_id
        in: path
        description: The unique identifier of an role.
        required: true
        schema:
          type: string
      - name: key_name
        in: path
        description: The key of the configuration item that will be set.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserConfigurationItem'
        required: true
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserConfigurationItem'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/Unexpected'
  /roles/{role_id}/configurations/{key_names}:
    delete:
      operationId: delete_role_configurations
      summary: Deletes role configuration items.
      description: Deletes role configuration items for a given role.
      tags:
      - Configurations
      parameters:
      - name: role_id
        in: path
        description: The unique identifier of the role.
        required: true
        schema:
          type: string
      - name: key_names
        in: path
        description: Keys of the configuration items that will be deleted.
        required: true
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserConfigurationItem'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/Unexpected'
  /configurations:
    get:
      operationId: list_global_configurations
      summary: Gets global configurations.
      description: Gets global configurations.
      tags:
      - Configurations
      parameters:
      - name: as_admin
        in: query
        description: If set, lists global configurations with admin permissions. The user must be admin.
        required: false
        schema:
          default: false
          type: boolean
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/GlobalConfigurationItem'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'
  /configurations/fetch-url:
    post:
      operationId: fetch_configuration_url
      summary: Fetch HTML content from a URL.
      description: 'Fetches HTML content from a remote URL for use as an email template. Validates that content is HTML and under 100KB. Admin only.

        '
      tags:
      - Configurations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - url
              properties:
                url:
                  type: string
                  description: The URL to fetch HTML content from.
      responses:
        '200':
          description: HTML content fetched successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  content:
                    type: string
                    description: The fetched HTML content.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '502':
          description: Failed to fetch content from the URL.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EndpointError'
        default:
          $ref: '#/components/responses/Unexpected'
  /configurations/{key_name}:
    put:
      operationId: set_global_configuration
      summary: Sets global configuration item.
      description: Sets global configuration item (to be used by admins only).
      tags:
      - Configurations
      parameters:
      - name: key_name
        in: path
        description: The key of the configuration item that will be set.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              required:
              - string_value
              - can_overwrite
              - is_public
              type: object
              properties:
                string_value:
                  description: The value to be set for the global config.
                  type: string
                can_overwrite:
                  description: Whether user settings can override this global setting.
                  type: boolean
                is_public:
                  description: Whether users can see the value for this global setting.
                  type: boolean
                value_type:
                  description: The type of the value to be set for the global config.
                  type: string
        required: true
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/GlobalConfigurationItem'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'
  /configurations/{key_names}:
    delete:
      operationId: delete_global_configurations
      summary: Deletes global configuration items.
      description: Deletes global configuration items (to be used by admins only).
      tags:
      - Configurations
      parameters:
      - name: key_names
        in: path
        description: Keys of the configuration items that will be deleted.
        required: true
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/GlobalConfigurationItem'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'
  /users/current/configurations:
    get:
      operationId: list_current_user_configurations
      summary: Gets configurations for current users.
      description: Gets configurations for current users.
      tags:
      - Configurations
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserConfigurationItem'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'
  /users/{user_id}/configurations:
    get:
      operationId: list_user_configurations
      summary: Gets user configurations.
      description: Gets user configurations (to be used by admins only).
      tags:
      - Configurations
      parameters:
      - name: user_id
        in: path
        description: The unique identifier of the user.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserConfigurationItem'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'
  /users/{user_id}/configurations/{key_name}:
    put:
      operationId: set_user_configuration
      summary: Sets user configuration item.
      description: Sets user configuration item (to be used by admins only).
      tags:
      - Configurations
      parameters:
      - name: user_id
        in: path
        description: The unique identifier of the user.
        required: true
        schema:
          type: string
      - name: key_name
        in: path
        description: The key of the configuration item that will be set.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              required:
              - string_value
              type: object
              properties:
                string_value:
                  type: string
                value_type:
                  type: string
        required: true
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserConfigurationItem'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        default:
          $ref: '#/components/responses/Unexpected'
  /users/{user_id}/configurations/{key_name}/reset:
    post:
      operationId: reset_user_configuration
      summary: Resets user configuration item.
      description: Resets user configuration item (to be used by admins only).
      tags:
      - Configurations
      parameters:
      - name: user_id
        in: path
        description: The unique identifier of the user.
        required: true
        schema:
          type: string
      - name: key_name
        in: path
        description: The key of the configuration item that will be set.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserConfigurationItem'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'
  /users/{user_id}/configurations/{key_names}:
    delete:
      operationId: delete_user_configurations
      summary: Deletes user configuration items.
      description: Deletes user configuration items (to be used by admins only).
      tags:
      - Configurations
      parameters:
      - name: user_id
        in: path
        description: The unique identifier of the user.
        required: true
        schema:
          type: string
      - name: key_names
        in: path
        description: Keys of the configuration items that will be deleted.
        required: true
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserConfigurationItem'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'
components:
  responses:
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EndpointError'
    NotFound:
      description: Not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EndpointError'
    Unexpected:
      description: Unexpected error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EndpointError'
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EndpointError'
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EndpointError'
    Unauthorized:
      description: Unauthorized - Invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EndpointError'
  schemas:
    GlobalConfigurationItem:
      required:
      - key_name
      - string_value
      - value_type
      - can_overwrite
      - is_public
      type: object
      properties:
        key_name:
          type: string
        string_value:
          type: string
        value_type:
          type: string
        can_overwrite:
          type: boolean
        upper_bound:
          type: number
        is_public:
          type: boolean
        is_read_only:
          type: boolean
        is_encrypted:
          type: boolean
        description:
          type: string
        category:
          type: string
        needs_propagation:
          type: boolean
          description: 'When true, mux resolves this key per-user (with role-priority

            overrides) and caches the resolved value for the duration of

            the global `config_cache_ttl_seconds` setting. The UI uses this

            flag to render an info icon explaining that changes take up to

            the cache-TTL seconds to propagate across all mux replicas.

            '
    EndpointError:
      required:
      - code
      - message
      properties:
        code:
          type: integer
          format: int32
          description: Error code
        message:
          type: string
          description: Error message
    UserConfigurationItem:
      required:
      - key_name
      - string_value
      - value_type
      type: object
      properties:
        key_name:
          type: string
        string_value:
          type: string
        value_type:
          type: string
        updated_at:
          type: string
          format: date-time
          description: When this override was last saved.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Using an API key generated by H2OGPTe