openapi: 3.2.0
info:
title: h2oGPTe REST Models 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: Models
paths:
/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
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
default:
$ref: '#/components/responses/Unexpected'
delete:
operationId: delete_topic_model
summary: Deletes the topic model from the collection.
description: Deletes the topic model from the collection.
tags:
- Models
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'
/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'
'400':
$ref: '#/components/responses/BadRequest'
'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'
'400':
$ref: '#/components/responses/BadRequest'
'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'
'400':
$ref: '#/components/responses/BadRequest'
'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
'400':
$ref: '#/components/responses/BadRequest'
'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'
'400':
$ref: '#/components/responses/BadRequest'
'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.\nNote: This method is only recommended if you are passing a chat conversation or for low-volume testing.\n For general chat with an LLM, use \"POST /chats/{session_id}/completions\" endpoint.\n"
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'
'400':
$ref: '#/components/responses/BadRequest'
'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'
'400':
$ref: '#/components/responses/BadRequest'
'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.\n`pre_prompt_extract` and `prompt_extract` variables must be used together. If these\n variables are not set, the inputs texts will be summarized into bullet points.\n"
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'
'400':
$ref: '#/components/responses/BadRequest'
'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
'400':
$ref: '#/components/responses/BadRequest'
'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
'400':
$ref: '#/components/responses/BadRequest'
'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
'400':
$ref: '#/components/responses/BadRequest'
'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
'400':
$ref: '#/components/responses/BadRequest'
'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'
'400':
$ref: '#/components/responses/BadRequest'
'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'
'400':
$ref: '#/components/responses/BadRequest'
'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'
'400':
$ref: '#/components/responses/BadRequest'
'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'
'400':
$ref: '#/components/responses/BadRequest'
'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'
'400':
$ref: '#/components/responses/BadRequest'
'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'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
default:
$ref: '#/components/responses/Unexpected'
components:
schemas:
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
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'
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
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
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
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
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'
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
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
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
ChatCompletionRequestLLMArgs:
type: object
description: "A map of arguments sent to LLM with query.\n * `temperature` **(type=double, default=0.0)** - A value used to modulate the next token probabilities.\n 0 is the most deterministic and 1 is most creative.\n * `top_k` **(type=integer, default=1)** - A number of highest probability vocabulary tokens to keep for top-k-filtering.\n * `top_p` **(type=double, default=0.0)** - If set to a value < 1, only the smallest set of most probable\n tokens with probabilities that add up to top_p or higher are kept for generation.\n * `seed` **(type=integer, default=0)** - A seed for the random number generator when sampling during\n generation (if temp>0 or top_k>1 or top_p<1), seed=0 picks a random seed.\n * `repetition_penalty` **(type=double, default=1.07)** - A parameter for repetition penalty. 1.0 means no penalty.\n * `max_new_tokens` **(type=double, default=1024)** - A maximum number of new tokens to generate.\n This limit applies to each (map+reduce) step during summarization and each (map) step during extraction.\n * `min_max_new_tokens` **(type=integer, default=512)** - A minimum value for max_new_tokens when auto-adjusting for content of prompt, docs, etc.\n * `response_format` **(type=enum[text, json_object, json_code], default=text)** - An output type of LLM\n * `guided_json` **(type=map)** - If specified, the output will follow the JSON schema.\n * `guided_regex` **(type=string)** - If specified, the output will follow the regex pattern.\n Only for models that support guided generation.\n * `guided_choice` **(type=array[string])** - If specified, the output will be exactly one of the choices.\n Only for models that support guided generation.\n * `guided_grammar` **(type=string)** - If specified, the output will follow the context free grammar.\n Only for models that support guided generation.\n * `guided_whitespace_pattern` **(type=string)** - If specified, will override the default whitespace pattern for guided json decoding.\n Only for models that support guided generation.\n * `enable_vision` **(type=enum[on, off, auto], default=auto)** - Controls vision mode,\n send images to the LLM in addition to text chunks.\n * `visible_vision_models` **(type=array[string], default=[auto])** - Controls which vision model to use when processing images.\n Must provide exactly one model. [auto] for automatic.\n * `images_num_max` **(type=integer, default=None)** - Maximum number of images to process.\n * `json_preserve_system_prompt` **(type=boolean, default=None)** - Whether to preserve system prompt in JSON response.\n * `client_metadata` **(type=string, default=None)** - Additional metadata to send with the request.\n * `min_chars_per_yield` **(type=integer, default=1)** - Minimum characters to yield in streaming response.\n * `reasoning_effort` **(type=integer, default=0)** - Level of reasoning effort for the model (higher values = deeper reasoning, e.g., 10000-65000).\n Use for models that support chain-of-thought reasoning. 0 means no additional reasoning effort.\n * `cost_controls` **(type=map)** A map with cost controls settings:\n * `max_cost` **(type=double)** - Sets the maximum allowed cost in USD per LLM call when doing Automatic model routing.\n If the estimated cost based on input and output token counts is higher than this limit,\n the request will fail as early as possible.\n * `max_cost_per_million_tokens` **(type=double)** - Only consider models that cost less than this value in USD per million tokens\n when doing automatic routing. Using the max of input and output cost.\n * `model` **(type=array[string])** - Optional subset of models to consider when doing automatic routing.\n If not specified, all models are considered.\n * `willingness_to_pay` **(type=double)** - Controls the willingness to pay extra for a more accurate model for every LLM call\n when doing automatic routing, in units of USD per +10% increase in accuracy.\n We start with the least accurate model. For each more accurate model,\n we accept it if the increase in estimated cost divided by the increase in estimated accuracy\n is no more than this value divided by 10%, up to the upper limit specified above.\n Lower values will try to keep the cost as low as possible,\n higher values will approach the cost limit to increase accuracy. 0 means unlimited.\n * `willingness_to_wait` **(type=double)** - Controls the willingness to wait longer for a more accurate model for every LLM call\n when doing automatic routing, in units of seconds per +10% increase in accuracy.\n We start with the least accurate model. For each more accurate model,\n we accept it if the increase in estimated time divided by the increase in estimated accuracy\n is no more than this value divided by 10%. Lower values will try to keep the time\n as low as possible, higher values will take longer to increase accuracy. 0 means unlimited.\n * `use_agent` **(type=boolean, default=False)** - If True, use the AI agent (with access to tools) to generate the response.\n * `agent_accuracy` **(type=string, default=\"standard\")** - Effort level by the agent. Only if use_agent=True. One of [\"quick\", \"basic\", \"standard\", \"maximum\"].\n * `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.\n * `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.\n * `agent_type` **(type=string, default=\"auto\")** - Type of agent to use for task processing.\n * `agent_original_files` **(type=array[string], default=None)** - List of file paths for agent to process.\n * `agent_timeout` **(type=integer, default=None)** - Timeout in seconds for each agent turn.\n * `agent_total_timeout` **(type=integer, default=3600)** - Total timeout in seconds for all agent processing.\n * `agent_code_writer_system_message` **(type=string, default=None)** - System message for agent code writer.\n * `agent_num_executable_code_blocks_limit` **(type=integer, default=1)** - Maximum number of executable code blocks.\n * `agent_system_site_packages` **(type=boolean, default=True)** - Whether agent has access to system site packages.\n * `agent_main_model` **(type=string, default=None)** - Main model to use for agent.\n * `agent_max_stream_length` **(type=integer, default=None)** - Maximum stream length for agent response.\n * `agent_max_memory_usage` **(type=integer, default=16*1024**3)** - Maximum memory usage for agent in bytes (16GB default).\n * `agent_main_reason
# --- truncated at 32 KB (47 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/h2o-ai/refs/heads/main/openapi/h2o-ai-models-api-openapi.yml