openapi: 3.0.1
info:
  title: h2oGPTe REST API
  description: |
  
    # Overview 

    Users can easily interact with the h2oGPTe API through its REST API, allowing HTTP requests from any programming language.

    ## Authorization: Getting an API key

    Sign up/in at Enterprise h2oGPTe and generate one of the following two types of API keys: 
    
    - **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.
    
    - **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.
     
    Access Enterprise h2oGPTe through your [H2O Generative AI](https://genai.h2o.ai/appstore) app store account, available with a freemium tier.

    ## Authorization: Using an API key 

    All h2oGPTe REST API requests must include an API Key in the "Authorization" HTTP header, formatted as follows:

    ```
    Authorization: Bearer sk-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
    ```

    ```sh
    curl -X 'POST' \
      'https://h2ogpte.genai.h2o.ai/api/v1/collections' \
      -H 'accept: application/json' \
      -H 'Content-Type: application/json' \
      -H 'Authorization: Bearer sk-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' \
      -d '{
        "name": "The name of my Collection",
        "description": "The description of my Collection",
        "embedding_model": "BAAI/bge-large-en-v1.5"
      }'
    ```
        
    ## Interactive h2oGPTe API testing

    This 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.


  version: v1.0.0
servers:
  - url: 'https://h2ogpte.genai.h2o.ai/api/v1'
tags:
  - name: Collections
  - name: Documents
  - name: Document Ingestion
  - name: Chat
  - name: Prompt Templates
  - name: Jobs
  - name: Models
  - name: Tags
  - name: Permissions
  - name: API Keys
  - name: Agents
  - name: System

paths:
  /collections:
    post:
      operationId: create_collection
      summary: Create a Collection
      description: A Collection refers to a group of related Documents. A Collection lets a user aggregate documents in one location. A user can utilize Collections to group particular sets of material (documents) to explore individually through Chats utilizing a large language model (LLM). 
      tags:
        - Collections
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CollectionCreateRequest'
        required: true
      responses:
        "201":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Collection'
        "401":
          $ref: '#/components/responses/Unauthorized'
        "403":
          $ref: '#/components/responses/Forbidden'
        default:
          $ref: '#/components/responses/Unexpected'
    get:
      operationId: list_collections
      summary: List collections.
      description: List collections for a given user. If sort_column is not specified, 
                   the output is sorted by by last update time in descending order.
      tags:
        - Collections
      parameters:
        - name: offset
          in: query
          description: How many collections to skip before returning.
          required: false
          schema:
            type: integer
            default: 0
        - name: limit
          in: query
          description: How many collections to return.
          required: false
          schema:
            type: integer
            default: 100
        - name: sort_column
          in: query
          description: Sort column.
          required: false
          schema:
            type: string
            enum: [name, document_count, document_size, updated_at, sessions_count]
            default: updated_at
        - name: ascending
          in: query
          description: When true, returns sorted by sort_column in ascending order.
          required: false
          schema:
            type: boolean
            default: false
        - name: metadata_filter
          in: query
          description: Only returns collections with metadata matching this filter.
          required: false
          schema:
            type: string
        - name: name_filter
          in: query
          description: Only returns collections with names matching this filter.
          required: false
          schema:
            type: string
        - name: current_user_only
          in: query
          description: When true, will only return the user owned collections.
          required: false
          schema:
            type: boolean
            default: false
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Collection'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /collections/all:
    get:
      operationId: list_all_collections
      summary: Fetches all users' collection metadata sorted by last update time by default.
      description: Fetches all users' collection metadata sorted by last update time by default.
        This is for admin use only and includes private, public, and shared collections in the result.
      tags:
        - Collections
      parameters:
        - name: offset
          in: query
          description: How many collections to skip before returning.
          required: false
          schema:
            type: integer
            default: 0
        - name: limit
          in: query
          description: How many collections to return.
          required: false
          schema:
            type: integer
            default: 100
        - name: sort_column
          in: query
          description: Sort column.
          required: false
          schema:
            type: string
            enum: [ name, document_count, document_size, updated_at, sessions_count, username, expiry_date, status, inactivity_interval, archived_at]
            default: updated_at
        - name: ascending
          in: query
          description: When true, returns sorted by sort_column in ascending order.
          required: false
          schema:
            type: boolean
            default: false
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Collection'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /collections/count:
    get:
      operationId: get_collection_count
      summary: Counts a number of collections.
      description: Counts a number of collections.
      tags:
        - Collections
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Count'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /collections/{collection_id}:
    get:
      tags:
        - Collections
      summary: Get a Collection 
      description: A user can obtain a Collection by specifying its ID.
      operationId: get_collection
      parameters:
        - name: collection_id
          in: path
          description: Id of collection to return
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Collection'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'
    delete:
      tags:
        - Collections
      summary: Deletes collection.
      description: Deletes collection with a given unique identifier.
      operationId: delete_collection
      parameters:
        - name: collection_id
          in: path
          description: Id of collection to delete
          required: true
          schema:
            type: string
        - name: timeout
          in: query
          description: Timeout in seconds
          schema:
            type: number
            format: double
            default: 300
      responses:
        "204":
          description: Successful operation
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'
    patch:
      tags:
        - Collections
      summary: Updates attributes of an existing collection.
      description: Updates of an existing collection, particularly name and description.
      operationId: update_collection
      parameters:
        - name: collection_id
          in: path
          description: Id of collection to to be updated
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CollectionUpdateRequest'
        required: true
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Collection'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /collections/{collection_id}/chunks/{chunk_ids}:
    get:
      tags:
        - Collections
      summary: Returns specific chunks in a collection.
      description: Returns specific chunks in a collection.
      operationId: get_collection_chunks
      parameters:
        - name: collection_id
          in: path
          description: Id of the collection to search in
          required: true
          schema:
            type: string
        - name: chunk_ids
          in: path
          description: List of ids for the chunks to return. Chunks are indexed starting at 1.
          required: true
          schema:
            type: array
            items:
              type: integer
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Chunk'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /collections/{collection_id}/chunks/match:
    post:
      tags:
        - Collections
      summary: Finds chunks related to a message using semantic search.
      description: |
        Finds chunks related to a message using semantic search.
        Chunks are sorted by relevance and similarity score to the message.
      operationId: match_collection_chunks
      parameters:
        - name: collection_id
          in: path
          description: Id of collection to search within.
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - vectors
                - topics
              properties:
                vectors:
                  description: A list of vectorized message for running semantic search.
                  type: array
                  items:
                    type: array
                    items:
                      type: number
                      format: double
                topics:
                  description: A list of document_ids used to filter which documents in the collection to search.
                  type: array
                  items:
                    type: string
                offset:
                  description: How many chunks to skip before returning chunks.
                  type: integer
                  default: 0
                limit:
                  description: How many chunks to return.
                  type: integer
                  default: 100
                cut_off:
                  description: Exclude matches with distances higher than this cut off.
                  type: number
                  format: double
                  default: 0
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ChunkSearchResult'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /collections/{collection_id}/chunks/search:
    post:
      tags:
        - Collections
      summary: Finds chunks related to a message using lexical search.
      description: |
        Finds chunks related to a message using lexical search.
        Chunks are sorted by relevance and similarity score to the message.
      operationId: search_collection_chunks
      parameters:
        - name: collection_id
          in: path
          description: Id of the collection to search within.
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - query
                - topics
              properties:
                query:
                  description: Question or imperative from the end user to search a collection for.
                  type: string
                topics:
                  description: A list of document_ids used to filter which documents in the collection to search.
                  type: array
                  items:
                    type: string
                offset:
                  description: How many chunks to skip before returning chunks.
                  type: integer
                  default: 0
                limit:
                  description: How many chunks to return.
                  type: integer
                  default: 100
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ChunkSearchResult'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /collections/delete_job:
    post:
      tags:
        - Collections
      summary: Creates a job to delete collections.
      description: Creates a job to delete collections with a given unique identifier.
      operationId: create_delete_collection_job
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteCollectionsJobRequest'
      responses:
        "201":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobDetails'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /collections/{collection_id}/topic_model:
    post:
      operationId: create_topic_model
      summary: Creates a topic model on the collection.
      description: Creates a topic model on the collection.
      tags:
        - Models
      parameters:
        - name: collection_id
          in: path
          description: Id of the collection
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/Timeout'
      responses:
        "204":
          description: Successful operation
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /collections/{collection_id}/prompt_template:
    put:
      tags:
        - Collections
      summary: Updates a prompt template reference of a collection.
      description: Updates a prompt template reference of a collection.
      operationId: update_collection_prompt_template
      parameters:
        - name: collection_id
          in: path
          description: Id of the collection
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PromptTemplateChangeRequest'
        required: true
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Collection'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'
    delete:
      tags:
        - Collections
      summary: Removes a prompt template reference from the collection.
      description: Removes a prompt template reference from the collection.
      operationId: delete_collection_prompt_template
      parameters:
        - name: collection_id
          in: path
          description: Id of the collection
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Collection'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /collections/{collection_id}/expiry_date:
    put:
      tags:
        - Collections
      summary: Updates an expiry date of a collection.
      description: Updates an expiry date of a collection.
      operationId: update_collection_expiry_date
      parameters:
        - name: collection_id
          in: path
          description: Id of the collection
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - expiry_date
              properties:
                expiry_date:
                  description: The expiry date.
                  type: string
                  format: date
                timezone:
                  description: Optional timezone to associate with the expiry date (with IANA timezone support).
                  type: string
        required: true
      responses:
        "204":
          description: Successful operation
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'
    delete:
      tags:
        - Collections
      summary: Removes an expiry date from a collection.
      description: Removes an expiry date from a collection.
      operationId: delete_collection_expiry_date
      parameters:
        - name: collection_id
          in: path
          description: Id of the collection
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Successful operation
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /collections/{collection_id}/inactivity_interval:
    put:
      tags:
        - Collections
      summary: Updates an inactivity interval of a collection.
      description: Updates an inactivity interval of a collection.
      operationId: update_collection_inactivity_interval
      parameters:
        - name: collection_id
          in: path
          description: Id of the collection
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - inactivity_interval
              properties:
                inactivity_interval:
                  description: The inactivity interval as an integer number of days.
                  type: integer
        required: true
      responses:
        "204":
          description: Successful operation
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'
    delete:
      tags:
        - Collections
      summary: Removes an inactivity interval from the collection.
      description: Removes an inactivity interval from the collection.
      operationId: delete_collection_inactivity_interval
      parameters:
        - name: collection_id
          in: path
          description: Id of the collection
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Successful operation
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /collections/{collection_id}/archive:
    post:
      tags:
        - Collections
      summary: Archives a collection along with its associated data.
      description: Archives a collection along with its associated data.
      operationId: archive_collection
      parameters:
        - name: collection_id
          in: path
          description: Id of the collection.
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Successful operation
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'


  /collections/{collection_id}/unarchive:
    post:
      tags:
        - Collections
      summary: Restores an archived collection to an active status.
      description: Restores an archived collection to an active status.
      operationId: unarchive_collection
      parameters:
        - name: collection_id
          in: path
          description: Id of the collection.
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Successful operation
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /collections/{collection_id}/size_limit:
    put:
      tags:
        - Collections
      summary: Sets a maximum limit on the total size of documents (sum) added to a collection.
      description: Sets a maximum limit on the total size of documents (sum) added to a collection.
        The limit is measured in bytes.
      operationId: set_collection_size_limit
      parameters:
        - name: collection_id
          in: path
          description: Id of the collection.
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - size_limit
              properties:
                size_limit:
                  description: The bytes limit
                  example: 12345, 1GB, 1GiB
                  type: string
        required: true
      responses:
        "204":
          description: Successful operation
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'
    delete:
      tags:
        - Collections
      summary: Removes a size limit for a collection.
      description: Removes a size limit for a collection.
      operationId: remove_collection_size_limit
      parameters:
        - name: collection_id
          in: path
          description: Id of the collection.
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Successful operation
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'


  /collections/{collection_id}/is_public:
    post:
      tags:
        - Collections
      summary: Updates a flag specifying whether a collection is private or public.
      description: Updates a flag specifying whether a collection is private or public.
      operationId: update_collection_privacy
      parameters:
        - name: collection_id
          in: path
          description: Id of the collection.
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - is_public
              properties:
                is_public:
                  description: A flag specifying whether a collection is private or public.
                  type: boolean
        required: true
      responses:
        "204":
          description: Successful operation
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /collections/{collection_id}/settings:
    get:
      operationId: get_collection_settings
      summary: Fetches collection settings.
      description: Returns details of collection settings
      tags:
        - Collections
      parameters:
        - name: collection_id
          in: path
          description: Id of the collection associated with the settings
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionSettings'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'
    put:
      operationId: update_collection_settings
      summary: Updates collection settings.
      description: Recreates entire settings on the collection.
      tags:
        - Collections
      parameters:
        - name: collection_id
          in: path
          description: Id of the collection
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CollectionSettings'
      responses:
        "204":
          description: Successful operation
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /collections/{collection_id}/prompt_settings:
    delete:
      operationId: reset_collection_prompt_settings
      summary: Resets the prompt settings for a given collection.
      description: Resets the prompt settings for a given collection.
      tags:
        - Collections
      parameters:
        - name: collection_id
          in: path
          description: Id of the collection
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Successful operation
        "401":
          $ref: '#/components/responses/Unauthorized'
        "409":
          $ref: '#/components/responses/Conflict'
        default:
          $ref: '#/components/responses/Unexpected'


  /collections/{collection_id}/metadata:
    get:
      operationId: get_collection_metadata
      summary: Fetches collection metadata.
      description: Returns details of collection metadata.
      tags:
        - Collections
      parameters:
        - name: collection_id
          in: path
          description: Id of the collection associated with metadata.
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Metadata'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'
    put:
      operationId: update_collection_metadata
      summary: Updates collection metadata.
      description: Recreates entire metadata of the collection.
      tags:
        - Collections
      parameters:
        - name: collection_id
          in: path
          description: Id of the collection
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Metadata'
      responses:
        "204":
          description: Successful operation
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /collections/{collection_id}/thumbnail:
    put:
      operationId: update_collection_thumbnail
      summary: Updates collection thumbnail.
      description: Uploads a new thumbnail image for the collection.
      tags:
        - Collections
      parameters:
        - name: collection_id
          in: path
          description: Id of the collection
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/Timeout'
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
        required: true
      responses:
        "204":
          description: Successful operation
        "401":
          $ref: '#/components/responses/Unauthorized'
        "413":
          $ref: '#/components/responses/RequestEntityTooLarge'
        "415":
          $ref: '#/components/responses/UnsupportedMediaType'
        default:
          $ref: '#/components/responses/Unexpected'
    delete:
      operationId: delete_collection_thumbnail
      summary: Deletes collection thumbnail.
      description: Deletes collection thumbnail image.
      tags:
        - Collections
      parameters:
        - name: collection_id
          in: path
          description: Id of the collection
          required: true
          schema:
            type: string
        - name: timeout
          in: query
          description: Timeout in seconds
          schema:
            type: number
            format: double
            default: 300
      responses:
        "204":
          description: Successful operation
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /collections/{collection_id}/thumbnail/job:
    put:
      operationId: create_update_collection_thumbnail_job
      summary: Creates a job to update collection thumbnail.
      description: Creates a job to update a new thumbnail image for the collection.
      tags:
        - Collections
      parameters:
        - name: collection_id
          in: path
          description: Id of the collection
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/Timeout'
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
        required: true
      responses:
        "201":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobDetails'
        "401":
          $ref: '#/components/responses/Unauthorized'
        "413":
          $ref: '#/components/responses/RequestEntityTooLarge'
        "415":
          $ref: '#/components/responses/UnsupportedMediaType'
        default:
          $ref: '#/components/responses/Unexpected'
    delete:
      operationId: create_delete_collection_thumbnail_job
      summary: Creates a job to delete collection thumbnail.
      description: Creates a job to delete collection thumbnail image.
      tags:
        - Collections
      parameters:
        - name: collection_id
          in: path
          description: Id of the collection
          required: true
          schema:
            type: string
      responses:
        "201":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobDetails'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /collections/{collection_id}/chat_settings:
    get:
      operationId: get_collection_chat_settings
      summary: Fetches collection chat settings.
      description: Returns details of collection chat settings
      tags:
        - Collections
      parameters:
        - name: collection_id
          in: path
          description: Id of the collection associated with the chat settings
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatSettings'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'
    put:
      operationId: update_collection_chat_settings
      summary: Updates collection chat settings.
      description: Recreates entire chat settings on the collection.
      tags:
        - Collections
      parameters:
        - name: collection_id
          in: path
          description: Id of the collection
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatSettings'
      responses:
        "204":
          description: Successful operation
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /collections/{collection_id}/documents:
    get:
      operationId: list_documents_for_collection
      summary: List a Collection's documents 
      description: A user can list a Collection's documents. 
      tags:
        - Collections
      parameters:
        - name: collection_id
          in: path
          description: This parameter refers to the unique identifier ( ID) of the Collection to filter results.
          required: true
          schema:
            type: string
        - name: offset
          in: query
          description: This parameter refers to the number of documents to skip before retrieving results.
          required: false
          schema:
            type: integer
            default: 0
        - name: limit
          in: query
          description: This parameter refers to the maximum number of documents to return in the result set.
          required: false
          schema:
            type: integer
            default: 100
        - name: metadata_filter
          in: query
          description: String containing metadata json dict to filter documents by metadata.
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Document'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /collections/{collection_id}/documents/{document_id}:
    put:
      operationId: insert_document_into_collection
      summary: Import an already stored document to an existing collection.
      description: Import an already stored document to an existing collection.
      tags:
        - Collections
      parameters:
        - name: collection_id
          in: path
          description: Id of the collection to remove the document from.
          required: true
          schema:
            type: string
        - name: document_id
          in: path
          description: Id of the document to be inserted.
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/CopyDocument'
        - $ref: '#/components/parameters/IngestionParameterGenDocSummaries'
        - $ref: '#/components/parameters/IngestionParameterGenDocQuestions'
        - $ref: '#/components/parameters/IngestionParameterOcrModel'
        - $ref: '#/components/parameters/IngestionParameterTesseractLang'
        - $ref: '#/components/parameters/IngestionParameterKeepTablesAsOneChunk'
        - $ref: '#/components/parameters/IngestionParameterChunkByPage'
        - $ref: '#/components/parameters/IngestionParameterHandwritingCheck'
        - $ref: '#/components/parameters/IngestionParameterIngestMode'
        - $ref: '#/components/parameters/Timeout'
      responses:
        "204":
          description: Successful operation
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'
    delete:
      operationId: delete_document_from_collection
      summary: Removes the document from the collection.
      description: Removes the document from the collection.
      tags:
        - Collections
      parameters:
        - name: collection_id
          in: path
          description: Id of the collection to remove the document from.
          required: true
          schema:
            type: string
        - name: document_id
          in: path
          description: Id of the document to be removed.
          required: true
          schema:
            type: string
        - name: timeout
          in: query
          description: Timeout in seconds
          schema:
            type: number
            format: double
            default: 300
      responses:
        "204":
          description: Successful operation
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /collections/{collection_id}/documents/insert_job:
    post:
      operationId: create_insert_document_to_collection_job
      summary: Creates job to insert document to the collection.
      description: Creates job to insert document to the collection.
      tags:
        - Collections
      parameters:
        - name: collection_id
          in: path
          description: Id of the collection where the document will be inserted into.
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/CopyDocument'
        - $ref: '#/components/parameters/IngestionParameterGenDocSummaries'
        - $ref: '#/components/parameters/IngestionParameterGenDocQuestions'
        - $ref: '#/components/parameters/IngestionParameterOcrModel'
        - $ref: '#/components/parameters/IngestionParameterTesseractLang'
        - $ref: '#/components/parameters/IngestionParameterKeepTablesAsOneChunk'
        - $ref: '#/components/parameters/IngestionParameterChunkByPage'
        - $ref: '#/components/parameters/IngestionParameterHandwritingCheck'
        - $ref: '#/components/parameters/IngestionParameterIngestMode'
        - $ref: '#/components/parameters/Timeout'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - document_id
              properties:
                document_id:
                  description: Id of the document to be inserted.
                  type: string
      responses:
        "201":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobDetails'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'
  /collections/{collection_id}/documents/delete_job:
    post:
      operationId: create_delete_document_from_collection_job
      summary: Creates job to remove documents from the collection.
      description: Creates job to remove documents from the collection.
      tags:
        - Collections
      parameters:
        - name: collection_id
          in: path
          description: Id of the collection to remove the document from.
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteDocumentsJobRequest'
      responses:
        "201":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobDetails'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /collections/{collection_id}/documents/count:
    get:
      operationId: get_document_count_for_collection
      summary: Counts a number of documents in the collection.
      description: Counts a number of documents in the collection.
      tags:
        - Collections
      parameters:
        - name: collection_id
          in: path
          description: Id of the collection to filter by.
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Count'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /collections/{collection_id}/chats:
    get:
      operationId: list_chat_sessions_for_collection
      summary: List chat sessions for a given collection.
      description: List chat sessions for a given collection.
      tags:
        - Collections
      parameters:
        - name: collection_id
          in: path
          description: Id of the collection to filter by.
          required: true
          schema:
            type: string
        - name: offset
          in: query
          description: How many chat sessions to skip before returning.
          required: false
          schema:
            type: integer
            default: 0
        - name: limit
          in: query
          description: How many chat sessions to return.
          required: false
          schema:
            type: integer
            default: 100
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ChatSession'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /collections/{collection_id}/chats/count:
    get:
      operationId: get_chat_session_count_for_collection
      summary: Counts a number of chat sessions with the collection.
      description: Counts a number of chat sessions with the collection.
      tags:
        - Collections
      parameters:
        - name: collection_id
          in: path
          description: Id of the collection to filter by.
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Count'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /collections/{collection_id}/questions:
    get:
      operationId: list_questions_for_collection
      summary: List suggested questions for a given collection.
      description: List suggested questions for a given collection.
      tags:
        - Collections
      parameters:
        - name: collection_id
          in: path
          description: Id of the collection to filter by.
          required: true
          schema:
            type: string
        - name: limit
          in: query
          description: How many questions to return.
          required: false
          schema:
            type: integer
            default: 100
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SuggestedQuestion'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'


  /collections/{collection_id}/permissions:
    get:
      tags:
        - Collections
      summary: Returns a list of access permissions for a given collection.
      description: The returned list of permissions denotes who has access to the collection.
      operationId: get_collection_permissions
      parameters:
        - name: collection_id
          in: path
          description: Id of the collection.
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SharePermission'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'
    delete:
      tags:
        - Collections
      summary: Removes sharing of a collection to all other users except the original owner.
      description: Removes sharing of a collection to all other users except the original owner.
      operationId: unshare_collection_for_all
      parameters:
        - name: collection_id
          in: path
          description: Id of the collection.
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Successful operation
        "401":
          $ref: '#/components/responses/Unauthorized'
        "409":
          $ref: '#/components/responses/Conflict'
        default:
          $ref: '#/components/responses/Unexpected'

  /collections/{collection_id}/permissions/is_granted:
    post:
      operationId: is_collection_permission_granted
      summary: Checks if collection permission is granted for a given user.
      description: Checks if collection permission is granted for a given user.
      tags:
        - Permissions
      parameters:
        - name: collection_id
          in: path
          description: Id of the collection.
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PermissionCheckRequest'
        required: true
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: boolean
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /collections/{collection_id}/permissions/{username}:
    put:
      tags:
        - Collections
      summary: Shares a collection to a user.
      description: Shares a collection template to a user.
      operationId: share_collection
      parameters:
        - name: collection_id
          in: path
          description: Id of the collection.
          required: true
          schema:
            type: string
        - name: username
          in: path
          description: User name that will obtain access to the collection
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShareCollectionRequest'
      responses:
        "204":
          description: Successful operation
        "401":
          $ref: '#/components/responses/Unauthorized'
        "409":
          $ref: '#/components/responses/Conflict'
        default:
          $ref: '#/components/responses/Unexpected'
    delete:
      tags:
        - Collections
      summary: Removes sharing of a collection to a user.
      description: Removes sharing of a collection to a user.
      operationId: unshare_collection
      parameters:
        - name: collection_id
          in: path
          description: Id of the collection.
          required: true
          schema:
            type: string
        - name: username
          in: path
          description: User name that will lose access to the collection
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Successful operation
        "401":
          $ref: '#/components/responses/Unauthorized'
        "409":
          $ref: '#/components/responses/Conflict'
        default:
          $ref: '#/components/responses/Unexpected'

  /collections/{collection_id}/group_permissions/{group_id}:
    put:
      tags:
        - Collections
      summary: Shares a collection to a group.
      description: Shares a collection to a group. The permission attribute defines the level of access,
        and which group can access the collection, the collection_id attribute
        denotes the collection to be shared.
      operationId: share_collection_with_group
      parameters:
        - name: collection_id
          in: path
          description: Id of the collection.
          required: true
          schema:
            type: string
        - name: group_id
          in: path
          description: Id of a group that will obtain access to the collection.
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShareCollectionRequest'
      responses:
        "204":
          description: Successful operation
        "401":
          $ref: '#/components/responses/Unauthorized'
        "409":
          $ref: '#/components/responses/Conflict'
        default:
          $ref: '#/components/responses/Unexpected'
    delete:
      tags:
        - Collections
      summary: Removes sharing of a collection to a user.
      description: Removes sharing of a collection to a user.
      operationId: unshare_collection_from_group
      parameters:
        - name: collection_id
          in: path
          description: Id of the collection.
          required: true
          schema:
            type: string
        - name: group_id
          in: path
          description: Id of a group that will lose access to the collection.
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Successful operation
        "401":
          $ref: '#/components/responses/Unauthorized'
        "409":
          $ref: '#/components/responses/Conflict'
        default:
          $ref: '#/components/responses/Unexpected'

  /collections/{collection_id}/import_collection_job:
    post:
      operationId: create_import_collection_to_collection_job
      summary: Creates job to import collection to the collection.
      description: Creates job to import collection to the collection.
      tags:
        - Collections
      parameters:
        - name: collection_id
          in: path
          description: Id of the destination collection.
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/CopyDocument'
        - $ref: '#/components/parameters/IngestionParameterGenDocSummaries'
        - $ref: '#/components/parameters/IngestionParameterGenDocQuestions'
        - $ref: '#/components/parameters/IngestionParameterOcrModel'
        - $ref: '#/components/parameters/IngestionParameterTesseractLang'
        - $ref: '#/components/parameters/IngestionParameterKeepTablesAsOneChunk'
        - $ref: '#/components/parameters/IngestionParameterChunkByPage'
        - $ref: '#/components/parameters/IngestionParameterHandwritingCheck'
        - $ref: '#/components/parameters/IngestionParameterIngestMode'
        - $ref: '#/components/parameters/Timeout'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - source_collection_id
              properties:
                source_collection_id:
                  description: Id of the collection to be inserted.
                  type: string
      responses:
        "201":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobDetails'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /documents:
    get:
      operationId: list_documents
      summary: List documents.
      description: List documents for a given user. If sort_column is not specified,
        the output is sorted by by last update time in descending order.
      tags:
        - Documents
      parameters:
        - name: offset
          in: query
          description: How many documents to skip before returning.
          required: false
          schema:
            type: integer
            default: 0
        - name: limit
          in: query
          description: How many documents to return.
          required: false
          schema:
            type: integer
            default: 100
        - name: sort_column
          in: query
          description: Sort column.
          required: false
          schema:
            type: string
            enum: [name, username, type, size, page_count, connector, uri, original_type, original_mtime, status, updated_at]
            default: updated_at
        - name: ascending
          in: query
          description: When true, returns sorted by sort_column in ascending order.
          required: false
          schema:
            type: boolean
            default: false
        - name: with_summaries
          in: query
          description: When true, returns also summary and summary_parameter with other common attributes of the document.
          required: false
          schema:
            type: boolean
            default: false
        - name: metadata_filter
          in: query
          description: String containing metadata json dict to filter collections by metadata.
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Document'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /documents/count:
    get:
      operationId: get_document_count
      summary: Counts a number of documents.
      description: Counts a number of documents the user has access to. If owned parameter is enabled, it counts only
                   the documents owned by the user.
      tags:
        - Documents
      parameters:
        - name: owned
          in: query
          description: If true, it counts only the documents owned by the user.
          required: false
          schema:
            type: boolean
            default: false
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Count'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /documents/{document_id}:
    get:
      tags:
        - Documents
      summary: Finds a document by id.
      description: Returns a single document by its unique identifier.
      operationId: get_document
      parameters:
        - name: document_id
          in: path
          description: Id of document to return
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Document'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'
    delete:
      tags:
        - Documents
      summary: Deletes a document.
      description: Deletes a document with a given unique identifier.
      operationId: delete_document
      parameters:
        - name: document_id
          in: path
          description: Id of document to delete
          required: true
          schema:
            type: string
        - name: timeout
          in: query
          description: Timeout in seconds
          schema:
            type: number
            format: double
            default: 300
      responses:
        "204":
          description: Successful operation
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'
    patch:
      tags:
        - Documents
      summary: Updates attributes of an existing document.
      description: Updates attributes of an existing document, particularly name and uri.
      operationId: update_document
      parameters:
        - name: document_id
          in: path
          description: Id of document to to be updated
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentUpdateRequest'
        required: true
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Document'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /documents/{document_id}/chunks:
    get:
      tags:
        - Documents
      summary: Returns all chunks for a specific document.
      description: Returns all chunks for a specific document.
      operationId: list_document_chunks
      parameters:
        - name: document_id
          in: path
          description: Id of the document.
          required: true
          schema:
            type: string
        - name: collection_id
          in: query
          description: Id of the collection the document belongs to.
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ChunkSearchResult'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /documents/process_job:
    post:
      tags:
        - Documents
      summary: Creates job to process document.
      description: |
        Processes a document to either create a global or piecewise summary/extraction/transformation of a document.
      operationId: create_process_document_job
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProcessDocumentJobRequest'
      responses:
        "201":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobDetails'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /documents/delete_job:
    post:
      tags:
        - Documents
      summary: Creates job to delete documents.
      description: Creates job to delete documents with a given unique identifier.
      operationId: create_delete_document_job
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteDocumentsJobRequest'
      responses:
        "201":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobDetails'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /documents/{document_id}/collections:
    get:
      tags:
        - Documents
      summary: Lists collections for containing a given document.
      description: Lists collections for containing a given document.
      operationId: list_collections_for_document
      parameters:
        - name: document_id
          in: path
          description: Id of the document.
          required: true
          schema:
            type: string
        - name: offset
          in: query
          description: How many collections to skip before returning.
          required: false
          schema:
            type: integer
            default: 0
        - name: limit
          in: query
          description: How many collections to return.
          required: false
          schema:
            type: integer
            default: 100
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Collection'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /documents/{document_id}/tags:
    post:
      tags:
        - Documents
      summary: Assigns a tag to the document.
      description: Assigns a tag to the document.
      operationId: create_tag_on_document
      parameters:
        - name: document_id
          in: path
          description: Id of the document to to be associated with a tag
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TagCreateRequest'
        required: true
      responses:
        "201":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tag'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /documents/{document_id}/tags/{tag_name}:
    delete:
      tags:
        - Documents
      summary: Removes a tag from a document.
      description: Removes a tag from a document.
      operationId: delete_tag_from_document
      parameters:
        - name: document_id
          in: path
          description: Id of the document to remove the tag from
          required: true
          schema:
            type: string
        - name: tag_name
          in: path
          description: Name of the tag to be removed.
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                required:
                  - tag_id
                properties:
                  tag_id:
                    type: string
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /documents/{document_id}/chats:
    get:
      operationId: list_chat_sessions_for_document
      summary: List chat sessions for a given document.
      description: List chat sessions for a given document.
      tags:
        - Documents
      parameters:
        - name: document_id
          in: path
          description: Id of the document to filter by.
          required: true
          schema:
            type: string
        - name: offset
          in: query
          description: How many chat sessions to skip before returning.
          required: false
          schema:
            type: integer
            default: 0
        - name: limit
          in: query
          description: How many chat sessions to return.
          required: false
          schema:
            type: integer
            default: 100
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ChatSession'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /documents/{document_id}/chats/count:
    get:
      operationId: get_chat_session_count_for_document
      summary: Counts a number of chat sessions with the document.
      description: Counts a number of chat sessions with the document.
      tags:
        - Documents
      parameters:
        - name: document_id
          in: path
          description: Id of the document to filter by.
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Count'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /documents/{document_id}/summaries:
    get:
      operationId: list_document_summaries
      summary: Fetches recent document summaries/extractions/transformations
      description: Fetches recent document summaries/extractions/transformations
      tags:
        - Documents
      parameters:
        - name: document_id
          in: path
          description: Id of the document to filter by.
          required: true
          schema:
            type: string
        - name: offset
          in: query
          description: How many summaries to skip before returning.
          required: false
          schema:
            type: integer
            default: 0
        - name: limit
          in: query
          description: How many summaries to return.
          required: false
          schema:
            type: integer
            default: 100
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DocumentSummary'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /documents/summaries/{summary_ids}:
    delete:
      operationId: delete_document_summaries
      summary: Deletes document summaries.
      description: Deletes document summaries.
      tags:
        - Documents
      parameters:
        - name: summary_ids
          in: path
          description: List of string ids of a document summary to delete from the system.
          required: true
          schema:
            type: array
            items:
              type: string
      responses:
        "204":
          description: Successful operation
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /documents/{document_id}/metadata:
    get:
      operationId: get_document_metadata
      summary: Fetches document metadata.
      description: Returns details of document metadata
      tags:
        - Documents
      parameters:
        - name: document_id
          in: path
          description: Id of the document associated with the metadata
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Metadata'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'
    put:
      operationId: update_document_metadata
      summary: Updates document metadata.
      description: Recreates entire metadata of the document.
      tags:
        - Documents
      parameters:
        - name: document_id
          in: path
          description: Id of the document
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Metadata'
      responses:
        "204":
          description: Successful operation
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /documents/{document_id}/user_source_file:
    get:
      operationId: get_document_user_source_file
      summary: Fetches document user source file.
      description: Returns document user source file.
      tags:
        - Documents
      parameters:
        - name: document_id
          in: path
          description: Id of the document
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful operation with data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dictionary'
        "204":
          description: Successful operation with no result
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /documents/{document_id}/page_ocr_model:
    get:
      operationId: get_document_page_ocr_model
      summary: Fetches document page ocr model.
      description: Returns document page ocr model.
      tags:
        - Documents
      parameters:
        - name: document_id
          in: path
          description: Id of the document
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful operation with data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dictionary'
        "204":
          description: Successful operation with no result
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /documents/{document_id}/page_layout:
    get:
      operationId: get_document_page_layout
      summary: Fetches document page layout.
      description: Returns document page layout.
      tags:
        - Documents
      parameters:
        - name: document_id
          in: path
          description: Id of the document
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful operation with data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dictionary'
        "204":
          description: Successful operation with no result
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /documents/{document_id}/internal_metadata:
    get:
      operationId: get_document_internal_metadata
      summary: Fetches document internal metadata.
      description: Returns document internal metadata.
      tags:
        - Documents
      parameters:
        - name: document_id
          in: path
          description: Id of the document
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful operation with data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dictionary'
        "204":
          description: Successful operation with no result
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /documents/{document_id}/guardrails_settings:
    get:
      operationId: get_document_guardrails_settings
      summary: Fetches document guardrails settings.
      description: Returns document guardrails settings.
      tags:
        - Documents
      parameters:
        - name: document_id
          in: path
          description: Id of the document
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful operation with data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GuardrailsSettings'
        "204":
          description: Successful operation with no result
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'


  /document_summaries/{summary_id}:
    get:
      operationId: get_document_summary
      summary: Fetches document summary.
      description: Fetches document summary.
      tags:
        - Documents
      parameters:
        - name: summary_id
          in: path
          description: Id of the document summary
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentSummary'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'


  /documents/{document_id}/users/{user_id}:
    put:
      operationId: add_user_document_permission
      summary: Associates a user with a document they have permission on.
      description: Associates a user with a document they have permission on.
      tags:
        - Permissions
      parameters:
        - name: document_id
          in: path
          description: Id of the document
          required: true
          schema:
            type: string
        - name: user_id
          in: path
          description: The id of the user that has the permission.
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Successful operation
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /prompt_templates:
    post:
      operationId: create_prompt_template
      summary: Creates a new prompt template.
      description: Creates a new prompt template that can be subsequently associated with a collection.
      tags:
        - Prompt Templates
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PromptTemplateCreateRequest'
        required: true
      responses:
        "201":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PromptTemplate'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'
    get:
      operationId: list_prompt_templates
      summary: List prompt templates.
      description: List all existing prompt templates.
      tags:
        - Prompt Templates
      parameters:
        - name: offset
          in: query
          description: How many prompt templates to skip before returning.
          required: false
          schema:
            type: integer
            default: 0
        - name: limit
          in: query
          description: How many prompt templates to return.
          required: false
          schema:
            type: integer
            default: 100
        - name: sort_column
          in: query
          description: Sort column.
          required: false
          schema:
            type: string
            enum: [name, description, is_default, lang, updated_at, username, user_count]
            default: updated_at
        - name: ascending
          in: query
          description: When true, returns sorted by sort_column in ascending order.
          required: false
          schema:
            type: boolean
            default: true
        - name: template_type
          in: query
          description: When set, will be used as a type filter.
          required: false
          schema:
            type: string
            enum: [all, user, system]
            default: all
        - name: filter
          in: query
          description: When set, will be used as a filter on some prompt template columns.
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PromptTemplate'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /prompt_templates/count:
    get:
      operationId: get_prompt_template_count
      summary: Counts a number of prompt templates.
      description: Counts a number of prompt templates.
      tags:
        - Prompt Templates
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Count'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /prompt_templates/default:
    get:
      tags:
        - Prompt Templates
      summary: Returns the default prompt template.
      description: Returns the default prompt template.
      operationId: get_default_prompt_template
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PromptTemplate'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /prompt_templates/{prompt_template_id}:
    get:
      tags:
        - Prompt Templates
      summary: Finds a prompt template by id.
      description: Returns a single prompt template by its unique identifier.
      operationId: get_prompt_template
      parameters:
        - name: prompt_template_id
          in: path
          description: Id of a prompt template to return
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PromptTemplate'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'
    patch:
      operationId: update_prompt_template
      summary: Updates attributes of a given prompt template.
      description: Updates attributes of a given prompt template.
      tags:
        - Prompt Templates
      parameters:
        - name: prompt_template_id
          in: path
          description: Id of a prompt template to update
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PromptTemplateUpdateRequest'
        required: true
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PromptTemplate'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'
    delete:
      tags:
        - Prompt Templates
      summary: Deletes a prompt template.
      description: Deletes a prompt template with a given unique identifier.
      operationId: delete_prompt_template
      parameters:
        - name: prompt_template_id
          in: path
          description: Id of a prompt template to delete
          required: true
          schema:
            type: array
            items:
              type: string
      responses:
        "204":
          description: Successful operation
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /prompt_templates/{prompt_template_id}/permissions:
    get:
      tags:
        - Prompt Templates
      summary: Returns a list of access permissions for a given prompt template.
      description: The returned list of permissions denotes who has access to the prompt template.
      operationId: get_prompt_template_permissions
      parameters:
        - name: prompt_template_id
          in: path
          description: Id of a prompt template
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SharePermission'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'
    put:
      tags:
        - Prompt Templates
      summary: Resets and shares a prompt template to a new list of users.
      description: Resets and shares a prompt template to a new list of users.
      operationId: reset_and_share_prompt_template
      parameters:
        - name: prompt_template_id
          in: path
          description: Id of a prompt template.
          required: true
          schema:
            type: string
      requestBody:
        required: true
        description: List of usernames the prompt template should be shared with.
        content:
          application/json:
            schema:
              type: object
              properties:
                usernames:
                  type: array
                  items:
                    type: string
      responses:
        "204":
          description: Successful operation
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'
    delete:
      tags:
        - Prompt Templates
      summary: Removes sharing of a prompt template to all other users except the original owner.
      description: Removes sharing of a prompt template to all other users except the original owner.
      operationId: unshare_prompt_template_for_all
      parameters:
        - name: prompt_template_id
          in: path
          description: Id of a prompt template
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Successful operation
        "401":
          $ref: '#/components/responses/Unauthorized'
        "409":
          $ref: '#/components/responses/Conflict'
        default:
          $ref: '#/components/responses/Unexpected'

  /prompt_templates/{prompt_template_id}/permissions/{username}:
    put:
      tags:
        - Prompt Templates
      summary: Shares a prompt template to a user.
      description: Shares a prompt template to a user.
      operationId: share_prompt_template
      parameters:
        - name: prompt_template_id
          in: path
          description: Id of a prompt template
          required: true
          schema:
            type: string
        - name: username
          in: path
          description: User name that will obtain access to the prompt template
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Successful operation
        "401":
          $ref: '#/components/responses/Unauthorized'
        "409":
          $ref: '#/components/responses/Conflict'
        default:
          $ref: '#/components/responses/Unexpected'
    delete:
      tags:
        - Prompt Templates
      summary: Removes sharing of a prompt template to a user.
      description: Removes sharing of a prompt template to a user.
      operationId: unshare_prompt_template
      parameters:
        - name: prompt_template_id
          in: path
          description: Id of a prompt template
          required: true
          schema:
            type: string
        - name: username
          in: path
          description: User name that will lose access to the prompt template
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Successful operation
        "401":
          $ref: '#/components/responses/Unauthorized'
        "409":
          $ref: '#/components/responses/Conflict'
        default:
          $ref: '#/components/responses/Unexpected'

  /tags:
    post:
      operationId: create_tag
      summary: Creates a new tag.
      description: Creates a new tag that can be subsequently associated with a document.
      tags:
        - Tags
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TagCreateRequest'
        required: true
      responses:
        "201":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tag'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'
    get:
      operationId: list_tags
      summary: List tags.
      description: List all existing tags.
      tags:
        - Tags
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Tag'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /tags/{tag_name}:
    get:
      tags:
        - Tags
      summary: Finds a tag by its name.
      description: Returns a single tag by its unique name.
      operationId: get_tag
      parameters:
        - name: tag_name
          in: path
          description: Name of a tag to return
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tag'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'
    patch:
      tags:
        - Tags
      summary: Updates attributes of a tag.
      description: Updates attributes of an existing tag, particularly description and format.
      operationId: update_tag
      parameters:
        - name: tag_name
          in: path
          description: Name of a tag to to be updated
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TagUpdateRequest'
        required: true
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tag'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /tags/{tag_names}/documents:
    get:
      operationId: list_documents_for_tags
      summary: List documents associated with a tag.
      description: List documents associated with a tag.
      tags:
        - Tags
      parameters:
        - name: tag_names
          in: path
          description: Names of a tags to return documents for
          required: true
          schema:
            type: array
            items:
              type: string
        - name: collection_id
          in: query
          description: Id of a collection containing the documents
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Document'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /uploads:
    put:
      operationId: upload_file
      description: Uploads file to H2OGPTe instance
      tags:
        - Document Ingestion
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
        required: true
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadedFile'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /uploads/{upload_ids}/ingest:
    post:
      tags:
        - Document Ingestion
      summary: Ingest uploaded document
      description: Ingests uploaded document identified to a given collection
      operationId: ingest_upload
      parameters:
        - $ref: '#/components/parameters/IngestionParameterUploadIds'
        - $ref: '#/components/parameters/IngestionParameterCollectionId'
        - $ref: '#/components/parameters/IngestionParameterGenDocSummaries'
        - $ref: '#/components/parameters/IngestionParameterGenDocQuestions'
        - $ref: '#/components/parameters/IngestionParameterAudioInputLanguage'
        - $ref: '#/components/parameters/IngestionParameterOcrModel'
        - $ref: '#/components/parameters/IngestionParameterTesseractLang'
        - $ref: '#/components/parameters/IngestionParameterKeepTablesAsOneChunk'
        - $ref: '#/components/parameters/IngestionParameterChunkByPage'
        - $ref: '#/components/parameters/IngestionParameterHandwritingCheck'
        - $ref: '#/components/parameters/IngestionParameterIngestMode'
        - $ref: '#/components/parameters/IngestionParameterRestricted'
        - $ref: '#/components/parameters/IngestionParameterPermissions'
        - $ref: '#/components/parameters/Timeout'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IngestUploadBody'
      responses:
        "204":
          description: Successful operation
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /uploads/{upload_ids}/ingest/job:
    post:
      tags:
        - Document Ingestion
      summary: Creates a job to ingest uploaded document
      description: Creates a job to ingest uploaded document identified to a given collection
      operationId: create_ingest_upload_job
      parameters:
        - $ref: '#/components/parameters/IngestionParameterUploadIds'
        - $ref: '#/components/parameters/IngestionParameterCollectionId'
        - $ref: '#/components/parameters/IngestionParameterGenDocSummaries'
        - $ref: '#/components/parameters/IngestionParameterGenDocQuestions'
        - $ref: '#/components/parameters/IngestionParameterAudioInputLanguage'
        - $ref: '#/components/parameters/IngestionParameterOcrModel'
        - $ref: '#/components/parameters/IngestionParameterTesseractLang'
        - $ref: '#/components/parameters/IngestionParameterKeepTablesAsOneChunk'
        - $ref: '#/components/parameters/IngestionParameterChunkByPage'
        - $ref: '#/components/parameters/IngestionParameterHandwritingCheck'
        - $ref: '#/components/parameters/IngestionParameterIngestMode'
        - $ref: '#/components/parameters/IngestionParameterRestricted'
        - $ref: '#/components/parameters/IngestionParameterPermissions'
        - $ref: '#/components/parameters/Timeout'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IngestUploadBody'
      responses:
        "201":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobDetails'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /ingest/file_system:
    post:
      tags:
        - Document Ingestion
      summary: Adds files from the local system into a collection.
      description: Adds files from the local system into a collection.
      operationId: ingest_from_file_system
      parameters:
        - $ref: '#/components/parameters/IngestionParameterCollectionId'
        - $ref: '#/components/parameters/IngestionParameterGenDocSummaries'
        - $ref: '#/components/parameters/IngestionParameterGenDocQuestions'
        - $ref: '#/components/parameters/IngestionParameterAudioInputLanguage'
        - $ref: '#/components/parameters/IngestionParameterOcrModel'
        - $ref: '#/components/parameters/IngestionParameterTesseractLang'
        - $ref: '#/components/parameters/IngestionParameterKeepTablesAsOneChunk'
        - $ref: '#/components/parameters/IngestionParameterChunkByPage'
        - $ref: '#/components/parameters/IngestionParameterHandwritingCheck'
        - $ref: '#/components/parameters/IngestionParameterIngestMode'
        - $ref: '#/components/parameters/Timeout'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IngestFromFileSystemBody'
      responses:
        "204":
          description: Successful operation
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /ingest/file_system/job:
    post:
      tags:
        - Document Ingestion
      summary: Creates a job to add files from the local system into a collection.
      description: Creates a job to add files from the local system into a collection.
      operationId: create_ingest_from_file_system_job
      parameters:
        - $ref: '#/components/parameters/IngestionParameterCollectionId'
        - $ref: '#/components/parameters/IngestionParameterGenDocSummaries'
        - $ref: '#/components/parameters/IngestionParameterGenDocQuestions'
        - $ref: '#/components/parameters/IngestionParameterAudioInputLanguage'
        - $ref: '#/components/parameters/IngestionParameterOcrModel'
        - $ref: '#/components/parameters/IngestionParameterTesseractLang'
        - $ref: '#/components/parameters/IngestionParameterKeepTablesAsOneChunk'
        - $ref: '#/components/parameters/IngestionParameterChunkByPage'
        - $ref: '#/components/parameters/IngestionParameterHandwritingCheck'
        - $ref: '#/components/parameters/IngestionParameterIngestMode'
        - $ref: '#/components/parameters/Timeout'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IngestFromFileSystemBody'
      responses:
        "201":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobDetails'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /ingest/plain_text:
    post:
      tags:
        - Document Ingestion
      summary: Adds plain text to a collection.
      description: Adds plain text to a collection.
      operationId: ingest_from_plain_text
      parameters:
        - $ref: '#/components/parameters/IngestionParameterCollectionId'
        - $ref: '#/components/parameters/IngestionParameterFileName'
        - $ref: '#/components/parameters/IngestionParameterGenDocSummaries'
        - $ref: '#/components/parameters/IngestionParameterGenDocQuestions'
        - $ref: '#/components/parameters/Timeout'
        - $ref: '#/components/parameters/IngestionParameterMetadata'
      requestBody:
        description: The text that will ingested into a collection.
        required: true
        content:
          text/plain:
            schema:
              type: string
      responses:
        "204":
          description: Successful operation
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /ingest/plain_text/job:
    post:
      tags:
        - Document Ingestion
      summary: Creates a job to add plain text to a collection.
      description: Creates a job to add plain text to a collection.
      operationId: create_ingest_from_plain_text_job
      parameters:
        - $ref: '#/components/parameters/IngestionParameterCollectionId'
        - $ref: '#/components/parameters/IngestionParameterFileName'
        - $ref: '#/components/parameters/IngestionParameterGenDocSummaries'
        - $ref: '#/components/parameters/IngestionParameterGenDocQuestions'
        - $ref: '#/components/parameters/IngestionParameterMetadata'
        - $ref: '#/components/parameters/Timeout'
      requestBody:
        description: The text that will ingested into a collection.
        required: true
        content:
          text/plain:
            schema:
              type: string
      responses:
        "201":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobDetails'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /ingest/website:
    post:
      tags:
        - Document Ingestion
      summary: Crawls and ingest a URL into a collection.
      description: Crawls and ingest a URL into a collection. The web page or document linked from
                   this URL will be imported.
      operationId: ingest_from_website
      parameters:
        - $ref: '#/components/parameters/IngestionParameterCollectionId'
        - $ref: '#/components/parameters/IngestionParameterFollowLinks'
        - $ref: '#/components/parameters/IngestionParameterMaxDepth'
        - $ref: '#/components/parameters/IngestionParameterMaxDocuments'
        - $ref: '#/components/parameters/IngestionParameterGenDocSummaries'
        - $ref: '#/components/parameters/IngestionParameterGenDocQuestions'
        - $ref: '#/components/parameters/IngestionParameterAudioInputLanguage'
        - $ref: '#/components/parameters/IngestionParameterOcrModel'
        - $ref: '#/components/parameters/IngestionParameterTesseractLang'
        - $ref: '#/components/parameters/IngestionParameterKeepTablesAsOneChunk'
        - $ref: '#/components/parameters/IngestionParameterChunkByPage'
        - $ref: '#/components/parameters/IngestionParameterHandwritingCheck'
        - $ref: '#/components/parameters/IngestionParameterIngestMode'
        - $ref: '#/components/parameters/Timeout'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IngestFromWebsiteBody'
      responses:
        "204":
          description: Successful operation
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /ingest/website/job:
    post:
      tags:
        - Document Ingestion
      summary: Creates a job to crawl and ingest a URL into a collection.
      description: Creates a job to crawl and ingest a URL into a collection. The web page or document linked from
        this URL will be imported.
      operationId: create_ingest_from_website_job
      parameters:
        - $ref: '#/components/parameters/IngestionParameterCollectionId'
        - $ref: '#/components/parameters/IngestionParameterFollowLinks'
        - $ref: '#/components/parameters/IngestionParameterMaxDepth'
        - $ref: '#/components/parameters/IngestionParameterMaxDocuments'
        - $ref: '#/components/parameters/IngestionParameterGenDocSummaries'
        - $ref: '#/components/parameters/IngestionParameterGenDocQuestions'
        - $ref: '#/components/parameters/IngestionParameterAudioInputLanguage'
        - $ref: '#/components/parameters/IngestionParameterOcrModel'
        - $ref: '#/components/parameters/IngestionParameterTesseractLang'
        - $ref: '#/components/parameters/IngestionParameterKeepTablesAsOneChunk'
        - $ref: '#/components/parameters/IngestionParameterChunkByPage'
        - $ref: '#/components/parameters/IngestionParameterHandwritingCheck'
        - $ref: '#/components/parameters/IngestionParameterIngestMode'
        - $ref: '#/components/parameters/Timeout'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IngestFromWebsiteBody'
      responses:
        "201":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobDetails'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /ingest/agent_only_to_standard:
    post:
      tags:
        - Document Ingestion
      summary: Converts files uploaded in "agent_only" ingest mode  to PDF and parses them.
      description: Converts files uploaded in "agent_only" ingest mode  to PDF and parses them.
      operationId: ingest_agent_only_to_standard
      parameters:
        - $ref: '#/components/parameters/IngestionParameterCollectionId'
        - $ref: '#/components/parameters/IngestionParameterDocumentId'
        - $ref: '#/components/parameters/IngestionParameterGenDocSummaries'
        - $ref: '#/components/parameters/IngestionParameterGenDocQuestions'
        - $ref: '#/components/parameters/IngestionParameterAudioInputLanguage'
        - $ref: '#/components/parameters/IngestionParameterOcrModel'
        - $ref: '#/components/parameters/IngestionParameterRestricted'
        - $ref: '#/components/parameters/IngestionParameterPermissions'
        - $ref: '#/components/parameters/IngestionParameterTesseractLang'
        - $ref: '#/components/parameters/IngestionParameterKeepTablesAsOneChunk'
        - $ref: '#/components/parameters/IngestionParameterChunkByPage'
        - $ref: '#/components/parameters/IngestionParameterHandwritingCheck'
        - $ref: '#/components/parameters/Timeout'
      responses:
        "204":
          description: Successful operation
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /ingest/agent_only_to_standard/job:
    post:
      tags:
        - Document Ingestion
      summary: Creates a job to parse files uploaded in "agent_only" ingest mode.
      description: Creates a job to parse files uploaded in "agent_only" ingest mode.
      operationId: create_ingest_agent_only_to_standard_job
      parameters:
        - $ref: '#/components/parameters/IngestionParameterCollectionId'
        - $ref: '#/components/parameters/IngestionParameterDocumentId'
        - $ref: '#/components/parameters/IngestionParameterGenDocSummaries'
        - $ref: '#/components/parameters/IngestionParameterGenDocQuestions'
        - $ref: '#/components/parameters/IngestionParameterAudioInputLanguage'
        - $ref: '#/components/parameters/IngestionParameterOcrModel'
        - $ref: '#/components/parameters/IngestionParameterRestricted'
        - $ref: '#/components/parameters/IngestionParameterPermissions'
        - $ref: '#/components/parameters/IngestionParameterTesseractLang'
        - $ref: '#/components/parameters/IngestionParameterKeepTablesAsOneChunk'
        - $ref: '#/components/parameters/IngestionParameterChunkByPage'
        - $ref: '#/components/parameters/IngestionParameterHandwritingCheck'
        - $ref: '#/components/parameters/Timeout'
      responses:
        "201":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobDetails'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /ingest/s3:
    post:
      tags:
        - Document Ingestion
      summary: Adds files from the AWS S3 storage into a collection.
      description: Adds files from the AWS S3 storage into a collection.
      operationId: ingest_from_s3
      parameters:
        - $ref: '#/components/parameters/IngestionParameterCollectionId'
        - $ref: '#/components/parameters/IngestionParameterGenDocSummaries'
        - $ref: '#/components/parameters/IngestionParameterGenDocQuestions'
        - $ref: '#/components/parameters/IngestionParameterAudioInputLanguage'
        - $ref: '#/components/parameters/IngestionParameterOcrModel'
        - $ref: '#/components/parameters/IngestionParameterTesseractLang'
        - $ref: '#/components/parameters/IngestionParameterKeepTablesAsOneChunk'
        - $ref: '#/components/parameters/IngestionParameterChunkByPage'
        - $ref: '#/components/parameters/IngestionParameterHandwritingCheck'
        - $ref: '#/components/parameters/IngestionParameterIngestMode'
        - $ref: '#/components/parameters/Timeout'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IngestFromS3Body'
      responses:
        "204":
          description: Successful operation
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /ingest/s3/job:
    post:
      tags:
        - Document Ingestion
      summary: Creates a job to add files from the AWS S3 storage into a collection.
      description: Creates a job to add files from the AWS S3 storage into a collection.
      operationId: create_ingest_from_s3_job
      parameters:
        - $ref: '#/components/parameters/IngestionParameterCollectionId'
        - $ref: '#/components/parameters/IngestionParameterGenDocSummaries'
        - $ref: '#/components/parameters/IngestionParameterGenDocQuestions'
        - $ref: '#/components/parameters/IngestionParameterAudioInputLanguage'
        - $ref: '#/components/parameters/IngestionParameterOcrModel'
        - $ref: '#/components/parameters/IngestionParameterTesseractLang'
        - $ref: '#/components/parameters/IngestionParameterKeepTablesAsOneChunk'
        - $ref: '#/components/parameters/IngestionParameterChunkByPage'
        - $ref: '#/components/parameters/IngestionParameterHandwritingCheck'
        - $ref: '#/components/parameters/IngestionParameterIngestMode'
        - $ref: '#/components/parameters/Timeout'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IngestFromS3Body'
      responses:
        "201":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobDetails'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /ingest/gcs:
    post:
      tags:
        - Document Ingestion
      summary: Adds files from the Google Cloud Storage into a collection.
      description: Adds files from the Google Cloud Storage into a collection.
      operationId: ingest_from_gcs
      parameters:
        - $ref: '#/components/parameters/IngestionParameterCollectionId'
        - $ref: '#/components/parameters/IngestionParameterGenDocSummaries'
        - $ref: '#/components/parameters/IngestionParameterGenDocQuestions'
        - $ref: '#/components/parameters/IngestionParameterAudioInputLanguage'
        - $ref: '#/components/parameters/IngestionParameterOcrModel'
        - $ref: '#/components/parameters/IngestionParameterTesseractLang'
        - $ref: '#/components/parameters/IngestionParameterKeepTablesAsOneChunk'
        - $ref: '#/components/parameters/IngestionParameterChunkByPage'
        - $ref: '#/components/parameters/IngestionParameterHandwritingCheck'
        - $ref: '#/components/parameters/IngestionParameterIngestMode'
        - $ref: '#/components/parameters/Timeout'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IngestFromGcsBody'
      responses:
        "204":
          description: Successful operation
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /ingest/gcs/job:
    post:
      tags:
        - Document Ingestion
      summary: Creates a job to add files from the Google Cloud Storage into a collection.
      description: Creates a job to add files from the Google Cloud Storage into a collection.
      operationId: create_ingest_from_gcs_job
      parameters:
        - $ref: '#/components/parameters/IngestionParameterCollectionId'
        - $ref: '#/components/parameters/IngestionParameterGenDocSummaries'
        - $ref: '#/components/parameters/IngestionParameterGenDocQuestions'
        - $ref: '#/components/parameters/IngestionParameterAudioInputLanguage'
        - $ref: '#/components/parameters/IngestionParameterOcrModel'
        - $ref: '#/components/parameters/IngestionParameterTesseractLang'
        - $ref: '#/components/parameters/IngestionParameterKeepTablesAsOneChunk'
        - $ref: '#/components/parameters/IngestionParameterChunkByPage'
        - $ref: '#/components/parameters/IngestionParameterHandwritingCheck'
        - $ref: '#/components/parameters/IngestionParameterIngestMode'
        - $ref: '#/components/parameters/Timeout'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IngestFromGcsBody'
      responses:
        "201":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobDetails'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /ingest/azure_blob_storage:
    post:
      tags:
        - Document Ingestion
      summary: Adds files from the Azure Blob Storage into a collection.
      description: Adds files from the Azure Blob Storage into a collection.
      operationId: ingest_from_azure_blob_storage
      parameters:
        - $ref: '#/components/parameters/IngestionParameterCollectionId'
        - $ref: '#/components/parameters/IngestionParameterGenDocSummaries'
        - $ref: '#/components/parameters/IngestionParameterGenDocQuestions'
        - $ref: '#/components/parameters/IngestionParameterAudioInputLanguage'
        - $ref: '#/components/parameters/IngestionParameterOcrModel'
        - $ref: '#/components/parameters/IngestionParameterTesseractLang'
        - $ref: '#/components/parameters/IngestionParameterKeepTablesAsOneChunk'
        - $ref: '#/components/parameters/IngestionParameterChunkByPage'
        - $ref: '#/components/parameters/IngestionParameterHandwritingCheck'
        - $ref: '#/components/parameters/IngestionParameterIngestMode'
        - $ref: '#/components/parameters/Timeout'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IngestFromAzureBlobStorageBody'
      responses:
        "204":
          description: Successful operation
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /ingest/azure_blob_storage/job:
    post:
      tags:
        - Document Ingestion
      summary: Creates a job to add files from the Azure Blob Storage into a collection.
      description: Creates a job to add files from the Azure Blob Storage into a collection.
      operationId: create_ingest_from_azure_blob_storage_job
      parameters:
        - $ref: '#/components/parameters/IngestionParameterCollectionId'
        - $ref: '#/components/parameters/IngestionParameterGenDocSummaries'
        - $ref: '#/components/parameters/IngestionParameterGenDocQuestions'
        - $ref: '#/components/parameters/IngestionParameterAudioInputLanguage'
        - $ref: '#/components/parameters/IngestionParameterOcrModel'
        - $ref: '#/components/parameters/IngestionParameterTesseractLang'
        - $ref: '#/components/parameters/IngestionParameterKeepTablesAsOneChunk'
        - $ref: '#/components/parameters/IngestionParameterChunkByPage'
        - $ref: '#/components/parameters/IngestionParameterHandwritingCheck'
        - $ref: '#/components/parameters/IngestionParameterIngestMode'
        - $ref: '#/components/parameters/Timeout'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IngestFromAzureBlobStorageBody'
      responses:
        "201":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobDetails'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /chats:
    post:
      tags:
        - Chat
      summary: Creates chat session.
      description: Creates chat session with a collection if provided. Otherwise, the session will be with a generic LLM.
      operationId: create_chat_session
      parameters:
        - name: collection_id
          in: query
          description: Id of collection
          required: false
          schema:
            type: string
      responses:
        "201":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatSession'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'
    get:
      operationId: list_chat_sessions
      summary: List chat sessions.
      description: List chat sessions.
      tags:
        - Chat
      parameters:
        - name: offset
          in: query
          description: How many chat sessions to skip before returning.
          required: false
          schema:
            type: integer
            default: 0
        - name: limit
          in: query
          description: How many chat sessions to return.
          required: false
          schema:
            type: integer
            default: 100
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ChatSession'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /chats/count:
    get:
      operationId: get_chat_session_count
      summary: Counts a number of chat sessions.
      description: Counts a number of chat sessions.
      tags:
        - Chat
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Count'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /chats/delete_job:
    post:
      tags:
        - Chat
      summary: Creates job to delete chat sessions.
      description: Creates job to delete chat sessions.
      operationId: create_delete_chat_session_job
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteChatSessionsJobRequest'
      responses:
        "201":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobDetails'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /chats/{session_id}:
    get:
      tags:
        - Chat
      summary: Finds a chat session by id.
      description: Returns a single chat session by its unique identifier.
      operationId: get_chat_session
      parameters:
        - name: session_id
          in: path
          description: Id of the chat session
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatSession'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'
    delete:
      tags:
        - Chat
      summary: Deletes collection.
      description: Deletes collection with a given unique identifier.
      operationId: delete_chat_session
      parameters:
        - name: session_id
          in: path
          description: Id of the chat session
          required: true
          schema:
            type: string
        - name: timeout
          in: query
          description: Timeout in seconds
          schema:
            type: number
            format: double
            default: 300
      responses:
        "204":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatSession'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'
    patch:
      tags:
        - Chat
      summary: Updates the name of a chat session.
      description: Updates the name of a chat session.
      operationId: update_chat_session
      parameters:
        - name: session_id
          in: path
          description: Id of the chat session
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatSessionUpdateRequest'
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatSession'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /chats/{session_id}/collection:
    put:
      tags:
        - Chat
      summary: Updates a collection reference of a chat session.
      description: Updates a collection reference of a chat session.
      operationId: update_chat_session_collection
      parameters:
        - name: session_id
          in: path
          description: Id of the chat session
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CollectionChangeRequest'
        required: true
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatSession'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'
    delete:
      tags:
        - Chat
      summary: Removes a collection reference from the chat session.
      description: Removes a collection reference from the chat session.
      operationId: delete_chat_session_collection
      parameters:
        - name: session_id
          in: path
          description: Id of the chat session
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatSession'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /chats/{session_id}/prompt_template:
    put:
      tags:
        - Chat
      summary: Updates a prompt template reference of a chat session.
      description: Updates a prompt template reference of a chat session.
      operationId: update_chat_session_prompt_template
      parameters:
        - name: session_id
          in: path
          description: Id of the chat session
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PromptTemplateChangeRequest'
        required: true
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatSession'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'
    delete:
      tags:
        - Chat
      summary: Removes a prompt template reference from the chat session.
      description: Removes a prompt template reference from the chat session.
      operationId: delete_chat_session_prompt_template
      parameters:
        - name: session_id
          in: path
          description: Id of the chat session
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatSession'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /chats/{session_id}/agent_server_files:
    get:
      operationId: list_agent_server_files
      summary: Lists agent server files.
      description: Lists agent server files.
      tags:
        - Chat
      parameters:
        - name: session_id
          in: path
          description: Id of the chat session
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AgentServerFile'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'
    delete:
      operationId: delete_agent_server_files
      summary: Deletes agent server files.
      description: Deletes agent server files.
      tags:
        - Chat
      parameters:
        - name: session_id
          in: path
          description: Id of the chat session
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Successful operation
        "401":
          $ref: '#/components/responses/Unauthorized'
        "409":
          $ref: '#/components/responses/Conflict'
        default:
          $ref: '#/components/responses/Unexpected'

  /chats/{session_ids}/agent_server_directories:
    delete:
      operationId: delete_agent_server_directories
      summary: Deletes agent server directories.
      description: Deletes agent server directories.
      tags:
        - Chat
      parameters:
        - name: session_ids
          in: path
          description: Id of the chat session
          required: true
          schema:
            type: array
            items:
              type: string
        - name: dir_types
          in: query
          description: Types of agent directories to be deleted
          required: false
          schema:
            type: array
            items:
              type: string
      responses:
        "204":
          description: Successful operation
        "401":
          $ref: '#/components/responses/Unauthorized'
        "409":
          $ref: '#/components/responses/Conflict'
        default:
          $ref: '#/components/responses/Unexpected'

  /chats/{session_id}/agent_server_directories/stats:
    get:
      operationId: list_all_agent_server_directories_stats
      summary: Lists stats of  agent server directories.
      description: Lists stats of agent server directories.
      tags:
        - Chat
      parameters:
        - name: session_id
          in: path
          description: Id of the chat session
          required: true
          schema:
            type: string
        - name: detail_level
          in: query
          description: the higher value, more details are returned.
          required: false
          schema:
            type: integer
            default: 0
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AgentServerDirectoryStats'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /chats/{session_id}/agent_server_directories/{directory_name}/stats:
    get:
      operationId: get_agent_server_directory_stats
      summary: Gets stats of a agent server directory.
      description: Gets stats of a agent server directory.
      tags:
        - Chat
      parameters:
        - name: session_id
          in: path
          description: Id of the chat session
          required: true
          schema:
            type: string
        - name: directory_name
          in: path
          description: Directory name
          required: true
          schema:
            type: string
        - name: detail_level
          in: query
          description: the higher value, more details are returned.
          required: false
          schema:
            type: integer
            default: 0
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentServerDirectoryStats'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /chats/{session_id}/completions:
    post:
      operationId: get_completion
      description: Asks question in a given chat session. If stream is enabled, 
                   the server sends stream of delta messages. The stream is terminated with the massage having property
                   finished set to true. This message terminating message contains also the full completion.
      tags:
        - Chat
      parameters:
        - name: session_id
          in: path
          description: Id of a chat session
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatCompletionRequest'
        required: true
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                 $ref: '#/components/schemas/ChatCompletion'
            application/jsonl:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/ChatCompletionDelta'
                  - $ref: '#/components/schemas/ChatError'
        "401":
          $ref: '#/components/responses/Unauthorized'
        "500":
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/Unexpected'

  /chats/{session_id}/questions:
    get:
      operationId: list_questions_for_chat_session
      summary: List suggested questions for a given chat session.
      description: List suggested questions for a given chat session.
      tags:
        - Chat
      parameters:
        - name: session_id
          in: path
          description: Id of a chat session
          required: true
          schema:
            type: string
        - name: limit
          in: query
          description: How many questions to return.
          required: false
          schema:
            type: integer
            default: 100
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SuggestedQuestion'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'


  /chats/{session_id}/messages:
    get:
      tags:
        - Chat
      summary: Fetches chat message and metadata for messages in a chat session.
      description: Fetches chat message and metadata for messages in a chat session.
                   Messages without a `reply_to` are from the end user, messages with a `reply_to`
                   are from an LLM and a response to a specific user message.
      operationId: get_chat_session_messages
      parameters:
        - name: session_id
          in: path
          description: Id of the chat session
          required: true
          schema:
            type: string
        - name: offset
          in: query
          description: How many chat sessions to skip before returning.
          required: false
          schema:
            type: integer
            default: 0
        - name: limit
          in: query
          description: How many chat sessions to return.
          required: false
          schema:
            type: integer
            default: 100
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ChatMessage'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /messages/{message_ids}:
    delete:
      tags:
        - Chat
      summary: Deletes specific chat messages.
      description: Deletes specific chat messages.
      operationId: delete_messages
      parameters:
        - name: message_ids
          in: path
          description: Ids of messages to be deleted
          required: true
          schema:
            type: array
            items:
              type: string
      responses:
        "204":
          description: Successful operation
        "401":
          $ref: '#/components/responses/Unauthorized'
        "409":
          $ref: '#/components/responses/Conflict'
        default:
          $ref: '#/components/responses/Unexpected'

  /messages/{message_id}/references:
    get:
      tags:
        - Chat
      summary: Fetches metadata for references of a chat message.
      description: Fetches metadata for references of a chat message. 
                   References are only available for messages sent from an LLM, an empty list will be returned
                   for messages sent by the user.
      operationId: get_message_references
      parameters:
        - name: message_id
          in: path
          description: Id of the chat message
          required: true
          schema:
            type: string
        - name: limit
          in: query
          description: The number of references to consider based on the highest confidence scores.
          required: false
          schema:
            type: integer
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ChatMessageReference'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /messages/{message_id}/meta:
    get:
      tags:
        - Chat
      summary: Fetches chat message meta information.
      description: Fetches chat message meta information.
      operationId: get_message_meta
      parameters:
        - name: message_id
          in: path
          description: Id of the chat message.
          required: true
          schema:
            type: string
        - name: info_type
          in: query
          description: Metadata type to fetch.
          required: false
          schema:
            type: string
            enum: [self_reflection, usage_stats, prompt_raw, llm_only, hyde1]
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ChatMessageMeta'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /messages/{message_id}/votes:
    put:
      tags:
        - Chat
      summary: Changes the vote value of a chat message.
      description: Set the exact value of a vote for a chat message. Any message type can be updated,
        but only LLM response votes will be visible in the UI. The expectation is 0 - unvoted, -1 - dislike, 1 - like. 
        Values outside of this will not be viewable in the UI.
      operationId: set_message_votes
      parameters:
        - name: message_id
          in: path
          description: Id of the chat message.
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MessageVoteUpdateRequest'
        required: true
      responses:
        "204":
          description: Successful operation
        "401":
          $ref: '#/components/responses/Unauthorized'
        "409":
          $ref: '#/components/responses/Conflict'
        default:
          $ref: '#/components/responses/Unexpected'

  /question_answer_feedbacks:
    get:
      tags:
        - Chat
      summary: Lists user's questions and answers that have a feedback.
      description: Lists user's questions and answers that have a feedback.
      operationId: list_question_answer_feedbacks
      parameters:
        - name: offset
          in: query
          description: How many feedbacks to skip before returning.
          required: false
          schema:
            type: integer
            default: 0
        - name: limit
          in: query
          description: How many feedbacks to return.
          required: false
          schema:
            type: integer
            default: 100
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/QAFeedback'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /question_answer_feedbacks/{answer_id}:
    post:
      tags:
        - Chat
      summary: Update feedback for a specific answer to a question.
      description: Update feedback for a specific answer to a question.
      operationId: update_question_answer_feedback
      parameters:
        - name: answer_id
          in: path
          description: Unique identifier of and answer connected with a feedback.
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateQAFeedbackRequest'
        required: true
      responses:
        "204":
          description: Successful operation
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /question_answer_feedbacks/count:
    get:
      operationId: get_question_answer_feedback_count
      summary: Counts a number of question-answer feedbacks.
      description: Counts a number of question-answer feedbacks.
      tags:
        - Chat
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Count'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /jobs:
    get:
      operationId: list_jobs
      summary: Lists jobs associated with the user.
      description: Lists jobs associated with the user making call.
      tags:
        - Jobs
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/JobDetails'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /jobs/pending/count:
    get:
      operationId: count_pending_jobs
      summary: Counts the number of global, pending jobs on the server.
      description: Counts the number of global, pending jobs on the server.
      tags:
        - Jobs
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CountWithQueueDetails'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /jobs/{job_id}:
    get:
      operationId: get_job
      summary: Lists jobs associated with the user.
      description: Lists jobs associated with the user calling this endpoint.
      tags:
        - Jobs
      parameters:
        - name: job_id
          in: path
          description: Id of the job
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobDetails'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'
    delete:
      operationId: delete_job
      summary: Deletes job.
      description: Deletes job with a given unique identifier.
      tags:
        - Jobs
      parameters:
        - name: job_id
          in: path
          description: Id of the job
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Successful operation
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /jobs/{job_id}/cancel:
    post:
      operationId: cancel_job
      summary:  Stops a specific job from running for the user.
      description: Stops a specific job from running for the user.
      tags:
        - Jobs
      parameters:
        - name: job_id
          in: path
          description: Id of the job
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobDetails'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /user_jobs:
    get:
      operationId: list_user_jobs
      summary: Lists all jobs running on the system for all users.
      description: Lists all jobs running on the system for all users (to be used by admins only).
      tags:
        - Jobs
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserJobDetails'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /user_jobs/{job_id}/cancel:
    post:
      operationId: cancel_user_job
      summary:  Stops a specific job from running on the server.
      description: As an admin, stops a specific user job from running on the server.
      tags:
        - Jobs
      parameters:
        - name: job_id
          in: path
          description: Id of the job
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Successful operation
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /models:
    get:
      operationId: list_models
      summary: Lists all available large language models.
      description: Lists all available large language models.
      tags:
        - Models
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Model'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /embedding_models:
    get:
      operationId: list_embedding_models
      summary: Lists all available embedding models.
      description: Lists all available embedding models.
      tags:
        - Models
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/EmbeddingModel'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /embedding_models/default:
    get:
      operationId: get_default_embedding_model
      summary: Gets default embedding model.
      description: Gets default embedding model.
      tags:
        - Models
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmbeddingModel'
        "401":
          $ref: '#/components/responses/Unauthorized'
        "404":
          $ref: '#/components/responses/NotFound'
        default:
          $ref: '#/components/responses/Unexpected'

  /embedding_models/{model_id}/encode_chunks_for_retrieval:
    post:
      operationId: encode_chunks_for_retrieval
      summary: Encode texts for semantic searching.
      description: Encode texts for semantic searching.
      tags:
        - Models
      parameters:
        - name: model_id
          in: path
          description: Id of the embedding model that will be used for operation.
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - chunks
              properties:
                chunks:
                  type: array
                  items:
                    type: string
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  type: array
                  items:
                    type: number
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /models/create_topic_model_job:
    post:
      operationId: create_topic_model_job
      summary: Creates job for creation of a topic model.
      description: Creates job for creation of a topic model.
      tags:
        - Models
      parameters:
        - $ref: '#/components/parameters/Timeout'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - collection_id
              properties:
                collection_id:
                  type: string
      responses:
        "201":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobDetails'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /models/{model_name}/self_test/{mode}:
    post:
      operationId: run_model_self_test
      summary: Runs a self-test for a given model.
      description: Runs a self-test for a given model.
      tags:
        - Models
      parameters:
        - name: model_name
          in: path
          description: Name of LLM.
          required: true
          schema:
            type: string
        - name: mode
          in: path
          description: Mode of the self test.
          required: true
          schema:
            type: string
            enum: [quick, rag, full, agent]
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SelfTestResult'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /models/{model_name}/answer_question:
    post:
      operationId: answer_question
      summary: Send a message and get a response from an LLM.
      description: |
        Send a message and get a response from an LLM.
        Note: This method is only recommended if you are passing a chat conversation or for low-volume testing.
              For general chat with an LLM, use "POST /chats/{session_id}/completions" endpoint.
      tags:
        - Models
      parameters:
        - name: model_name
          in: path
          description: Name of LLM. Use auto, when you are not interested in particular model.
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QuestionRequest'
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelAnswer'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /models/{model_name}/summarize_content:
    post:
      operationId: summarize_content
      summary: Summarize one or more contexts using an LLM.
      description: Summarize one or more contexts using an LLM.
      tags:
        - Models
      parameters:
        - name: model_name
          in: path
          description: Name of LLM. Use auto, when you are not interested in particular model.
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SummarizeRequest'
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelAnswer'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /models/{model_name}/extract_data:
    post:
      operationId: extract_data
      summary: Extract information from one or more contexts using an LLM.
      description: |
        Extract information from one or more contexts using an LLM.
        `pre_prompt_extract` and `prompt_extract` variables must be used together. If these
                variables are not set, the inputs texts will be summarized into bullet points.
      tags:
        - Models
      parameters:
        - name: model_name
          in: path
          description: Name of LLM. Use auto, when you are not interested in particular model.
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExtractionRequest'
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelExtractionAnswer'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /models/vision_capable_model_names:
    get:
      operationId: get_vision_capable_model_names
      summary: Lists names of available vision-capable multi-modal LLMs in the environment.
      description: Lists names of available vision-capable multi-modal LLMs (that can natively handle images as input) in the environment.
      tags:
        - Models
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /models/model_to_vision_model_mapping:
    get:
      operationId: get_model_to_vision_model_mapping
      summary: Get mapping of llm to its vision_model when ["auto"] is passed as visible_vision_models.
      description: Get mapping of llm to its vision_model when ["auto"] is passed as visible_vision_models.
      tags:
        - Models
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: string
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /models/reasoning_capable_model_names:
    get:
      operationId: get_reasoning_capable_model_names
      summary: Lists names of available reasoning-capable (that can natively reason) in the environment.
      description: Lists names of available reasoning-capable (that can natively reason) in the environment.
      tags:
        - Models
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /models/model_to_reasoning_model_mapping:
    get:
      operationId: get_model_to_reasoning_model_mapping
      summary: Get mapping of llm to its reasoning_model when ["auto"] is passed as visible_reasoning_models.
      description: Get mapping of llm to its reasoning_model when ["auto"] is passed as visible_reasoning_models.
      tags:
        - Models
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: string
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /guardrails_settings:
    post:
      operationId: create_guardrails_settings
      summary: Helper to get reasonable (easy to use) defaults for Guardrails/PII settings.
      description: Helper to get reasonable (easy to use) defaults for Guardrails/PII settings. To be further customized.
      tags:
        - Models
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GuardrailsSettingsCreateRequest'
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GuardrailsSettings'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /stats/usage:
    get:
      operationId: get_usage_stats
      summary: Returns usage statistics for all models.
      description: Returns usage statistics for all models.
      tags:
        - Models
      parameters:
        - name: interval
          in: query
          description: The length of an interval for which the stats will be obtained. The interval ends now.
          example: 24 hours
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageStats'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /stats/usage_by_model:
    get:
      operationId: get_usage_stats_by_model
      summary: Returns usage statistics grouped by models.
      description: Returns usage statistics grouped by models.
      tags:
        - Models
      parameters:
        - name: interval
          in: query
          description: The length of an interval for which the stats will be obtained. The interval ends now.
          example: 24 hours
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UsageStatsPerModel'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /stats/usage_by_user:
    get:
      operationId: get_usage_stats_by_user
      summary: Returns usage statistics grouped by users.
      description: Returns usage statistics grouped by users.
      tags:
        - Models
      parameters:
        - name: interval
          in: query
          description: The length of an interval for which the stats will be obtained. The interval ends now.
          example: 24 hours
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UsageStatsPerUser'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /stats/usage_by_model_and_user:
    get:
      operationId: get_usage_stats_by_model_and_user
      summary: Returns usage statistics grouped by models and users.
      description: Returns usage statistics grouped by models and users.
      tags:
        - Models
      parameters:
        - name: interval
          in: query
          description: The length of an interval for which the stats will be obtained. The interval ends now.
          example: 24 hours
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UsageStatsPerModelAndUser'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /stats/performance_by_model:
    get:
      operationId: get_performance_stats_by_model
      summary: Returns performance statistics grouped by models.
      description: Returns performance statistics grouped by models.
      tags:
        - Models
      parameters:
        - name: interval
          in: query
          description: The length of an interval for which the stats will be obtained. The interval ends now.
          example: 24 hours
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PerformanceStatsPerModel'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /users:
    get:
      operationId: list_users
      summary: Returns a list of all registered users for the system.
      description: Returns a list of all registered users for the system.
      tags:
        - Permissions
      parameters:
        - name: offset
          in: query
          description: How many users to skip before returning.
          required: false
          schema:
            type: integer
            default: 0
        - name: limit
          in: query
          description: How many users to return.
          required: false
          schema:
            type: integer
            default: 100
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserInfo'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /users/{user_id}:
    get:
      operationId: get_user
      summary: Finds user for a given unique identifier.
      description: Finds user for a given unique identifier.
      tags:
        - Permissions
      parameters:
        - name: user_id
          in: path
          description: The unique identifier of an user.
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserInfo'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /users/{user_id}/permissions:
    get:
      operationId: get_user_permissions
      summary: Lists permissions of a given user.
      description: Lists permissions of a given user.
      tags:
        - Permissions
      parameters:
        - name: user_id
          in: path
          description: The unique identifier of an user.
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserPermission'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /users/current/permissions:
    get:
      operationId: get_current_user_permissions
      summary: Lists permissions of the user calling the endpoint.
      description: Lists permissions of the user calling the endpoint.
      tags:
        - Permissions
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserPermission'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /users/{user_id}/roles:
    get:
      operationId: get_user_roles
      summary: Finds roles associated with a given user.
      description: Finds roles associated with a given user.
      tags:
        - Permissions
      parameters:
        - name: user_id
          in: path
          description: The unique identifier of an user.
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RoleInfo'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'
    delete:
      operationId: reset_user_roles
      summary: Resets user roles.
      description: Replaces all roles of the given user with a new set of roles
      tags:
        - Permissions
      parameters:
        - name: user_id
          in: path
          description: The unique identifier of an user.
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RolesResetRequest'
        required: true
      responses:
        "204":
          description: Successful operation
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /users/current/roles:
    get:
      operationId: get_current_user_roles
      summary: Finds roles associated with the user calling the endpoint.
      description: Finds roles associated with the user calling the endpoint.
      tags:
        - Permissions
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RoleInfo'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /users/{user_id}/roles/{role_names}:
    put:
      operationId: assign_roles_to_user
      summary: Assigns roles to a given user.
      description: Assigns roles to a given user.
      tags:
        - Permissions
      parameters:
        - name: user_id
          in: path
          description: The unique identifier of an user.
          required: true
          schema:
            type: string
        - name: role_names
          in: path
          description: The role names.
          required: true
          schema:
            type: array
            items:
              type: string
      responses:
        "204":
          description: Successful operation
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'
    delete:
      operationId: remove_roles_from_user
      summary: Removes roles from a given user.
      description: Removes roles from a given user.
      tags:
        - Permissions
      parameters:
        - name: user_id
          in: path
          description: The unique identifier of an user.
          required: true
          schema:
            type: string
        - name: role_names
          in: path
          description: The role names.
          required: true
          schema:
            type: array
            items:
              type: string
      responses:
        "204":
          description: Successful operation
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /groups:
    get:
      operationId: list_groups
      summary: Returns a list of all groups existing on the H2OGPTe instance.
      description: Returns a list of all groups existing on the H2OGPTe instance.
      tags:
        - Permissions
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/GroupInfo'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'
    post:
      operationId: create_group
      summary: Creates a user group.
      description: Creates a user group.
      tags:
        - Permissions
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GroupCreateRequest'
        required: true
      responses:
        "201":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupInfo'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'
    delete:
      operationId: delete_groups_by_names
      summary: Deletes groups for given group names.
      description: Deletes groups for given group names.
      tags:
        - Permissions
      parameters:
        - name: names
          in: query
          description: Names of groups to be deleted.
          required: true
          schema:
            type: array
            items:
              type: string
      responses:
        "204":
          description: Successful operation
        "401":
          $ref: '#/components/responses/Unauthorized'
        "409":
          $ref: '#/components/responses/Conflict'
        default:
          $ref: '#/components/responses/Unexpected'

  /groups/{group_ids}:
    delete:
      operationId: delete_groups
      summary: Deletes groups for given unique identifiers.
      description: Deletes a groups for given unique identifiers.
      tags:
        - Permissions
      parameters:
        - name: group_ids
          in: path
          description: The unique identifiers of groups to be deleted.
          required: true
          schema:
            type: array
            items:
              type: string
      responses:
        "204":
          description: Successful operation
        "401":
          $ref: '#/components/responses/Unauthorized'
        "409":
          $ref: '#/components/responses/Conflict'
        default:
          $ref: '#/components/responses/Unexpected'

  /groups/{group_id}/roles:
    get:
      operationId: get_group_roles
      summary: Finds roles associated with a given group.
      description: Finds roles associated with a given group.
      tags:
        - Permissions
      parameters:
        - name: group_id
          in: path
          description: The unique identifier of a group.
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RoleInfo'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'
    delete:
      operationId: reset_group_roles
      summary: Resets group roles.
      description: Replaces all roles of the given group with a new set of roles
      tags:
        - Permissions
      parameters:
        - name: group_id
          in: path
          description: The unique identifier of a group.
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RolesResetRequest'
        required: true
      responses:
        "204":
          description: Successful operation
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /groups/{group_id}/roles/{role_names}:
    put:
      operationId: assign_roles_to_group
      summary: Assigns roles to a given group.
      description: Assigns roles to a given user.
      tags:
        - Permissions
      parameters:
        - name: group_id
          in: path
          description: The unique identifier of a group.
          required: true
          schema:
            type: string
        - name: role_names
          in: path
          description: The role names.
          required: true
          schema:
            type: array
            items:
              type: string
      responses:
        "204":
          description: Successful operation
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'
    delete:
      operationId: remove_roles_from_group
      summary: Removes roles from a given group.
      description: Removes roles from a given group.
      tags:
        - Permissions
      parameters:
        - name: group_id
          in: path
          description: The unique identifier of a group.
          required: true
          schema:
            type: string
        - name: role_names
          in: path
          description: The role names.
          required: true
          schema:
            type: array
            items:
              type: string
      responses:
        "204":
          description: Successful operation
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /group/{group_id}/permissions:
    get:
      operationId: get_group_permissions
      summary: Lists permissions of a given group.
      description: Lists permissions of a given group.
      tags:
        - Permissions
      parameters:
        - name: group_id
          in: path
          description: The unique identifier of a group.
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserPermission'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /roles:
    post:
      operationId: create_role
      summary: Creates a role.
      description: Creates a role.
      tags:
        - Permissions
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RoleCreateRequest'
        required: true
      responses:
        "201":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoleInfo'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'
    get:
      operationId: list_roles
      summary: Returns all roles for in the H2OGPTe instance.
      description: Returns all roles for in the H2OGPTe instance.
      tags:
        - Permissions
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RoleInfo'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'
    delete:
      operationId: delete_roles_by_names
      summary: Deletes roles for given role names.
      description: Deletes roles for given role names.
      tags:
        - Permissions
      parameters:
        - name: names
          in: query
          description: Names of roles to be deleted.
          required: true
          schema:
            type: array
            items:
              type: string
      responses:
        "204":
          description: Successful operation
        "401":
          $ref: '#/components/responses/Unauthorized'
        "409":
          $ref: '#/components/responses/Conflict'
        default:
          $ref: '#/components/responses/Unexpected'

  /roles/{role_id}:
    get:
      operationId: get_role
      summary: Finds role for a given unique identifier.
      description: Finds role for a given unique identifier.
      tags:
        - Permissions
      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:
                $ref: '#/components/schemas/RoleInfo'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /roles/{role_ids}:
    delete:
      operationId: delete_roles
      summary: Deletes roles for given unique identifiers.
      description: Deletes roles for given unique identifiers.
      tags:
        - Permissions
      parameters:
        - name: role_ids
          in: path
          description: The unique identifiers of roles to be deleted.
          required: true
          schema:
            type: array
            items:
              type: string
      responses:
        "204":
          description: Successful operation
        "401":
          $ref: '#/components/responses/Unauthorized'
        "409":
          $ref: '#/components/responses/Conflict'
        default:
          $ref: '#/components/responses/Unexpected'

  /roles/{role_id}/permissions:
    get:
      operationId: get_role_permissions
      summary: Lists permissions of a given role.
      description: Lists permissions of a given role.
      tags:
        - Permissions
      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/UserPermission'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'
    post:
      operationId: set_role_permissions
      summary: Sets a new set of permissions for a given role.
      description: Sets a new set of permissions for a given role.
      tags:
        - Permissions
      parameters:
        - name: role_id
          in: path
          description: The unique identifier of an role.
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PermissionResetRequest'
        required: true
      responses:
        "204":
          description: Successful operation
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /roles/{role_id}/permissions/{permission_name}:
    put:
      operationId: assign_permission_to_role
      summary: Assigns permission to a given role.
      description: Assigns permission to a given role.
      tags:
        - Permissions
      parameters:
        - name: role_id
          in: path
          description: The unique identifier of an user.
          required: true
          schema:
            type: string
        - name: permission_name
          in: path
          description: The permission name.
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Successful operation
        "401":
          $ref: '#/components/responses/Unauthorized'
        "409":
          $ref: '#/components/responses/Conflict'
        default:
          $ref: '#/components/responses/Unexpected'
    delete:
      operationId: remove_permission_from_role
      summary: Removes permission from a given role.
      description: Removes permission from a given role.
      tags:
        - Permissions
      parameters:
        - name: role_id
          in: path
          description: The unique identifier of an user.
          required: true
          schema:
            type: string
        - name: permission_name
          in: path
          description: The permission name.
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Successful operation
        "401":
          $ref: '#/components/responses/Unauthorized'
        "409":
          $ref: '#/components/responses/Conflict'
        default:
          $ref: '#/components/responses/Unexpected'

  /permissions:
    get:
      operationId: list_permissions
      summary: Returns system permissions.
      description:  Returns all system permissions or permissions for given groups
      tags:
        - Permissions
      parameters:
        - name: group_names
          in: query
          description: If set, the output permissions will be related only to given groups.
          required: false
          schema:
            type: array
            items:
              type: string
        - name: role_names
          in: query
          description: If set, the output permissions will be related only to given roles.
          required: false
          schema:
            type: array
            items:
              type: string
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserPermission'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /permissions/is_granted:
    post:
      operationId: is_permission_granted
      summary: Checks if permission is granted for a given user.
      description: Checks if permission is granted for a given user.
      tags:
        - Permissions
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PermissionCheckRequest'
        required: true
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: boolean
        "401":
          $ref: '#/components/responses/Unauthorized'
        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'
        "401":
          $ref: '#/components/responses/Unauthorized'
        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'
        "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'
        "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'
        "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'
        "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'
        "401":
          $ref: '#/components/responses/Unauthorized'
        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'
        "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'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'


  /admin/api_keys:
    post:
      operationId: create_api_key_for_user
      summary: Create an API key
      description: Allows admins to create an API key for another user.
      tags:
        - API Keys
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/APIKeyCreateRequest'
        required: true
      responses:
        "201":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIKeyResult'
        "401":
          $ref: '#/components/responses/Unauthorized'
        "500":
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/Unexpected'
    get:
      operationId: list_all_api_keys
      summary: List API keys.
      description: Allows admins to list all existing API keys.
      tags:
        - API Keys
      parameters:
        - name: offset
          in: query
          description: How many API keys to skip before returning.
          required: false
          schema:
            type: integer
            default: 0
        - name: limit
          in: query
          description: How many API keys to return.
          required: false
          schema:
            type: integer
            default: 100
        - name: filter
          in: query
          description: Only returns keys for usernames matching this filter.
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/APIKeyInfo'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'
  /admin/api_keys/deactivate/{key_id}:
    post:
      operationId: deactivate_api_key
      summary: Deactivate an API key
      description: Allows admins to deactivate an API key.
      tags:
        - API Keys
      parameters:
        - name: key_id
          in: path
          description: Id of the key to deactivate.
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Successful operation
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'
  /admin/api_keys/expire/{key_id}:
    patch:
      operationId: update_api_key_expiry
      summary: Update API key expiry.
      description: Allows admins to update the expiration of an API key (either set a new expiry or remove one).
      tags:
        - API Keys
      parameters:
        - name: key_id
          in: path
          description: Id of the key to update.
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/APIKeyUpdateExpiryRequest'
      responses:
        "204":
          description: Successful operation
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'
  /admin/api_keys/{key_id}:
    delete:
      operationId: delete_api_key
      summary: Delete an API key.
      description: Allows admins to delete an API key.
      tags:
        - API Keys
      parameters:
        - name: key_id
          in: path
          description: Id of the key to delete.
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Successful operation
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /agents/directory_stats:
    get:
      operationId: list_agent_directory_stats
      summary: Lists agent directory stats across all agent chat sessions.
      description: Lists agent directory stats across all agent chat sessions.
      tags:
        - Agents
      parameters:
        - name: offset
          in: query
          description: How many agent chat sessions to skip before returning.
          required: false
          schema:
            type: integer
            default: 0
        - name: limit
          in: query
          description: How many agent chat sessions to return.
          required: false
          schema:
            type: integer
            default: 100
        - name: filter_text
          in: query
          description: Applied text filter.
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AgentServerDirectoryStatsPerAgentChatSession'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

  /agents/tools:
    get:
      operationId: list_agent_tools
      summary: Lists agent tools present on the system.
      description: Lists agent tools present on the system.
      tags:
        - Agents
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AgentToolSpec'
        "401":
          $ref: '#/components/responses/Unauthorized'
        "500":
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/Unexpected'

  /agents/tool_preference:
    get:
      operationId: list_agent_tool_preference
      summary: Lists the agent tool preference for the user.
      description: Lists the agent tool preference for the user.
      tags:
        - Agents
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                nullable: true
        "401":
          $ref: '#/components/responses/Unauthorized'
        "500":
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/Unexpected'
    post:
      operationId: update_agent_tool_preference
      summary: Creates or updates the agent tool preference for the user.
      description: Creates or updates the agent tool preference for the user.
      tags:
        - Agents
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - reference_value
              properties:
                reference_value:
                  type: array
                  items:
                    type: string
      responses:
        "204":
          description: Successful operation
        "401":
          $ref: '#/components/responses/Unauthorized'
        "500":
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/Unexpected'
    delete:
      operationId: delete_agent_tool_preference
      summary: Deletes the agent tool preferences for the user.
      description: Deletes the agent tool preferences for the user.
      tags:
        - Agents
      responses:
        "204":
          description: Successful operation
        "401":
          $ref: '#/components/responses/Unauthorized'
        "500":
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/Unexpected'

  /agents/keys:
    get:
      operationId: list_agent_keys
      summary: Lists agent keys.
      description: Lists agent keys.
      tags:
        - Agents
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AgentKey'
        "401":
          $ref: '#/components/responses/Unauthorized'
        "500":
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/Unexpected'
    post:
      operationId: create_agent_key
      summary: Creates agent key.
      description: Creates agent key.
      tags:
        - Agents
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAgentKeyRequest'
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentKey'
        "401":
          $ref: '#/components/responses/Unauthorized'
        "409":
          $ref: '#/components/responses/Conflict'
        "500":
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/Unexpected'

  /agents/keys/{key_id}:
    post:
      operationId: update_agent_key
      summary: Updates agent key.
      description: Updates agent key.
      tags:
        - Agents
      parameters:
        - name: key_id
          in: path
          description: Id of the key to be updated.
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAgentKeyRequest'
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentKey'
        "401":
          $ref: '#/components/responses/Unauthorized'
        "409":
          $ref: '#/components/responses/Conflict'
        "500":
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/Unexpected'

  /agents/keys/{key_ids}:
    delete:
      operationId: delete_agent_keys
      summary: Deletes agent keys.
      description: Deletes agent keys.
      tags:
        - Agents
      parameters:
        - name: key_ids
          in: path
          description: Ids of keys to be deleted.
          required: true
          schema:
            type: array
            items:
              type: string
      responses:
        "204":
          description: Successful operation
        "401":
          $ref: '#/components/responses/Unauthorized'
        "500":
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/Unexpected'

  /agents/tool_association:
    get:
      operationId: list_agent_key_tool_associations
      summary: Returns a list of tools and the user's associated keys.
      description: Returns a list of tools and the user's associated keys.
      tags:
        - Agents
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AgentToolKeyAssociations'
        "401":
          $ref: '#/components/responses/Unauthorized'
        "500":
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/Unexpected'
    post:
      operationId: create_agent_key_tool_associations
      summary: Creates associations between a tool and user's keys.
      description: Creates associations between a tool and user's keys.
      tags:
        - Agents
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAgentToolKeyAssociationsRequest'
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentToolKeyAssociations'
        "401":
          $ref: '#/components/responses/Unauthorized'
        "500":
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/Unexpected'

  /agents/tool_association/{associate_ids}:
    delete:
      operationId: delete_agent_tool_association
      summary: Deletes agent tool key associations.
      description: Deletes agent tool key associations given a list of associate ids belonging to the user.
      tags:
        - Agents
      parameters:
        - name: associate_ids
          in: path
          description: The unique identifiers of tool associations to be deleted.
          required: true
          schema:
            type: array
            items:
              type: string
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Count'
        "401":
          $ref: '#/components/responses/Unauthorized'
        "500":
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/Unexpected'

  /system/h2ogpt_info:
    get:
      operationId: get_h2ogpt_system_info
      summary: Gets H2OGPT system information.
      description: Gets H2OGPT system information.
      tags:
        - System
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/H2OGPTSystemInfo'
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'

components:
  parameters:
    IngestionParameterUploadIds:
      name: upload_ids
      in: path
      description: Id of uploaded document
      required: true
      schema:
        type: array
        items:
          type: string
    IngestionParameterCollectionId:
      name: collection_id
      in: query
      description: String id of the collection to add the ingested documents into.
      required: true
      schema:
        type: string
    IngestionParameterDocumentId:
      name: document_id
      in: query
      description: String id of the document to be parsed.
      required: true
      schema:
        type: string
    IngestionParameterFileName:
      name: file_name
      in: query
      description: String of the file name to use for the document.
      required: true
      schema:
        type: string
    IngestionParameterGenDocSummaries:
      name: gen_doc_summaries
      in: query
      description: Whether to auto-generate document summaries (uses LLM).
      schema:
        type: boolean
        default: false
    IngestionParameterGenDocQuestions:
      name: gen_doc_questions
      in: query
      description: Whether to auto-generate sample questions for each document (uses LLM).
      schema:
        type: boolean
        default: false
    IngestionParameterFollowLinks:
      name: follow_links
      in: query
      description: Whether to import all web pages linked from this URL will be imported.
        External links will be ignored. Links to other pages on the same domain will
        be followed as long as they are at the same level or below the URL you specify.
        Each page will be transformed into a PDF document.
      schema:
        type: boolean
        default: false
    IngestionParameterMaxDepth:
      name: max_depth
      in: query
      description: Max depth of recursion when following links, only when follow_links is `true`.
        Max_depth of 0 means don't follow any links, max_depth of 1 means follow only top-level links, etc.
        Use -1 for automatic (system settings).
      schema:
        type: integer
        default: -1
    IngestionParameterMaxDocuments:
      name: max_documents
      in: query
      description: Max number of documents when following links, only when follow_links is `true`.
        Use None for automatic (system defaults).
        Use -1 for max (system limit).
      schema:
        type: integer
    IngestionParameterAudioInputLanguage:
      name: audio_input_language
      in: query
      description: Language of audio files.
      schema:
        type: string
        default: auto
    IngestionParameterOcrModel:
      name: ocr_model
      in: query
      description: Which method to use to extract text from images using AI-enabled optical character
        recognition (OCR) models. docTR is best for Latin text,
        PaddleOCR is best for certain non-Latin languages, Tesseract covers a wide range of languages.
        Mississippi works well on handwriting.
        - `auto` - Automatic will auto-select the best OCR model for every page.
        - `off` - Disable OCR for speed, but all images will then be skipped (also no image captions will be made).
      schema:
        type: string
        default: auto
    IngestionParameterTesseractLang:
      name: tesseract_lang
      in: query
      description: Which language to use when using ocr_model="tesseract".
      schema:
        type: string
    IngestionParameterKeepTablesAsOneChunk:
      name: keep_tables_as_one_chunk
      in: query
      description: When tables are identified by the table parser the table tokens will be kept in a single chunk.
      schema:
        type: boolean
    IngestionParameterChunkByPage:
      name: chunk_by_page
      in: query
      description: Each page will be a chunk. `keep_tables_as_one_chunk` will be ignored if this is `true`.
      schema:
        type: boolean
    IngestionParameterHandwritingCheck:
      name: handwriting_check
      in: query
      description: Check pages for handwriting. Will use specialized models if handwriting is found.
      schema:
        type: boolean
    IngestionParameterIngestMode:
      name: ingest_mode
      in: query
      description: Ingest mode to use.
        - `standard` - Files will be ingested for use with RAG
        - `agent_only` - Bypasses standard ingestion. Files can only be used with agents.
      schema:
        type: string
        enum: [standard, agent_only]
    IngestionParameterRestricted:
      name: restricted
      in: query
      description: Whether the document should be restricted only to certain users.
      schema:
        type: boolean
        default: False
    IngestionParameterPermissions:
      name: permissions
      in: query
      description: The list of usernames having permissions to the document.
      schema:
        type: array
        items:
          type: string
    Timeout:
      name: timeout
      in: query
      description: Timeout in seconds
      schema:
        type: number
        format: double
    IngestionParameterMetadata:
      name: metadata
      in: query
      description: String with json-encoded metadata for the document.
      schema:
        type: string
    CopyDocument:
      name: copy_document
      in: query
      description: Whether to save a new copy of the document
      schema:
        type: boolean
    SessionId:
      name: Session-Id
      in: header
      description: Optional session identifier for request tracing and correlation
      required: false
      schema:
        type: string
  responses:
    UnsupportedMediaType:
      description: Unsupported media type
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EndpointError'
    RequestEntityTooLarge:
      description: Request entity is too large
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EndpointError'
    Unauthorized:
      description: Unauthorized - Invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EndpointError'
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EndpointError'
    Conflict:
      description: Conflict
      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'
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EndpointError'


  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Using an API key generated by H2OGPTe

  schemas:
    APIKeyResult:
      required:
        - secret_key
        - api_key
      type: object
      properties:
        secret_key:
          description: The secret key associated with the newly generated API Key.
          type: string
        api_key:
          $ref: '#/components/schemas/APIKeyInfo'
    APIKeyInfo:
      required:
        - id
        - username
        - name
        - hint
        - created_at
        - is_global_key
        - is_active
      type: object
      properties:
        id:
          description: The unique identifier of the API key
          type: string
        username:
          description: The username of the user this key belongs to
          type: string
        name:
          description: The name of the API key
          type: string
        hint:
          description: Hint for the secret key of the API key
          type: string
        created_at:
          description: The date and time of when the API key was created
          type: string
          format: date-time
        expires_at:
          description: The date and time of the API key expiration
          type: string
          format: date-time
        is_active:
          description: Status denoting if the API key is active or not
          type: boolean
        collection_name:
          description: The name of the collection associated with the API key (if it has been configured to a collection)
          type: string
        collection_id:
          description: The id of the collection associated with the API key (if it has been configured to a collection)
          type: string
        is_global_key:
          description: Status denoting if the API key is global or collection specific
          type: boolean
    APIKeyCreateRequest:
      type: object
      required:
        - user_id
      properties:
        user_id:
          description: Id of the user the key will be created for
          type: string
        name:
          description: The name for the API key
          type: string
        collection_id:
          description: The id of the collection you want the key to be configured to
          type: string
        expires_in:
          description: Interval of when the API key should expire
          type: string
          example: "30 days"
    APIKeyUpdateExpiryRequest:
      type: object
      properties:
        expires_in:
          description: Interval of when the API key should expire. Do not include if you would like to remove the expiry of a key.
          type: string
          example: "30 days"
    Count:
      required:
        - count
      type: object
      properties:
        count:
          type: integer
    CountWithQueueDetails:
      allOf:
        - $ref: '#/components/schemas/Count'
        - type: object
          required:
            - queue_infos
          properties:
            queue_infos:
              type: array
              items:
                $ref: '#/components/schemas/QueueDetails'
    QueueDetails:
      required:
        - name
        - length
      properties:
        name:
          type: string
        length:
          type: integer
    CollectionChangeRequest:
      required:
        - collection_id
      type: object
      properties:
        collection_id:
          type: string
    PromptTemplateChangeRequest:
      type: object
      properties:
        prompt_template_id:
          type: string
    GuardrailsSettingsCreateRequest:
      type: object
      properties:
        action:
          description: |
            What to do when detecting PII, either "redact" or "fail" ("allow" would keep PII intact).
            Guardrails models always fail upon detecting safety violations.
          type: string
          enum: [redact, fail, allow]
          default: redact
        sensitive:
          description: Whether to include the most sensitive PII entities like SSN, bank account info.
          type: boolean
          default: true
        non_sensitive:
          description: Whether to include all non-sensitive PII entities, such as IP addresses, locations, names, e-mail addresses etc.
          type: boolean
          default: true
        all_guardrails:
          description: Whether to include all possible entities for prompt guard and guardrails models, or just system defaults.
          type: boolean
          default: true
        guardrails_settings:
          description: |
            Existing guardrails settings (e.g., from collection settings) to obtain guardrails entities,
            guardrails_entities_to_flag, column redaction custom_pii_entities, column_redaction_pii_to_flag
            from instead of system defaults
          allOf:
            - $ref: '#/components/schemas/GuardrailsSettings'
    CollectionCreateRequest:
      required:
        - name
        - description
      type: object
      properties:
        name:
          type: string
          example: My sci-fi library
        description:
          type: string
          example: Collection of my favourite sci-fi books
        embedding_model:
          type: string
          example: BAAI/bge-large-en-v1.5
        collection_settings:
          $ref: '#/components/schemas/CollectionSettings'
        chat_settings:
          $ref: '#/components/schemas/ChatSettings'
    CollectionUpdateRequest:
      type: object
      properties:
        name:
          description: Name of the collection
          type: string
        description:
          description: Description of the collection
          type: string
        rag_type:
          description: >
            RAG type options:
              * `auto` - Automatically select the best rag_type.
              * `llm_only` LLM Only - Answer the query without any supporting document contexts.
              Requires 1 LLM call.
              * `rag` RAG (Retrieval Augmented Generation) - Use supporting document contexts
              to answer the query. Requires 1 LLM call.
              * `hyde1` LLM Only + RAG composite - HyDE RAG (Hypothetical Document Embedding).
              Use 'LLM Only' response to find relevant contexts from a collection for generating
              a response. Requires 2 LLM calls.
              * `hyde2` HyDE + RAG composite - Use the 'HyDE RAG' response to find relevant
              contexts from a collection for generating a response. Requires 3 LLM calls.
              * `rag+` Summary RAG - Like RAG, but uses more context and recursive
              summarization to overcome LLM context limits. Keeps all retrieved chunks, puts
              them in order, adds neighboring chunks, then uses the summary API to get the
              answer. Can require several LLM calls.
              * `all_data` All Data RAG - Like Summary RAG, but includes all document
              chunks. Uses recursive summarization to overcome LLM context limits.
              Can require several LLM calls.
          type: string
          enum: [ auto, llm_only, rag, hyde1, hyde2, rag+, all_data ]
    DeleteCollectionsJobRequest:
      type: object
      required:
        - collection_ids
      properties:
        collection_ids:
          description: Ids of collections to be deleted.
          type: array
          items:
            type: string
    Collection:
      required:
        - id
        - name
        - description
        - embedding_model
        - document_count
        - document_size
        - created_at
        - updated_at
        - user_count
        - is_public
        - username
        - sessions_count
        - status
      type: object
      properties:
        id:
          description: A unique identifier of the collection
          type: string
          example: 123e4567-e89b-12d3-a456-426655440000
        name:
          description: Name of the collection
          type: string
          example: My sci-fi library
        description:
          description: Description of the collection
          type: string
          example: Collection of my favourite sci-fi books
        embedding_model:
          type: string
          example: BAAI/bge-large-en-v1.5
        document_count:
          description: A number of documents in the collection
          type: integer
        document_size:
          description: Total size in bytes of all documents in the collection
          type: integer
        created_at:
          description: Time when the collection was created
          type: string
          format: date-time
        updated_at:
          description: Last time when the collection was modified
          type: string
          format: date-time
        user_count:
          description: A number of users having access to the collection
          type: integer
        is_public:
          description: Is publicly accessible
          type: boolean
        username:
          description: Name of the user owning the collection
          type: string
        sessions_count:
          description: A number of chat sessions with the collection
          type: integer
        status:
          description: Status of the collection
          type: string
        prompt_template_id:
          description: A unique identifier of a prompt template associated with the collection.
          type: string
          example: 4e400991-c459-455f-995c-dc6f55ffdb90
        thumbnail:
          description: A file name of a thumbnail image.
          type: string
        size_limit:
          description: Maximum size of data that could be contained in the collection.
          type: integer
        expiry_date:
          description: An expiry date
          type: string
          format: date-time
        inactivity_interval:
          description: The inactivity interval as an integer number of days.
          type: integer
        rag_type:
          description: >
            RAG type options:
              * `auto` - Automatically select the best rag_type.
              * `llm_only` LLM Only - Answer the query without any supporting document contexts.
              Requires 1 LLM call.
              * `rag` RAG (Retrieval Augmented Generation) - Use supporting document contexts
              to answer the query. Requires 1 LLM call.
              * `hyde1` LLM Only + RAG composite - HyDE RAG (Hypothetical Document Embedding).
              Use 'LLM Only' response to find relevant contexts from a collection for generating
              a response. Requires 2 LLM calls.
              * `hyde2` HyDE + RAG composite - Use the 'HyDE RAG' response to find relevant
              contexts from a collection for generating a response. Requires 3 LLM calls.
              * `rag+` Summary RAG - Like RAG, but uses more context and recursive
              summarization to overcome LLM context limits. Keeps all retrieved chunks, puts
              them in order, adds neighboring chunks, then uses the summary API to get the
              answer. Can require several LLM calls.
              * `all_data` All Data RAG - Like Summary RAG, but includes all document
              chunks. Uses recursive summarization to overcome LLM context limits.
              Can require several LLM calls.
          type: string
          enum: [auto, llm_only, rag, hyde1, hyde2, rag+, all_data]
        metadata_dict:
          $ref: '#/components/schemas/Metadata'

    CollectionSettings:
      type: object
      properties:
        max_tokens_per_chunk:
          description: Approximate max. number of tokens per chunk for text-dominated document pages.
                       For images, chunks can be larger.
          type: integer
          example: 320
        chunk_overlap_tokens:
          description: Approximate number of tokens that are overlapping between successive chunks.
          type: integer
          example: 0
        gen_doc_summaries:
          description: Whether to auto-generate document summaries (uses LLM)
          type: boolean
          default: false
        gen_doc_questions:
          description: Whether to auto-generate sample questions for each document (uses LLM)
          type: boolean
          default: false
        audio_input_language:
          description: Language of audio files. Defaults to "auto" language detection. Pass empty string to see choices.
          type: string
          default: auto
        ocr_model:
          description: Which method to use to extract text from images using AI-enabled optical character recognition (OCR) models.
                       Pass empty string to see choices.
                       docTR is best for Latin text, PaddleOCR is best for certain non-Latin languages, Tesseract covers a wide range of languages.
                       Mississippi works well on handwriting.
                       auto - Automatic will auto-select the best OCR model for every page.
                       off - Disable OCR for speed, but all images will then be skipped (also no image captions will be made).
          type: string
          default: auto
        tesseract_lang:
          description: Which language to use when using ocr_model="tesseract". Pass empty string to see choices.
          type: string
        keep_tables_as_one_chunk:
          description: When tables are identified by the table parser the table tokens will be kept in a single chunk.
          type: boolean
        chunk_by_page:
          description: Each page will be a chunk. `keep_tables_as_one_chunk` will be ignored if this is `true`.
          type: boolean
        handwriting_check:
          description: Check pages for handwriting. Will use specialized models if handwriting is found.
          type: boolean
        follow_links:
          description: Whether to import all web pages linked from this URL will be imported. External links will be ignored. Links to other pages on the same domain will be followed as long as they are at the same level or below the URL you specify. Each page will be transformed into a PDF document.
          type: boolean
        max_depth:
          description: Max depth of recursion when following links, only when follow_links is `true`. Max_depth of 0 means don't follow any links, max_depth of 1 means follow only top-level links, etc. Use -1 for automatic (system settings).
          type: integer
        max_documents:
          description: Max number of documents when following links, only when follow_links is `true`. Use None for automatic (system defaults). Use -1 for max (system limit).
          type: integer
        root_dir:
          description: Root directory for document storage
          type: string
        copy_document:
          description: Whether to copy the document when importing an existing document
          type: boolean
        guardrails_settings:
          $ref: '#/components/schemas/GuardrailsSettings'
    Chunk:
      type: object
      required:
        - id
        - text
        - name
        - size
        - pages
      properties:
        text:
          description: The text represented by the chunk
          type: string
        id:
          description: The identifier of the chunk
          type: integer
        name:
          type: string
        size:
          description: The size in bytes.
          type: integer
        pages:
          type: string
    ChunkSearchResult:
      allOf:
        - $ref: '#/components/schemas/Chunk'
        - type: object
          required:
            - topic
            - score
          properties:
            topic:
              type: string
            score:
              type: number
              format: double
    Metadata:
      type: object
      additionalProperties: true
    Dictionary:
      type: object
      additionalProperties: true
    ChatSettings:
      type: object
      properties:
        llm:
          type: string
          description: LLM name to send the query. Use "auto" for automatic model routing,
            set cost_controls of llm_args for detailed control over automatic routing.
        llm_args:
          $ref: '#/components/schemas/ChatCompletionRequestLLMArgs'
        self_reflection_config:
          $ref: '#/components/schemas/ChatCompletionSelfReflectionConfig'
        rag_config:
          $ref: '#/components/schemas/ChatCompletionRAGConfig'
        include_chat_history:
          type: string
          enum: [ on, off, auto ]
          description: Whether to include chat history. Includes previous questions and answers for
            the current chat session for each new chat request. Disable if require deterministic
            answers for a given question.
        tags:
          type: array
          items:
            type: string
          description: A list of tags from which to pull the context for RAG.
    GuardrailsSettings:
      type: object
      properties:
        exception_message:
          description: A message that will be returned in case some guardrails settings are violated.
          type: string
        column_redaction_config:
          type: array
          description: List of [column_pattern, redaction_label], both strings.
          items:
            type: array
            minItems: 2
            maxItems: 2
            items:
              type: string
        disallowed_regex_patterns:
          description: A list of regular expressions that match custom PII.
          type: array
          items:
            type: string
          example: ["secret_disallowed_word", '(?!0{3})(?!6{3})[0-8]\d{2}-(?!0{2})\d{2}-(?!0{4})\d{4}']
        presidio_labels_to_flag:
          description: A list of entities to be flagged as PII by the built-in Presidio model.
          type: array
          items:
            type: string
          example: ["IBAN_CODE", "US_SSN"]
        pii_labels_to_flag:
          description: A list of entities to be flagged as PII by the built-in PII model.
          type: array
          items:
            type: string
          example: ["IBAN", "SSN"]
        pii_detection_parse_action:
          description: What to do when PII is detected during parsing of documents. The 'redact' option
                       will replace disallowed content in the ingested documents with redaction bars.
          type: string
          enum: [allow, redact, fail]
        pii_detection_llm_input_action:
          description: What to do when PII is detected in the input to the LLM (document content and user prompts).
                       The 'redact' option will replace disallowed content with placeholders.
          type: string
          enum: [allow, redact, fail]
        pii_detection_llm_output_action:
          description: What to do when PII is detected in the output of the LLM.
                       The 'redact' option will replace disallowed content with placeholders.
          type: string
          enum: [ allow, redact, fail ]
        prompt_guard_labels_to_flag:
          description: A list of entities to be flagged as safety violations in user prompts by 
                       the built-in prompt guard model.
          type: array
          items:
            type: string
          example: ["JAILBREAK"]
        guardrails_labels_to_flag:
          description: A list of entities to be flagged as safety violations in user prompts.
                       Must be a subset of guardrails_entities, if provided.
          type: array
          items:
            type: string
          example: ["Violent Crimes", "Non-Violent Crimes", "Intellectual Property", "Code Interpreter Abuse"]
        guardrails_llm:
          description: LLM to use for Guardrails and PII detection
          type: string
          example: "h2oai/h2o-danube3-4b-chat"
        guardrails_safe_category:
          description: Name of the safe category for guardrails. Must be a key in guardrails_entities, if provided. Otherwise uses system defaults.
          type: string
          example: "Safe"
        guardrails_entities:
          description: Dictionary of entities and their descriptions for the guardrails model to classify. The first entry is the "safe" class, the rest are "unsafe" classes.
          type: object
          additionalProperties:
            type: string
          example: {
            "Safe": "Messages that do not contain any of the following unsafe content",  # must be first, not used as potential label to flag
            "Violent Crimes": "Messages that enable, encourage, or endorse the commission of violent crimes, including: (1) unlawful violence toward people (ex: terrorism, genocide, murder, hate-motivated violent crimes, child abuse, assault, battery, kidnapping) and (2) unlawful violence toward animals (ex: animal abuse)",
            "Non-Violent Crimes": "Messages that enable, encourage, or endorse the commission of non-violent crimes, including: (1) personal crimes (ex: labor trafficking, threats, intimidation, hate-motivated non-violent crimes), (2) financial crimes (ex: fraud, scams, money laundering), (3) property crimes (ex: theft, arson, vandalism), (4) drug crimes (ex: creating or using regulated substances), (5) weapons crimes (ex: producing unlicensed firearms), and (6) cyber crimes (ex: hacking)",
            "Defamation": "Messages that are both verifiably false and likely to injure a living person’s reputation",
            "Specialized Advice": "Messages that contain specialized financial, medical, or legal advice, or that indicate dangerous activities or objects are safe",
            "Intellectual Property": "Messages that may violate the intellectual property rights of any third party",
            "Code Interpreter Abuse": "Messages that seek to abuse code interpreters, including those that enable denial of service attacks, container escapes or privilege escalation exploits",
          }
        column_redaction_custom_entities_to_flag:
          description: A list of entities to redact in tabular data files. Must be a subset of column_redaction_custom_entities, if provided.
          type: array
          items:
            type: "string"
          example: ["Mother's Maiden Name"]
        column_redaction_custom_entities:
          description: (Optional) A dictionary of entities and a short description for the LLM to check for and redact columns containing PII in tabular data files.
          type: object
          additionalProperties:
            type: string
          example: {
                    "Mother's Maiden Name": "Mother's maiden name",
                }
    DocumentUpdateRequest:
      type: object
      properties:
        name:
          type: string
        uri:
          type: string
    ProcessDocumentJobRequest:
      type: object
      required:
        - document_id
      properties:
        document_id:
          description: String id of the document to create a summary from.
          type: string
        summary_id:
          description: The requested identifier of the output document summary.
          type: string
        system_prompt:
          description: System prompt.
          type: string
        pre_prompt_summary:
          description: Prompt that goes before each large piece of text to summarize.
          type: string
        prompt_summary:
          description: Prompt that goes after each large piece of text to summarize.
          type: string
        image_batch_image_prompt:
          description: Prompt for each image batch for vision models.
          type: string
        image_batch_final_prompt:
          description: Prompt to reduce all answers each image batch for vision models.
          type: string
        llm:
          description: LLM to use.
          type: string
        llm_args:
          $ref: '#/components/schemas/ChatCompletionRequestLLMArgs'
        max_num_chunks:
          description: Max limit of chunks to send to the summarizer.
          type: integer
        sampling_strategy:
          description: How to sample if the document has more chunks than max_num_chunks.
                       Options are "auto", "uniform", "first", "first+last", default is "auto" (a hybrid of them all).
          type: string
          enum: [auto, uniform, first, first+last]
          default: auto
        pages:
          description: List of specific pages (of the ingested document in PDF form) to use from the document. 
                       1-based indexing.
          type: array
          items:
            type: integer
        schema:
          description: Optional JSON schema to use for guided json generation.
          type: object
        keep_intermediate_results:
          description: Whether to keep intermediate results. If false, further LLM calls are applied to 
                       the intermediate results until one global summary is obtained - map+reduce (i.e., summary).
                       If true, the results' content will be a list of strings (the results of applying 
                       the LLM to different pieces of document context) - map (i.e., extract).
          type: boolean
          default: false
        guardrails_settings:
          $ref: '#/components/schemas/GuardrailsSettings'
        timeout:
          description: Amount of time in seconds to allow the request to run. The default is 86400 seconds.
          type: integer
          default: 86400
        meta_data_to_include:
          description: |
            A map with flags that indicate whether each piece of document metadata is to be included as part of 
            the context for a chat with a collection.
              * `name` **(type: boolean, default=True)**
              * `text` **(type: boolean, default=True)**
              * `page` **(type: boolean, default=True)**
              * `captions` **(type: boolean, default=True)**
              * `uri` **(type: boolean, default=False)**
              * `connector` **(type: boolean, default=False)**
              * `original_mtime` **(type: boolean, default=False)**
              * `age` **(type: boolean, default=False)**
              * `score` **(type: boolean, default=False)**
          type: object
          additionalProperties:
            type: boolean

    DeleteDocumentsJobRequest:
      type: object
      required:
        - document_ids
      properties:
        document_ids:
          description: Ids of documents to be deleted.
          type: array
          items:
            type: string
    Document:
      required:
        - id
        - name
        - username
        - type
        - size
        - page_count
        - created_at
        - updated_at
        - status
      type: object
      properties:
        id:
          description: A unique identifier of the document
          type: string
          example: 123e4567-e89b-12d3-a456-426655440000
        name:
          description: Name of the document
          type: string
          example: The Hitchhiker's Guide to the Galaxy
        username:
          description: A username owning the document
          type: string
        type:
          description: Type of the document
          type: string
        size:
          description: Size of the document in bytes
          type: integer
        page_count:
          description: A number of pages contained in the document
          type: integer
        status:
          description: Status of the document
          type: string
          enum:
            - unknown
            - scheduled
            - queued
            - running
            - completed
            - failed
            - canceled
            - agent_only
        usage_stats:
          description: Usage stats
          type: string
        connector:
          type: string
        original_type:
          type: string
        original_mtime:
          type: string
          format: datetime
        created_at:
          description: Time when document was created
          type: string
          format: date-time
        updated_at:
          description: Last time when document was modified
          type: string
          format: date-time
        uri:
          type: string
        summary:
          type: string
        summary_parameters:
          type: string
        metadata_dict:
          $ref: '#/components/schemas/Metadata'
    DocumentSummary:
      type: object
      required:
        - id
        - document_id
        - content
        - error
        - kwargs
        - created_at
      properties:
        id:
          description: A unique identifier of the document summary
          type: string
        document_id:
          description: A unique identifier of the document
          type: string
        content:
          type: string
        error:
          type: string
        kwargs:
          type: string
        created_at:
          type: string
          format: datetime
        usage_stats:
          type: string
    TagCreateRequest:
      required:
        - name
      type: object
      properties:
        name:
          type: string
          example: marvel
    TagUpdateRequest:
      type: object
      properties:
        description:
          type: string
        format:
          type: string
    Tag:
      required:
        - id
        - name
      type: object
      properties:
        id:
          type: string
          example: 123e4567-e89b-12d3-a456-426655440000
        name:
          type: string
          example: marvel
        description:
          type: string
          example: Stories based on Marvel's comics.
        format:
          type: string
    PromptTemplateBase:
      type: object
      properties:
        name:
          type: string
          description: A name of the prompt template.
        description:
          type: string
          description: A description of the prompt template.
        lang:
          type: string
          description: A language code.
        system_prompt:
          type: string
          description: A system prompt.
        pre_prompt_query:
          type: string
          description: A text that is prepended before the contextual document chunks.
        prompt_query:
          type: string
          description: A text that is appended to the beginning of the user's message.
        hyde_no_rag_llm_prompt_extension:
          type: string
          description: An LLM prompt extension.
        pre_prompt_summary:
          type: string
          description: A prompt that goes before each large piece of text to summarize.
        prompt_summary:
          type: string
          description: A prompt that goes after each large piece of text to summarize.
        system_prompt_reflection:
          type: string
          description: A system prompt for self-reflection.
        prompt_reflection:
          type: string
          description: A template for self-reflection, must contain two occurrences of %s for full previous prompt
                       (including system prompt, document related context and prompts if applicable, and user prompts)
                       and answer
        auto_gen_description_prompt:
          type: string
          description: A prompt to create a description of the collection.
        auto_gen_document_summary_pre_prompt_summary:
          type: string
          description: A `pre_prompt_summary` for summary of a freshly imported document (if enabled).
        auto_gen_document_summary_prompt_summary:
          type: string
          description: A `prompt_summary` for summary of a freshly imported document (if enabled).`
        auto_gen_document_sample_questions_prompt:
          type: string
          description: A prompt to create sample questions for a freshly imported document (if enabled).
        default_sample_questions:
          type: array
          items:
            type: string
          description: Default sample questions in case there are no auto-generated sample questions.
        image_batch_image_prompt:
          type: string
          description: A prompt for each image batch for vision models.
        image_batch_final_prompt:
          type: string
          description: A prompt for each image batch for vision models.
    PromptTemplateCreateRequest:
      allOf:
        - $ref: '#/components/schemas/PromptTemplateBase'
        - type: object
          required:
            - name
          properties:
            name:
              type: string
    PromptTemplateUpdateRequest:
      $ref: '#/components/schemas/PromptTemplateBase'
    PromptTemplate:
      allOf:
        - $ref: '#/components/schemas/PromptTemplateBase'
        - type: object
          required:
            - id
            - is_default
          properties:
            id:
              description: A unique identifier of the prompt template.
              type: string
            is_default:
              description: A flag identifying if the prompt template is default or not.
              type: boolean
            user_count:
              description: A number of users having access to the prompt template.
              type: integer
            username:
              description: Name of the user owning the prompt template.
              type: string
            created_at:
              description: The moment when the prompt template was created.
              type: string
              format: date-time
            updated_at:
              description: The Last time when the prompt template was modified.
              type: string
              format: date-time
    SharePermission:
      required:
        - username
      type: object
      properties:
        username:
          type: string
    UserInfo:
      required:
        - id
        - username
        - email
      type: object
      properties:
        id:
          type: string
        username:
          type: string
        email:
          type: string
    UserPermission:
      required:
        - id
        - name
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        category:
          type: string
    GroupInfo:
      required:
        - id
        - name
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
    GroupCreateRequest:
      required:
        - name
        - description
      type: object
      properties:
        name:
          type: string
        description:
          type: string
    RoleInfo:
      required:
        - id
        - name
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
    RoleCreateRequest:
      required:
        - name
        - description
      type: object
      properties:
        name:
          type: string
        description:
          type: string
    PermissionCheckRequest:
      required:
        - permission
      type: object
      properties:
        permission:
          type: string
    UploadedFile:
      required:
        - id
        - filename
      type: object
      properties:
        id:
          type: string
          example: 123e4567-e89b-12d3-a456-426655440000
        filename:
          type: string
          example: my_favourite_book.pdf
    ChatSessionUpdateRequest:
      required:
        - name
      type: object
      properties:
        name:
          type: string
    MessageVoteUpdateRequest:
      required:
        - votes
      type: object
      properties:
        votes:
          type: integer
    DeleteChatSessionsJobRequest:
      type: object
      required:
        - session_ids
      properties:
        session_ids:
          description: Ids of chat sessions to be deleted.
          type: array
          items:
            type: string
    ChatSession:
      required:
        - id
        - updated_at
      type: object
      properties:
        id:
          type: string
          example: 123e4567-e89b-12d3-a456-426655440000
        name:
          type: string
          example: Discussion about sci-fi heroes.
        collection_id:
          type: string
          example: c91e7c84-65df-4b43-ba15-fbd3afb2e86f
        collection_name:
          type: string
        prompt_template_id:
          type: string
          example: 4e400991-c459-455f-995c-dc6f55ffdb90
        latest_message_content:
          type: string
          example: The strongest hero is superman!
        updated_at:
          type: string
          format: date-time
    ChatCompletionRequest:
      required:
        - message
      type: object
      properties:
        message:
          type: string
          description: A query or an instruction from the end user to the LLM.
          example: Who is the strongest hero?
        system_prompt:
          type: string
          description: A text sent to models which support system prompts. It gives the model
                       overall context in how to respond. Use 'auto' for the model default.
                       Don't specify for no system prompt.
        pre_prompt_query:
          type: string
          description: A text that is prepended before the contextual document chunks.
                       The default can be customized per environment.
          default: Pay attention and remember the information below, which will help to answer
                   the question or imperative after the context ends.\\\\n
        prompt_query:
          type: string
          description: A text that is appended to the beginning of the user's message.
                       The default can be customized per environment.
          default: According to only the information in the document sources provided within the context above,
        image_batch_final_prompt:
          type: string
          description: A prompt for each image batch for vision models.
        image_batch_image_prompt:
          type: string
          description: A prompt to reduce all answers each image batch for vision models
        llm:
          type: string
          description: LLM name to send the query. Use "auto" for automatic model routing,
                       set cost_controls of llm_args for detailed control over automatic routing.
        llm_args:
          $ref: '#/components/schemas/ChatCompletionRequestLLMArgs'
        self_reflection_config:
          $ref: '#/components/schemas/ChatCompletionSelfReflectionConfig'
        rag_config:
          $ref: '#/components/schemas/ChatCompletionRAGConfig'
        include_chat_history:
          type: string
          enum: [on, off, auto]
          description: Whether to include chat history. Includes previous questions and answers for
                       the current chat session for each new chat request. Disable if require deterministic
                       answers for a given question.
        tags:
          type: array
          items:
            type: string
          description: A list of tags from which to pull the context for RAG.
        stream:
          type: boolean
          default: false
    ChatCompletionRequestLLMArgs:
      type: object
      description: |
        A map of arguments sent to LLM with query.
          * `temperature` **(type=double, default=0.0)** - A value used to modulate the next token probabilities.
            0 is the most deterministic and 1 is most creative.
          * `top_k` **(type=integer, default=1)** - A number of highest probability vocabulary tokens to keep for top-k-filtering.
          * `top_p` **(type=double, default=0.0)** - If set to a value < 1, only the smallest set of most probable
            tokens with probabilities that add up to top_p or higher are kept for generation.
          * `seed` **(type=integer, default=0)** - A seed for the random number generator when sampling during
             generation (if temp>0 or top_k>1 or top_p<1), seed=0 picks a random seed.
          * `repetition_penalty` **(type=double, default=1.07)** - A parameter for repetition penalty. 1.0 means no penalty.
          * `max_new_tokens` **(type=double, default=1024)** - A maximum number of new tokens to generate.
            This limit applies to each (map+reduce) step during summarization and each (map) step during extraction.
          * `min_max_new_tokens` **(type=integer, default=512)** - A minimum value for max_new_tokens when auto-adjusting for content of prompt, docs, etc.
          * `response_format` **(type=enum[text, json_object, json_code], default=text)** - An output type of LLM
          * `guided_json` **(type=map)** - If specified, the output will follow the JSON schema.
          * `guided_regex` **(type=string)** - If specified, the output will follow the regex pattern.
            Only for models that support guided generation.
          * `guided_choice` **(type=array[string])** - If specified, the output will be exactly one of the choices.
            Only for models that support guided generation.
          * `guided_grammar` **(type=string)** - If specified, the output will follow the context free grammar.
            Only for models that support guided generation.
          * `guided_whitespace_pattern` **(type=string)** - If specified, will override the default whitespace pattern for guided json decoding.
            Only for models that support guided generation.
          * `enable_vision` **(type=enum[on, off, auto], default=auto)** - Controls vision mode,
            send images to the LLM in addition to text chunks.
          * `visible_vision_models` **(type=array[string], default=[auto])** - Controls which vision model to use when processing images.
            Must provide exactly one model. [auto] for automatic.
          * `images_num_max` **(type=integer, default=None)** - Maximum number of images to process.
          * `json_preserve_system_prompt` **(type=boolean, default=None)** - Whether to preserve system prompt in JSON response.
          * `client_metadata` **(type=string, default=None)** - Additional metadata to send with the request.
          * `min_chars_per_yield` **(type=integer, default=1)** - Minimum characters to yield in streaming response.
          * `cost_controls` **(type=map)** A map with cost controls settings:
            * `max_cost` **(type=double)** - Sets the maximum allowed cost in USD per LLM call when doing Automatic model routing.
              If the estimated cost based on input and output token counts is higher than this limit,
              the request will fail as early as possible.
            * `max_cost_per_million_tokens` **(type=double)** - Only consider models that cost less than this value in USD per million tokens
              when doing automatic routing. Using the max of input and output cost.
            * `model` **(type=array[string])** - Optional subset of models to consider when doing automatic routing.
              If not specified, all models are considered.
            * `willingness_to_pay` **(type=double)** - Controls the willingness to pay extra for a more accurate model for every LLM call
              when doing automatic routing, in units of USD per +10% increase in accuracy.
              We start with the least accurate model. For each more accurate model,
              we accept it if the increase in estimated cost divided by the increase in estimated accuracy
              is no more than this value divided by 10%, up to the upper limit specified above.
              Lower values will try to keep the cost as low as possible,
              higher values will approach the cost limit to increase accuracy. 0 means unlimited.
            * `willingness_to_wait` **(type=double)** - Controls the willingness to wait longer for a more accurate model for every LLM call
              when doing automatic routing, in units of seconds per +10% increase in accuracy.
              We start with the least accurate model. For each more accurate model,
              we accept it if the increase in estimated time divided by the increase in estimated accuracy
              is no more than this value divided by 10%. Lower values will try to keep the time
              as low as possible, higher values will take longer to increase accuracy. 0 means unlimited.
          * `use_agent` **(type=boolean, default=False)** - If True, use the AI agent (with access to tools) to generate the response.
          * `agent_accuracy` **(type=string, default="standard")** - Effort level by the agent. Only if use_agent=True. One of ["quick", "basic", "standard", "maximum"].
          * `agent_max_turns` **(type=union[string, integer], default="auto")** - Optional max. number of back-and-forth turns with the agent. Only if use_agent=True. Either "auto" or an integer.
          * `agent_tools` **(type=union[string, array[string]], default="auto")** - Either "auto", "all", "any" to enable all available tools, or a specific list of tools to use. Only if use_agent=True.
          * `agent_type` **(type=string, default="auto")** - Type of agent to use for task processing.
          * `agent_original_files` **(type=array[string], default=None)** - List of file paths for agent to process.
          * `agent_timeout` **(type=integer, default=None)** - Timeout in seconds for each agent turn.
          * `agent_total_timeout` **(type=integer, default=3600)** - Total timeout in seconds for all agent processing.
          * `agent_code_writer_system_message` **(type=string, default=None)** - System message for agent code writer.
          * `agent_num_executable_code_blocks_limit` **(type=integer, default=1)** - Maximum number of executable code blocks.
          * `agent_system_site_packages` **(type=boolean, default=True)** - Whether agent has access to system site packages.
          * `agent_main_model` **(type=string, default=None)** - Main model to use for agent.
          * `agent_max_stream_length` **(type=integer, default=None)** - Maximum stream length for agent response.
          * `agent_max_memory_usage` **(type=integer, default=16*1024**3)** - Maximum memory usage for agent in bytes (16GB default).
          * `agent_main_reasoning_effort` **(type=integer, default=None)** - Effort level for main reasoning.
          * `agent_advanced_reasoning_effort` **(type=integer, default=None)** - Effort level for advanced reasoning.
          * `agent_max_confidence_level` **(type=integer, default=None)** - Maximum confidence level for agent responses.
          * `agent_planning_forced_mode` **(type=boolean, default=None)** - Whether to force planning mode for agent.
          * `agent_too_soon_forced_mode` **(type=boolean, default=None)** - Whether to force "too soon" mode for agent.
          * `agent_critique_forced_mode` **(type=integer, default=None)** - Whether to force critique mode for agent.
          * `agent_stream_files` **(type=boolean, default=True)** - Whether to stream files from agent.
      additionalProperties: true
    ChatCompletionSelfReflectionConfig:
      type: object
      description: |
        A map with self reflection settings:
          * `llm_reflection` **(type=string, example=gpt-4-0613)**
          * `prompt_reflection` **(type=string, example=\"\"\"Prompt:\\\\n%s\\\\n\"\"\"\\\\n\\\\n\"\"\")**
          * `system_prompt_reflection` **(type=string)**
          * `llm_args_reflection` **(type=string, example={})**
      additionalProperties: true
    ChatCompletionRAGConfig:
      type: object
      description: |
        A map with arguments to control RAG (retrieval-augmented-generation) types.:
          * `rag_type` **(type=enum[auto, llm_only, rag, hyde1, hyde2, rag+, all_data])** RAG type options:
            * `auto` - Automatically select the best rag_type.
            * `llm_only` LLM Only - Answer the query without any supporting document contexts.
               Requires 1 LLM call.
            * `rag` RAG (Retrieval Augmented Generation) - Use supporting document contexts
               to answer the query. Requires 1 LLM call.
            * `hyde1` LLM Only + RAG composite - HyDE RAG (Hypothetical Document Embedding).
               Use 'LLM Only' response to find relevant contexts from a collection for generating
               a response. Requires 2 LLM calls.
            * `hyde2` HyDE + RAG composite - Use the 'HyDE RAG' response to find relevant
               contexts from a collection for generating a response. Requires 3 LLM calls.
            * `rag+` Summary RAG - Like RAG, but uses more context and recursive
               summarization to overcome LLM context limits. Keeps all retrieved chunks, puts
               them in order, adds neighboring chunks, then uses the summary API to get the
               answer. Can require several LLM calls.
            * `all_data` All Data RAG - Like Summary RAG, but includes all document
               chunks. Uses recursive summarization to overcome LLM context limits.
               Can require several LLM calls.
          * `hyde_no_rag_llm_prompt_extension` **(type=string, example=\\\\nKeep the answer brief, and list the 5 most relevant key words at the end.)** -
            Add this prompt to every user's prompt, when generating answers to be used for subsequent retrieval during HyDE.
            Only used when rag_type is `hyde1` or `hyde2`.
          * `num_neighbor_chunks_to_include` **(type=integer, default=1)** - A number of neighboring chunks to include 
            for every retrieved relevant chunk. It helps to keep surrounding context together. Only enabled for rag_type `rag+`.
          * `meta_data_to_include` **(type=map)** - A map with flags that indicate whether each piece of document metadata 
            is to be included as part of the context for a chat with a collection.
            * `name` **(type: boolean, default=True)**
            * `text` **(type: boolean, default=True)**
            * `page` **(type: boolean, default=True)**
            * `captions` **(type: boolean, default=True)**
            * `uri` **(type: boolean, default=False)**
            * `connector` **(type: boolean, default=False)**
            * `original_mtime` **(type: boolean, default=False)**
            * `age` **(type: boolean, default=False)**
            * `score` **(type: boolean, default=False)**
          * `rag_max_chunks` **(type=integer, default=-1)** - Maximum number of document chunks to retrieve for RAG.
            Actual number depends on rag_type and admin configuration. Set to >0 values to enable. 
            Can be combined with rag_min_chunk_score.
          * `rag_min_chunk_score` **(type=double, default=0.0)** - Minimum score of document chunks to retrieve for RAG.
            Set to >0 values to enable. Can be combined with rag_max_chunks.
    ChatCompletion:
      required:
        - body
      type: object
      properties:
        body:
          type: string
          example: The strongest here is Superman!
    ChatCompletionDelta:
      required:
        - body
        - finished
      type: object
      properties:
        body:
          type: string
          example: The strongest
        finished:
          type: boolean
    ChatError:
      required:
        - error
      type: object
      properties:
        error:
          type: string
          example: The communication with llm has been interrupted
    ChatMessage:
      required:
        - id
        - content
        - votes
        - created_at
        - has_references
        - total_references
      type: object
      properties:
        id:
          type: string
          example: 123e4567-e89b-12d3-a456-426655440000
        content:
          type: string
        votes:
          type: integer
        created_at:
          type: string
          format: date-time
        has_references:
          type: boolean
        total_references:
          type: integer
        username:
          type: string
        reply_to:
          type: string
        error:
          type: string
        type_list:
          type: array
          items:
            $ref: '#/components/schemas/ChatMessageMeta'
    ChatMessageMeta:
      required:
        - message_type
        - content
      type: object
      properties:
        message_type:
          type: string
        content:
          type: string
    ChatMessageReference:
      required:
        - document_id
        - document_name
        - chunk_id
        - pages
        - score
        - were_references_deleted
      type: object
      properties:
        collection_id:
          type: string
        document_id:
          type: string
        document_name:
          type: string
        chunk_id:
          type: integer
        score:
          type: number
        pages:
          type: string
        content:
          type: string
        were_references_deleted:
          type: boolean
    SuggestedQuestion:
      required:
        - question
      type: object
      properties:
        question:
          type: string
    UpdateQAFeedbackRequest:
      required:
        - expected_answer
        - user_comment
      type: object
      properties:
        expected_answer:
          type: string
        user_comment:
          type: string
    QAFeedback:
      required:
        - question_content
        - reply_content
        - question_id
        - reply_id
        - votes
        - response_created_at_time
      type: object
      properties:
        question_content:
          type: string
        reply_content:
          type: string
        question_id:
          type: string
        reply_id:
          type: string
        llm:
          type: string
        system_prompt:
          type: string
        pre_prompt_query:
          type: string
        prompt_query:
          type: string
        pre_prompt_summary:
          type: string
        prompt_summary:
          type: string
        rag_config:
          type: string
        collection_documents:
          type: array
          items:
            type: string
        votes:
          type: integer
        expected_answer:
          type: string
        user_comment:
          type: string
        collection_id:
          type: string
        collection_name:
          type: string
        response_created_at_time:
          type: string
        prompt_template_id:
          type: string
        include_chat_history:
          type: string
    S3Credentials:
      description: The object with S3 credentials. If the object is not provided, only public buckets will be accessible.
      required:
        - access_key_id
        - secret_access_key
      type: object
      properties:
        access_key_id:
          type: string
        secret_access_key:
          type: string
        session_token:
          type: string
        role_arn:
          type: string
    GCSCredentials:
      description: The object holding  JSON key of Google Cloud service account.
                   If the object is not provided, only public buckets will be accessible.
      required:
        - service_account_json_key
      type: object
      properties:
        service_account_json_key:
          type: string
    AzureCredentials:
      description: The object with Azure credentials. If container is private, set either `account_key` or `sas_token`.
      type: object
      properties:
        account_key:
          type: string
        sas_token:
          type: string
    Model:
      required:
        - id
        - display_name
      type: object
      properties:
        id:
          description: The model identifier.
          type: string
        display_name:
          description: The model name.
          type: string
      additionalProperties: true
    EmbeddingModel:
      required:
        - id
        - display_name
        - description
        - languages
      type: object
      properties:
        id:
          description: The model identifier.
          type: string
        display_name:
          description: The model name.
          type: string
        description:
          description: The model description.
          type: string
        languages:
          description: Languages supported by the model.
          type: array
          items:
            type: string
    UsageStats:
      required:
        - current
        - max_allowed_24h
        - cost_unit
        - interval
      type: object
      properties:
        current:
          type: number
          format: double
        max_allowed_24h:
          type: number
          format: double
        cost_unit:
          type: string
        interval:
          type: string
    UsageStatsPerModel:
      required:
        - llm_name
        - llm_cost
        - call_count
        - input_tokens
        - output_tokens
      type: object
      properties:
        llm_name:
          type: string
        llm_cost:
          type: number
          format: double
        call_count:
          type: integer
        input_tokens:
          type: integer
        output_tokens:
          type: integer
    UsageStatsPerUser:
      required:
        - user_id
        - username
        - email
        - llm_usage
      type: object
      properties:
        user_id:
          type: string
        username:
          type: string
        email:
          type: string
        llm_usage:
          type: array
          items:
            $ref: '#/components/schemas/UsageStatsPerModel'
    UsageStatsPerModelAndUser:
      required:
        - llm_name
        - total_cost
        - total_calls
        - total_input_tokens
        - total_output_tokens
        - user_usage
      type: object
      properties:
        llm_name:
          type: string
        total_cost:
          type: number
          format: double
        total_calls:
          type: integer
        total_input_tokens:
          type: integer
        total_output_tokens:
          type: integer
        user_usage:
          type: array
          items:
            $ref: '#/components/schemas/ModelUsageStatsPerUser'
    ModelUsageStatsPerUser:
      required:
        - user_id
        - username
        - email
        - llm_cost
        - call_count
        - input_tokens
        - output_tokens
      type: object
      properties:
        user_id:
          type: string
        username:
          type: string
        email:
          type: string
        llm_cost:
          type: number
          format: double
        call_count:
          type: integer
        input_tokens:
          type: integer
        output_tokens:
          type: integer
    PerformanceStatsPerModel:
      required:
        - llm_name
        - call_count
        - input_tokens
        - output_tokens
        - tokens_per_second
        - time_to_first_token
      type: object
      properties:
        llm_name:
          type: string
        call_count:
          type: integer
        input_tokens:
          type: integer
        output_tokens:
          type: integer
        tokens_per_second:
          type: number
          format: double
        time_to_first_token:
          type: number
          format: double
    IngestUploadBody:
      type: object
      properties:
        metadata:
          description: Metadata for the document.
          type: object
    IngestFromFileSystemBody:
      type: object
      required:
        - root_dir
        - glob
      properties:
        root_dir:
          description: String path of where to look for files.
          type: string
        glob:
          description: String of the glob pattern used to match files in the root directory.
          type: string
    IngestFromWebsiteBody:
      type: object
      required:
        - url
      properties:
        url:
          description: String of the url to crawl.
          type: string
    IngestFromS3Body:
      type: object
      required:
        - urls
      properties:
        urls:
          description: The path or list of paths of S3 files or directories.
          type: array
          items:
            type: string
          example: s3://bucket/file, s3://bucket/../dir/
        region:
          description: The name of the region used for interaction with AWS services.
          type: string
          default: us-east-1
        credentials:
          $ref: '#/components/schemas/S3Credentials'
        metadata:
          description: Metadata for the documents.
          type: object
    IngestFromGcsBody:
      type: object
      required:
        - urls
      properties:
        urls:
          description: The path or list of paths of GCS files or directories.
          type: array
          items:
            type: string
          example: gs://bucket/file, gs://bucket/../dir/
        credentials:
          $ref: '#/components/schemas/GCSCredentials'
        metadata:
          description: Metadata for the document.
          type: object
    IngestFromAzureBlobStorageBody:
      type: object
      required:
        - container
        - paths
        - account_name
      properties:
        container:
          description: Name of the Azure Blob Storage container.
          type: string
        paths:
          description: Path or list of paths to files or directories within an Azure Blob Storage container.
          type: array
          items:
            type: string
          example: file1, dir1/file2, dir3/dir4/
        account_name:
          description: Name of a storage account
          type: string
        credentials:
          $ref: '#/components/schemas/AzureCredentials'
        metadata:
          description: Metadata for the document.
          type: object
    UserJobDetails:
      type: object
      required:
        - username
        - user_id
        - jobs
      properties:
        username:
          type: string
        user_id:
          type: string
        jobs:
          type: array
          items:
            $ref: '#/components/schemas/JobDetails'

    JobDetails:
      required:
        - id
        - name
        - overall_status
        - passed_percentage
        - failed_percentage
        - progress
        - created_at
        - updated_at
        - kind
        - statuses
        - errors
        - duration
        - duration_seconds
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        overall_status:
          type: string
          enum:
            - in progress
            - completed
            - failed
            - canceled
        status:
          type: string
        passed_percentage:
          type: number
          format: double
        failed_percentage:
          type: number
          format: double
        progress:
          type: number
          format: double
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        kind:
          type: string
        statuses:
          type: array
          items:
            $ref: '#/components/schemas/JobDetailsStatus'
        errors:
          type: array
          items:
            type: string
        duration:
          type: string
        duration_seconds:
          type: number
          format: double
        canceled_by:
          type: string
        timeout:
          type: number
          format: double
        start_time:
          type: number
          format: double
    RolesResetRequest:
      required:
        - new_roles
      type: object
      properties:
        new_roles:
          type: array
          items:
            type: string
    PermissionResetRequest:
      required:
        - new_permissions
      type: object
      properties:
        new_permissions:
          type: array
          items:
            type: string
    ShareCollectionRequest:
      type: object
      properties:
        permissions:
          description: Individual permission levels defining the sharing rule.
          type: array
          items:
            type: string
    JobDetailsStatus:
      required:
        - id
        - status
      type: object
      properties:
        id:
          type: string
        status:
          type: string
    SelfTestResult:
      required:
        - origin
        - llm
        - input_tokens
        - output_tokens
        - time_to_first_token
        - tokens_per_second
      type: object
      additionalProperties: true
      properties:
        origin:
          type: string
        llm:
          type: string
        input_tokens:
          type: integer
        output_tokens:
          type: integer
        time_to_first_token:
          type: number
        tokens_per_second:
          type: number
        responses:
          type: array
          items:
            type: string
        error:
          type: string
    AgentServerFile:
      required:
        - id
        - object
        - bytes
        - created_at
        - filename
        - purpose
      type: object
      additionalProperties: true
      properties:
        id:
          type: string
        object:
          type: string
        bytes:
          type: integer
        created_at:
          type: integer
        filename:
          type: string
        purpose:
          type: string
    AgentServerDirectoryStatsPerAgentChatSession:
      required:
        - agent_chat_session_id
        - chat_preview
        - stats
      type: object
      properties:
        agent_chat_session_id:
          type: string
        chat_preview:
          type: string
        stats:
          type: array
          items:
            $ref: '#/components/schemas/AgentServerDirectoryStats'

    AgentServerDirectoryStats:
      required:
        - id
        - object
        - size_bytes
        - size_human_readable
        - file_count
        - directory_count
        - created_timestamp
        - modified_timestamp
        - created_date
        - modified_date
        - is_empty
        - top_level_contents
        - owner
        - permissions
      type: object
      additionalProperties: true
      properties:
          id:
            type: string
          object:
            type: string
          size_bytes:
            type: integer
          size_human_readable:
            type: string
          file_count:
            type: integer
          directory_count:
            type: integer
          created_timestamp:
            type: number
          modified_timestamp:
            type: number
          created_date:
            type: string
          modified_date:
            type: string
          is_empty:
            type: boolean
          top_level_contents:
            type: array
            items:
              type: string
          owner:
            type: string
          permissions:
            type: string
          files:
            description: Only populated when detail_level > 0
            type: array
            items:
              $ref: '#/components/schemas/AgentServerDirectoryFileStats'
    AgentServerDirectoryFileStats:
      required:
        - name
        - path
        - size_bytes
        - size_human_readable
        - created_timestamp
        - modified_timestamp
        - created_date
        - modified_date
        - is_directory
        - owner
        - permissions
      type: object
      additionalProperties: true
      properties:
        name:
          type: string
        path:
          type: string
        size_bytes:
          type: integer
        size_human_readable:
          type: string
        created_timestamp:
          type: number
        modified_timestamp:
          type: number
        created_date:
          type: string
        modified_date:
          type: string
        is_directory:
          type: boolean
        owner:
          description: Unix systems only
          type: string
        permissions:
          description: Unix systems only
          type: string
        sha256:
          description: Only for files, not directories
          type: string
    AgentToolSpecApiKeys:
      required:
        - required
        - optional
        - internal
      description: The specific keys associated with an agent tool.
      type: object
      properties:
        required:
          description: List of required keys set for the tool to function.
          type: array
          items:
            type: string
        optional:
          description: The tool can still operate even if these keys are not set.
          type: array
          items:
            type: string
        internal:
          description: Keys that are managed internally by the system.
          type: array
          items:
            type: string
    AgentToolSpec:
      required:
        - name
        - description
        - enabled
        - default
        - extendable
        - api_keys
      type: object
      properties:
        name:
          description: The identifier representing the specific tool.
          type: string
        description:
          description: Description of the tool.
          type: string
        enabled:
          description: Specifies whether the tool is currently enabled in H2OGPT.
          type: boolean
        default:
          description: Specifies if the tool is pre-selected by default when available.
          type: boolean
        extendable:
          description: Specifies whether the tool supports custom API keys
          type: boolean
        api_keys:
          $ref: '#/components/schemas/AgentToolSpecApiKeys'
    CreateAgentKeyRequest:
      required:
        - name
        - type
        - value
      type: object
      properties:
        name:
          type: string
        type:
          type: string
          enum: [ private, shared ]
        value:
          type: string
        description:
          type: string
    UpdateAgentKeyRequest:
      type: object
      properties:
        name:
          type: string
        type:
          type: string
          enum: [ private, shared ]
        value:
          type: string
        description:
          type: string
    AgentKey:
      required:
        - name
        - type
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        type:
          type: string
          enum: [private, shared, built_in]
        description:
          type: string
        created_at:
          type: string
        updated_at:
          type: string
        owner_email:
          type: string
    KeyAssociation:
      required:
        - name
        - key_id
      type: object
      properties:
        name:
          type: string
        key_id:
          type: string
        associate_id:
          type: string
        user_id:
          type: string
        email:
          type: string
    NewKeyAssociation:
      required:
        - name
        - key_id
      type: object
      properties:
        name:
          type: string
        key_id:
          type: string
    AgentToolKeyAssociations:
      required:
        - tool
        - keys
      type: object
      properties:
        tool:
          type: string
        keys:
          type: array
          items: 
            $ref: '#/components/schemas/KeyAssociation'
    CreateAgentToolKeyAssociationsRequest:
      required:
        - tool
        - keys
      type: object
      properties:
        tool:
          type: string
        keys:
          type: array
          items:
            $ref: '#/components/schemas/NewKeyAssociation'
    H2OGPTSystemInfo:
      required:
        - timestamp
        - uptime_seconds
        - hostname
        - os_name
        - os_version
        - kernel_version
        - cpu_count_physical
        - cpu_count_logical
        - cpu_percent_per_cpu
        - cpu_freq_current
        - cpu_freq_min
        - cpu_freq_max
        - load_avg_1min
        - load_avg_5min
        - load_avg_15min
        - memory_total
        - memory_available
        - memory_used
        - memory_percent
        - swap_total
        - swap_used
        - swap_percent
        - disk_partitions
        - disk_usage
        - disk_io_counters
        - network_interfaces
        - network_io_counters
        - network_connections_count
        - gpus
        - process_count
        - top_processes_cpu
        - top_processes_memory
      type: object
      properties:
        timestamp:
          type: string
        uptime_seconds:
          type: number
        hostname:
          type: string
        os_name:
          type: string
        os_version:
          type: string
        kernel_version:
          type: string
        cpu_count_physical:
          type: integer
        cpu_count_logical:
          type: integer
        cpu_percent_per_cpu:
          type: array
          items:
            type: number
        cpu_freq_current:
          type: number
        cpu_freq_min:
          type: number
        cpu_freq_max:
          type: number
        cpu_temperature:
          type: number
        load_avg_1min:
          type: number
        load_avg_5min:
          type: number
        load_avg_15min:
          type: number
        memory_total:
          type: integer
        memory_available:
          type: integer
        memory_used:
          type: integer
        memory_percent:
          type: number
        swap_total:
          type: integer
        swap_used:
          type: integer
        swap_percent:
          type: number
        disk_partitions:
          type: array
          items:
            type: object
            additionalProperties:
              type: string
        disk_usage:
          type: object
          additionalProperties:
            type: object
            additionalProperties:
              type: number
        disk_io_counters:
          type: object
          additionalProperties:
            type: number
        network_interfaces:
          type: array
          items:
            type: string
        network_io_counters:
          type: object
          additionalProperties:
            type: object
            additionalProperties:
              type: number
        network_connections_count:
          type: integer
        gpus:
          type: array
          items:
            $ref: '#/components/schemas/H2OGPTGPUInfo'
        process_count:
          type: integer
        top_processes_cpu:
          type: array
          items:
            type: object
        top_processes_memory:
          type: array
          items:
            type: object
    H2OGPTGPUInfo:
      required:
        - name
      type: object
      properties:
        name:
          type: string
        temperature:
          type: number
        utilization:
          type: number
        memory_total:
          type: integer
        memory_used:
          type: integer
        power_usage:
          type: number
        fan_speed:
          type: integer
    ModelRequestBase:
      type: object
      additionalProperties: true

    QuestionRequest:
      type: object
      additionalProperties: true
      required:
        - question
      properties:
        text_context_list:
          description: List of raw text strings to be summarized.
          type: array
          items:
            type: string
        system_prompt:
          description: |
            Text sent to models which support system prompts. Gives the model
            overall context in how to respond. Use `auto` for the model default or None for h2oGPTe defaults. Defaults
            to '' for no system prompt.
          type: string
          default: ''
        llm_args:
          $ref: '#/components/schemas/ChatCompletionRequestLLMArgs'
        guardrails_settings:
          $ref: '#/components/schemas/GuardrailsSettings'
        timeout:
          description: Timeout in seconds.
          type: integer
        pre_prompt_query:
          description: Text that is prepended before the contextual document chunks in text_context_list.
            Only used if text_context_list is provided.
          type: string
        prompt_query:
          description: Text that is appended after the contextual document chunks in text_context_list.
            Only used if text_context_list is provided.
          type: string
        question:
          description: Text query to send to the LLM.
          type: string
        chat_conversation:
          description: |
            List of tuples for (human, bot) conversation that will be pre-appended
            to an (question, None) case for a query.
          type: array
          items:
            type: array
            minItems: 2
            maxItems: 2
            items:
              type: string
    SummarizeRequest:
      type: object
      additionalProperties: true
      properties:
        text_context_list:
          description: List of raw text strings to be summarized.
          type: array
          items:
            type: string
            nullable: true
        system_prompt:
          description: |
            Text sent to models which support system prompts. Gives the model
            overall context in how to respond. Use `auto` for the model default or None for h2oGPTe defaults. Defaults
            to '' for no system prompt.
          type: string
          default: ''
        llm_args:
          $ref: '#/components/schemas/ChatCompletionRequestLLMArgs'
        guardrails_settings:
          $ref: '#/components/schemas/GuardrailsSettings'
        timeout:
          description: Timeout in seconds.
          type: integer
        pre_prompt_summary:
          description: |
            Text that is prepended before the list of texts. The default can be
            customized per environment, but the standard default is `"In order to write a concise single-paragraph
            or bulleted list summary, pay attention to the following text:\\\\n"`
          type: string
        prompt_summary:
          description: |
            Text that is appended after the list of texts. The default can be customized
            per environment, but the standard default is `"Using only the text above, write a condensed and concise
            summary of key results (preferably as bullet points):\\\\n"`
          type: string
    ExtractionRequest:
      type: object
      additionalProperties: true
      properties:
        text_context_list:
          description: List of raw text strings to be summarized.
          type: array
          items:
            type: string
        system_prompt:
          description: |
            Text sent to models which support system prompts. Gives the model
            overall context in how to respond. Use `auto` for the model default or None for h2oGPTe defaults. Defaults
            to '' for no system prompt.
          type: string
          default: ''
        llm_args:
          $ref: '#/components/schemas/ChatCompletionRequestLLMArgs'
        guardrails_settings:
          $ref: '#/components/schemas/GuardrailsSettings'
        timeout:
          description: Timeout in seconds.
          type: integer
        pre_prompt_extract:
          description: |
            Text that is prepended before the list of texts. If not set,
            the inputs will be summarized.
          type: string
        prompt_extract:
          description: Text that is appended after the list of texts. If not set, the inputs will be summarized.
          type: string

    ModelAnswer:
      required:
        - content
        - error
        - llm
      type: object
      properties:
        content:
          type: string
        error:
          type: string
        prompt_raw:
          type: string
        llm:
          type: string
        input_tokens:
          type: integer
        output_tokens:
          type: integer
        origin:
          type: string
    ModelExtractionAnswer:
      required:
        - content
        - error
        - llm
      type: object
      properties:
        content:
          type: array
          items:
            type: string
        error:
          type: string
        llm:
          type: string
        input_tokens:
          type: integer
        output_tokens:
          type: integer
    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
    UserConfigurationItem:
      required:
        - key_name
        - string_value
        - value_type
      type: object
      properties:
        key_name:
          type: string
        string_value:
          type: string
        value_type:
          type: string
    EndpointError:
      required:
        - code
        - message
      properties:
        code:
          type: integer
          format: int32
          description: Error code
        message:
          type: string
          description: Error message

security:
  - bearerAuth: []