H2O.ai Collections API

openapi: 3.2.0
info:
  title: h2oGPTe REST Collections API
  description: "\n# Overview \n\nUsers can easily interact with the h2oGPTe API through its REST API, allowing HTTP requests from any programming language.\n\n## Authorization: Getting an API key\n\nSign up/in at Enterprise h2oGPTe and generate one of the following two types of API keys: \n\n- **Global API key**: If a Collection is not specified when creating a new API Key, that key is considered to be a global API Key. Use global API Keys to grant full user impersonation and system-wide access to all of your work. Anyone with access to one of your global API Keys can create, delete, or interact with any of your past, current, and future Collections, Documents, Chats, and settings.\n\n- **Collection-specific API key**: Use Collection-specific API Keys to grant external access to only Chat with a specified Collection and make related API calls to it. Collection-specific API keys do not allow other API calls, such as creation, deletion, or access to other Collections or Chats.\n \nAccess Enterprise h2oGPTe through your [H2O Generative AI](https://genai.h2o.ai/appstore) app store account, available with a freemium tier.\n\n## Authorization: Using an API key \n\nAll h2oGPTe REST API requests must include an API Key in the \"Authorization\" HTTP header, formatted as follows:\n\n```\nAuthorization: Bearer sk-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n```\n\n```sh\ncurl -X 'POST' \\\n  'https://h2ogpte.genai.h2o.ai/api/v1/collections' \\\n  -H 'accept: application/json' \\\n  -H 'Content-Type: application/json' \\\n  -H 'Authorization: Bearer sk-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' \\\n  -d '{\n    \"name\": \"The name of my Collection\",\n    \"description\": \"The description of my Collection\",\n    \"embedding_model\": \"BAAI/bge-large-en-v1.5\"\n  }'\n```\n    \n## Interactive h2oGPTe API testing\n\nThis page only showcases the h2oGPTe REST API; you can test it directly in the [Swagger UI](https://h2ogpte.genai.h2o.ai/swagger-ui/). Ensure that you are logged into your Enterprise h2oGPTe account.\n"
  version: v1.0.0
servers:
- url: https://h2ogpte.genai.h2o.ai/api/v1
security:
- bearerAuth: []
tags:
- name: Collections
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'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        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'
        '400':
          $ref: '#/components/responses/BadRequest'
        '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
      - name: filter
        in: query
        description: Filter collections by name, ID, or username.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Collection'
        '400':
          $ref: '#/components/responses/BadRequest'
        '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'
        '400':
          $ref: '#/components/responses/BadRequest'
        '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'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        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
        '400':
          $ref: '#/components/responses/BadRequest'
        '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'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        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'
        '400':
          $ref: '#/components/responses/BadRequest'
        '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'
        '400':
          $ref: '#/components/responses/BadRequest'
        '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'
        '400':
          $ref: '#/components/responses/BadRequest'
        '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'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'
  /collections/reset_all_collection_expirations:
    post:
      operationId: reset_all_collection_expirations
      summary: Reset all collection expiry dates and inactivity intervals that have been set.
      description: Reset any expiry dates and inactivity intervals that have been set for all collections (admin only). This will also reset any archived collections back to active.
      tags:
      - Collections
      responses:
        '204':
          description: Successful operation
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          $ref: '#/components/responses/Conflict'
        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'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        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'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        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
        '400':
          $ref: '#/components/responses/BadRequest'
        '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
        '400':
          $ref: '#/components/responses/BadRequest'
        '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
        '400':
          $ref: '#/components/responses/BadRequest'
        '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
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'
  /collections/{collection_id}/workspace:
    put:
      tags:
      - Collections
      summary: Updates the workspace associated with a collection.
      description: Updates the workspace associated with a collection as well as the chats belonging to the collection.
      operationId: update_collection_workspace
      parameters:
      - name: collection_id
        in: path
        description: Id of the collection
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - workspace
              properties:
                workspace:
                  description: The name of the workspace to be associated with the collection.
                  type: string
        required: true
      responses:
        '204':
          description: Successful operation
        '400':
          $ref: '#/components/responses/BadRequest'
        '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
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        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
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        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
        '400':
          $ref: '#/components/responses/BadRequest'
        '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
        '400':
          $ref: '#/components/responses/BadRequest'
        '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
                permissions:
                  type: array
                  description: Collection specific permissions, only used if is_public is true.
                  items:
                    type: string
        required: true
      responses:
        '204':
          description: Successful operation
        '400':
          $ref: '#/components/responses/BadRequest'
        '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'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        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
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        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
        '400':
          $ref: '#/components/responses/BadRequest'
        '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'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/N

# --- truncated at 32 KB (111 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/h2o-ai/refs/heads/main/openapi/h2o-ai-collections-api-openapi.yml