H2O.ai Prompt Templates API

openapi: 3.2.0
info:
  title: h2oGPTe REST Prompt Templates API
  description: '# Overview


    Users can easily interact with the h2oGPTe API through its REST API, allowing HTTP requests from any programming language.'
  version: v1.0.0
servers:
- url: https://h2ogpte.genai.h2o.ai/api/v1
security:
- bearerAuth: []
tags:
- name: Prompt Templates
paths:
  /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'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        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'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Unexpected'
  /prompt_templates/all:
    get:
      operationId: list_all_prompt_templates
      summary: Lists prompt templates, including hidden default templates
      description: Lists prompt templates, including hidden default templates. Only for users who have the permission to manage 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
          - visible
          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'
        '400':
          $ref: '#/components/responses/BadRequest'
        '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'
        '400':
          $ref: '#/components/responses/BadRequest'
        '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'
        '400':
          $ref: '#/components/responses/BadRequest'
        '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'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        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'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        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
        '400':
          $ref: '#/components/responses/BadRequest'
        '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'
        '400':
          $ref: '#/components/responses/BadRequest'
        '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:
              $ref: '#/components/schemas/ResetAndShareRequest'
      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'
    delete:
      tags:
      - Prompt Templates
      summary: Removes sharing of a prompt template to all other users except the original…
      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
        '400':
          $ref: '#/components/responses/BadRequest'
        '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
        '400':
          $ref: '#/components/responses/BadRequest'
        '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
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          $ref: '#/components/responses/Conflict'
        default:
          $ref: '#/components/responses/Unexpected'
  /prompt_templates/{prompt_template_id}/group_permissions:
    get:
      tags:
      - Prompt Templates
      summary: Returns a list of group access permissions for a given prompt template
      description: The returned list of group permissions denotes which groups have access to the prompt template.
      operationId: get_prompt_template_group_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/GroupSharePermission'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/Unexpected'
    put:
      tags:
      - Prompt Templates
      summary: Resets and shares a prompt template to a new list of groups
      description: Resets and shares a prompt template to a new list of groups.
      operationId: reset_and_share_prompt_template_with_groups
      parameters:
      - name: prompt_template_id
        in: path
        description: Id of a prompt template.
        required: true
        schema:
          type: string
      requestBody:
        required: true
        description: List of group ids the prompt template should be shared with.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResetAndShareWithGroupsRequest'
      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'
  /prompt_templates/{prompt_template_id}/group_permissions/{group_id}:
    put:
      tags:
      - Prompt Templates
      summary: Shares a prompt template with a group
      description: Shares a prompt template with a user.
      operationId: share_prompt_template_with_group
      parameters:
      - name: prompt_template_id
        in: path
        description: Id of a prompt template.
        required: true
        schema:
          type: string
      - name: group_id
        in: path
        description: Id of the group that will obtain access to the prompt template.
        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'
    delete:
      tags:
      - Prompt Templates
      summary: Removes access to a prompt template for a group
      description: Removes access to a prompt template for a group.
      operationId: unshare_prompt_template_from_group
      parameters:
      - name: prompt_template_id
        in: path
        description: Id of a prompt template.
        required: true
        schema:
          type: string
      - name: group_id
        in: path
        description: Id of the group that will lose access to the prompt template.
        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'
  /prompt_templates/{prompt_template_id}/is_public:
    post:
      tags:
      - Prompt Templates
      summary: Updates a flag specifying whether a prompt template is private or public
      description: Updates a flag specifying whether a prompt template is private or public.
      operationId: update_prompt_template_privacy
      parameters:
      - name: prompt_template_id
        in: path
        description: Id of the prompt template.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - is_public
              properties:
                is_public:
                  description: A flag specifying whether a prompt template is private or public.
                  type: boolean
        required: true
      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'
  /prompt_templates/{prompt_template_id}/is_visible:
    put:
      tags:
      - Prompt Templates
      summary: Updates a flag specifying whether a default prompt template is visible or…
      description: Updates a flag specifying whether a default prompt template is visible or hidden to users.
      operationId: update_default_prompt_template_visibility
      parameters:
      - name: prompt_template_id
        in: path
        description: Id of a prompt template.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - is_visible
              properties:
                is_visible:
                  description: A flag specifying whether the default prompt template should be visible or not.
                  type: boolean
        required: true
      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'
components:
  schemas:
    Count:
      required:
      - count
      type: object
      properties:
        count:
          type: integer
    PromptTemplateUpdateRequest:
      $ref: '#/components/schemas/PromptTemplateBase'
    SharePermission:
      required:
      - username
      type: object
      properties:
        username:
          type: string
        permissions:
          type: array
          items:
            type: string
    EndpointError:
      required:
      - code
      - message
      properties:
        code:
          type: integer
          format: int32
          description: Error code
        message:
          type: string
          description: Error message
    PromptTemplate:
      allOf:
      - $ref: '#/components/schemas/PromptTemplateBase'
      - type: object
        required:
        - id
        - is_default
        - is_public
        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: The number of users who have access to the prompt template.
            type: integer
          group_count:
            description: The number of groups who have access to the prompt template.
            type: integer
          username:
            description: Name of the user owning the prompt template.
            type: string
          user_id:
            description: The unique identifier 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
          is_public:
            description: Whether the prompt template is public or private (only applies to custom templates).
            type: boolean
          visible:
            description: A flag identifying if a default prompt template is visible to system users.
            type: boolean
          is_system_default:
            description: A flag identifying if a default prompt template is the system default.
            type: boolean
    ResetAndShareWithGroupsRequest:
      required:
      - groups
      type: object
      properties:
        groups:
          type: array
          items:
            type: string
    ResetAndShareRequest:
      required:
      - usernames
      type: object
      properties:
        usernames:
          type: array
          items:
            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.
    GroupSharePermission:
      required:
      - group_id
      type: object
      properties:
        group_id:
          type: string
        permissions:
          type: array
          items:
            type: string
    PromptTemplateCreateRequest:
      allOf:
      - $ref: '#/components/schemas/PromptTemplateBase'
      - type: object
        required:
        - name
        properties:
          name:
            type: string
  responses:
    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'
    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