H2O.ai Shared Chats API

openapi: 3.2.0
info:
  title: h2oGPTe REST Shared Chats 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: Shared Chats
paths:
  /shared_chats:
    post:
      operationId: share_chat_session
      summary: Share a chat session
      description: Creates a shared chat from an existing chat session. Returns a URL that can be used to access the shared chat.
      tags:
      - Shared Chats
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShareChatRequest'
        required: true
      responses:
        '201':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShareChatResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        default:
          $ref: '#/components/responses/Unexpected'
    get:
      operationId: list_shared_chats
      summary: List shared chats
      description: List shared chats created by the current user.
      tags:
      - Shared Chats
      parameters:
      - name: offset
        in: query
        description: How many shared chats to skip.
        required: false
        schema:
          type: integer
          default: 0
      - name: limit
        in: query
        description: How many shared chats to return.
        required: false
        schema:
          type: integer
      - name: name_filter
        in: query
        description: Filter shared chats by name (case-insensitive substring match).
        required: false
        schema:
          type: string
      - name: filter_type
        in: query
        description: Filter shared chats by type (all, private, public, frozen).
        required: false
        schema:
          type: string
          default: all
      - name: showcase_filter
        in: query
        description: Filter shared chats by Showcase membership (all, featured, not_featured).
        required: false
        schema:
          type: string
          default: all
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SharedChatInfo'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'
  /shared_chats/{shared_chat_id}:
    get:
      operationId: get_shared_chat
      summary: Get a shared chat
      description: Get a shared chat by its ID. Public shared chats are accessible without authentication. Private shared chats require authentication.
      tags:
      - Shared Chats
      parameters:
      - name: shared_chat_id
        in: path
        description: ID of the shared chat.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SharedChatDetail'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        default:
          $ref: '#/components/responses/Unexpected'
    patch:
      operationId: update_shared_chat
      summary: Update a shared chat
      description: Update a shared chat's settings. Only the owner can update a shared chat.
      tags:
      - Shared Chats
      parameters:
      - name: shared_chat_id
        in: path
        description: ID of the shared chat to update.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSharedChatRequest'
        required: true
      responses:
        '204':
          description: Successful operation
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        default:
          $ref: '#/components/responses/Unexpected'
    delete:
      operationId: delete_shared_chat
      summary: Delete a shared chat
      description: Delete a single shared chat by its ID. Only the owner can delete a shared chat.
      tags:
      - Shared Chats
      parameters:
      - name: shared_chat_id
        in: path
        description: ID of the shared chat to delete.
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Successful operation
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        default:
          $ref: '#/components/responses/Unexpected'
  /shared_chats/batch_delete:
    post:
      operationId: delete_shared_chats
      summary: Batch delete shared chats
      description: Delete multiple shared chats by their IDs. Only the owner can delete shared chats.
      tags:
      - Shared Chats
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteSharedChatsRequest'
        required: true
      responses:
        '204':
          description: Successful operation
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        default:
          $ref: '#/components/responses/Unexpected'
components:
  responses:
    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'
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EndpointError'
    Unauthorized:
      description: Unauthorized - Invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EndpointError'
  schemas:
    UpdateSharedChatRequest:
      type: object
      properties:
        is_private:
          type: boolean
          description: Whether the shared chat requires authentication.
        includes_artifacts:
          type: boolean
          description: Whether to include file artifacts.
    SharedChatInfo:
      type: object
      required:
      - id
      - is_private
      - is_frozen
      - includes_artifacts
      - created_at
      properties:
        id:
          type: string
          description: Unique identifier of the shared chat.
        name:
          type: string
          description: Name of the shared chat.
        chat_session_id:
          type: string
          description: ID of the source chat session.
        is_private:
          type: boolean
          description: Whether the shared chat requires authentication.
        is_frozen:
          type: boolean
          description: Whether the shared chat is a frozen snapshot.
        includes_artifacts:
          type: boolean
          description: Whether file artifacts are included.
        created_at:
          type: string
          format: date-time
          description: When the shared chat was created.
        showcase_id:
          type: string
          description: 'When set, this shared chat is currently featured on the public

            Showcase page; this is the id of the matching showcase entry.

            '
    DeleteSharedChatsRequest:
      type: object
      required:
      - shared_chat_ids
      properties:
        shared_chat_ids:
          type: array
          items:
            type: string
          description: List of shared chat IDs to delete.
    ShareChatRequest:
      type: object
      required:
      - chat_session_id
      properties:
        chat_session_id:
          type: string
          description: ID of the chat session to share.
        is_private:
          type: boolean
          default: false
          description: Whether the shared chat requires authentication to view.
        is_frozen:
          type: boolean
          default: true
          description: Whether to capture a snapshot of the chat at share time.
        includes_artifacts:
          type: boolean
          default: false
          description: Whether to include file artifacts in the shared chat.
    EndpointError:
      required:
      - code
      - message
      properties:
        code:
          type: integer
          format: int32
          description: Error code
        message:
          type: string
          description: Error message
    SharedChatDetail:
      type: object
      required:
      - is_frozen
      - is_private
      - includes_artifacts
      - messages
      properties:
        name:
          type: string
          description: Name of the shared chat.
        shared_at:
          type: string
          description: When the chat was shared.
        shared_by:
          type: string
          description: Username of the person who shared the chat.
        is_frozen:
          type: boolean
          description: Whether the shared chat is a frozen snapshot.
        is_private:
          type: boolean
          description: Whether the shared chat requires authentication.
        includes_artifacts:
          type: boolean
          description: Whether file artifacts are included.
        messages:
          type: array
          items:
            type: object
          description: Chat messages in the shared chat.
    ShareChatResponse:
      type: object
      required:
      - url
      - relative_path
      properties:
        url:
          type: string
          description: Full URL to access the shared chat.
        relative_path:
          type: string
          description: Relative path to the shared chat.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Using an API key generated by H2OGPTe