Skip to main content
Version: v1.7.0

h2oGPTe REST API: OpenAPI specification file

Overview​

The h2oGPTe OpenAPI specification file outlines the structure and functionality of the h2oGPTe REST API, including endpoints, request and response formats, and authentication requirements.

What you will learn​

  • How to generate client SDKs (Python, JavaScript, Go) from the spec using the OpenAPI Generator CLI.
  • How to configure authentication and data deletion for REST API integrations.
  • How to use the OpenAI-compatible REST endpoints with existing OpenAI-based clients.
  • How to register and manage custom tools that extend agents with MCP servers, browser actions, or general-purpose code.

Helpful resources​

How we generated the SDKs​

The available SDKs were developed using the OpenAPI Generator CLI, a robust tool designed to create client libraries directly from OpenAPI specifications.

Installation​

pip install openapi-generator-cli==7.10.0

SDK Setup Guide​

Python
You are currently viewing: Python SDK
All code examples and instructions below are for Python

General CLI structure​

openapi-generator-cli generate \
  -i rest_api_spec_h2ogpte.yaml \
  -g python \
  -o sdk \
  --additional-properties=packageName=h2ogpte_rest_client,packageVersion=1.6.2,projectName=h2ogpte-rest-client

Prerequisites​

  1. Create a folder for your Python SDK. Paste the following commands in your terminal:

    mkdir python-sdk
    cd python-sdk

  2. Download the OpenAPI specification file: Download api-spec.yaml and move it to the python-sdk folder.

  3. Set up a Python environment with Python 3.8 or later:

    python3 -m venv venv
    source venv/bin/activate
    pip install openapi-generator-cli==7.10.0

Generate SDK​

In the python-sdk directory, run the following command (CLI) to create the Python SDK using the OpenAPI Generator CLI:

openapi-generator-cli generate \
  -i rest_api_spec_h2ogpte.yaml \
  -g python \
  -o sdk \
  --additional-properties=packageName=h2ogpte_rest_client,packageVersion=1.6.2,projectName=h2ogpte-rest-client
note

The CLI creates a folder named sdk containing the Python SDK.

Install Dependencies​

  1. Navigate to the SDK directory and install dependencies:

    cd sdk
    pip install -r requirements.txt

  2. Install the Python SDK:

    pip install setuptools
    python setup.py install

Test SDK with Collection Creation​

Create a test Collection to verify the Python SDK installation:

create_a_collection.py
# This example with the Python SDK creates a new Collection with the following 
# name and description (while testing whether the Python SDK was properly installed): 
# Name = The name of my Collection
# Description = The description of my Collection
import h2ogpte_rest_client
import os
from h2ogpte_rest_client.rest import ApiException
from pprint import pprint

configuration = h2ogpte_rest_client.Configuration(
    # This line specifies the URL where Enterprise h2oGPTe is hosted. 
    # The address should be the location where the API key was created.
    host="https://h2ogpte.genai.h2o.ai/",
    # This line specifies the API key for authentication.
    access_token=os.environ["BEARER_TOKEN"]
)

with h2ogpte_rest_client.ApiClient(configuration) as api_client:
    api_instance = h2ogpte_rest_client.CollectionsApi(api_client)
    
    collection_create_request = h2ogpte_rest_client.CollectionCreateRequest(
        name="The name of my Collection",
        description="The description of my Collection"
    ) 

    try:
        api_response = api_instance.create_collection(collection_create_request)
        print("The response of CollectionsApi->create_collection:\n")
        pprint(api_response)
    except Exception as e:
        print("Exception when calling CollectionsApi->create_collection: %s\n" % e)

Set up authentication:

Before you can run the Python script, you need to export a global API key within the sdk directory:

export BEARER_TOKEN="sk-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Run the test:

Within the sdk directory, run the following command:

python3 create_a_collection.py

Expected output:

The response of CollectionsApi->create_collection:

Collection(id='091c6ab1-a031-4eb7-9e3e-7d0939911d00', name='The name of my Collection', description='The description of my Collection', embedding_model='BAAI/bge-large-en-v1.5', document_count=0, document_size=0, updated_at=datetime.datetime(2024, 12, 3, 21, 39, 49, 442087, tzinfo=TzInfo(UTC)), user_count=0, is_public=False, username='sergio.perez@h2o.ai', sessions_count=0)

CLI Parameters​

  • -i: The path or URL to the OpenAPI spec (for example, openapi.yaml or https://example.com/openapi.yaml).
  • -g: The target programming language for the client (for example, python, javascript, go).
  • -o: The output directory for the generated files (for example, ./python-client).
  • --additional-properties: Additional settings for client generation (for example, usePromises=true for JavaScript).

For more information about generating SDKs in other languages, visit the OpenAPI Generator CLI documentation.

Authentication​

Global API Key
  • The value exported for the BEARER_TOKEN (Python), accessToken (JavaScript), or Authorization header (Go) should be a global API key.
  • To learn more about what is a global API key and how to create one, see APIs.
  • All URIs are relative to https://h2ogpte.genai.h2o.ai/. The global API key must be created on this platform to ensure successful requests.
  • Make sure to replace sk-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX with your actual API key.

Delete your data​

To see the detailed process for deleting your data, refer to the User data deletion documentation.

OpenAI-compatible REST API​

This API provides OpenAI-style endpoints for chat completions, chat responses, and model listing for integration with OpenAI-based applications.

Endpoints​

POST /openai_api/v1/chat/completions : OpenAI-compatible chat completions endpoint.

POST /openai_api/v1/responses : OpenAI-compatible responses endpoint for new chat interactions.

GET /openai_api/v1/models : Lists available models for use with chat and completions endpoints.

Authentication​

Use the same API key authentication as the main REST API:

Authorization: Bearer sk-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
note

Make sure to replace sk-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX with your actual API key.

Chat completions​

Endpoint: POST /openai_api/v1/chat/completions

note

Supported features: developer, system, user, and assistant message types with text and image content parts are accepted as input for user messages. See OpenAI API reference for complete feature comparison.

API behavior​

The following table shows the key differences from using OpenAI API:

FeatureSupport
Message typesOnly developer, system, user, and assistant messages are supported
Content partsOnly text and image content parts are supported in user messages (audio and file content are not supported)
Agentic featuresTool calls, function calling, and other agentic features are not supported
CollectionsDocument collections are not supported
note

Most unsupported fields are ignored without error.

Request:

{
  "model": "auto",
  "messages": [
    { "role": "user", "content": "What color is the sky?" }
  ],
  "temperature": 0.7,
  "max_tokens": 1024
}

Response:

{
  "choices": [
    {
      "message": { "role": "assistant", "content": "The sky is typically blue during the day." },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 9,
    "completion_tokens": 12,
    "total_tokens": 21
  }
}

Responses​

Endpoint: POST /openai_api/v1/responses

note

Supported features: Only text input is accepted. For a full list of OpenAI API capabilities, see the OpenAI API reference.

API behavior​

The following table shows the key differences from using OpenAI API:

FeatureSupport
Input typesOnly text content is supported in the input parameter (no files, images, or base64 content)
Agentic featuresTool calls, function calling, and other agentic features are not supported
CollectionsDocument collections are not supported
note

Most unsupported fields are ignored without error.

Request:

{
  "model": "auto",
  "input": "What color is the sky?",
  "instructions": "You are a helpful assistant.",
  "temperature": 0.7,
  "stream": false
}

Alternative Request with Chat History:

{
  "model": "auto",
  "input": [
    { "role": "user", "content": "What color is the sky?" },
    { "role": "assistant", "content": "The sky is blue." },
    { "role": "user", "content": "What was the answer, again?" }
  ],
  "stream": true
}

Response:

{
  "id": "resp_abc123",
  "object": "response",
  "created_at": 1677610602,
  "model": "auto",
  "status": "completed",
  "output": [
    {
      "id": "msg_123",
      "role": "assistant",
      "status": "completed",
      "type": "message",
      "content": [
        {
          "type": "output_text",
          "text": "The sky is typically blue during the day.",
          "annotations": []
        }
      ]
    }
  ],
  "error": null
}

List models​

Endpoint: GET /openai_api/v1/models

note

See OpenAI API reference for full OpenAI API capabilities.

Request:

GET /openai_api/v1/models
Authorization: Bearer sk-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Response:

{
  "object": "list",
  "data": [
    {
      "id": "gpt-3.5-turbo",
      "object": "model",
      "created": 1677610602,
      "owned_by": "h2oai",
      "permission": [
        {
          "id": "modelperm-abc123",
          "object": "model_permission",
          "created": 1677610602,
          "allow_create_engine": false,
          "allow_sampling": true,
          "allow_logprobs": false,
          "allow_search_indices": false,
          "allow_view": true,
          "allow_fine_tuning": false,
          "organization": "*",
          "group": null,
          "is_blocking": false
        }
      ],
      "root": "gpt-3.5-turbo",
      "parent": null
    }
    // ... more models may be listed here
  ]
}

Compatibility​

  • OpenAI Python client: Compatible with basic chat completions, responses, and model listing endpoints. You can use the standard OpenAI Python library with these specific endpoints.
  • Cline VSCode extension: Supported with the OpenAI Compatible provider setting.
  • Streaming: Supported via the stream=true parameter (responses are streamed as per OpenAI's API).

Custom Tools API​

Custom tools extend h2oGPTe agents with additional capabilities such as remote MCP servers, local MCP servers, browser automation actions, and general-purpose code execution. Use this API to programmatically register custom tools that agents can invoke during conversations.

Authentication​

Use the same API key authentication as the main REST API. The caller must have the ConfigureAgents permission, or the API returns 401 Unauthorized.

Authorization: Bearer sk-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
note

Make sure to replace sk-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX with your actual API key.

Add a custom agent tool​

Endpoint: POST /api/v1/agents/custom_tools

Create a custom agent tool by uploading tool files and providing configuration. The request uses multipart/form-data encoding.

Parameters​

ParameterTypeRequiredDescription
tool_typestringYesType of custom tool (see values below)
tool_argsJSON stringYesTool-specific arguments (structure varies by tool_type)
filebinaryConditionalTool file to upload. Required for local_mcp, browser_action, and general_code. Optional for remote_mcp.
filenamestringNoOverride filename for the uploaded file

tool_type values:

ValueDescriptionFile requirements
local_mcpModel Context Protocol server running locally.zip file containing MCP server code
remote_mcpModel Context Protocol server running remotelyOptional .json file with MCP configuration
browser_actionCustom browser automation actions.py file (must start with browser_) or .zip
general_codeGeneral-purpose code execution.py or .zip file with custom code

tool_args structure:

For remote_mcp:

{
  "mcp_config_json": "{\"mcpServers\": {\"my-server\": {\"url\": \"https://example.com/mcp\"}}}",
  "enable_by_default": true
}
tip

To control which agent roles can use a remote MCP tool, include "tool_usage_mode" inside the mcp_config_json string (at the top level, alongside "mcpServers").

For local_mcp:

{
  "tool_name": "my_mcp_server",
  "description": "A local MCP server for data retrieval",
  "enable_by_default": true,
  "tool_usage_mode": ["runner", "creator"]
}

For browser_action:

{
  "tool_name": "browser_scraper",
  "description": "Scrape structured data from web pages",
  "enable_by_default": true,
  "tool_usage_mode": ["runner", "creator"]
}

For general_code:

{
  "tool_name": "my_tool",
  "description": "My custom tool",
  "enable_by_default": true,
  "should_unzip": false,
  "tool_usage_mode": ["runner", "creator"]
}
FieldTypeRequiredDescription
mcp_config_jsonstringYes (remote_mcp only)JSON-encoded string with MCP server configuration
tool_namestringNoDefaults to filename without extension
descriptionstringNoTool description
enable_by_defaultbooleanNoWhether the tool is enabled by default. Defaults to true
should_unzipbooleanNoFor general_code .zip files only
tool_usage_modestring[]NoAgent roles that can use this tool. Applies to local_mcp, browser_action, and general_code as a top-level field. For remote_mcp, include inside mcp_config_json. Defaults to ["runner", "creator"]

Python SDK example​

from h2ogpte import H2OGPTE

client = H2OGPTE(address="https://h2ogpte.genai.h2o.ai", api_key="sk-XXXXX...")

# Add a remote MCP tool
tool_ids = client.add_custom_agent_tool(
    tool_type="remote_mcp",
    tool_args={
        "mcp_config_json": '{"mcpServers": {"my-server": {"url": "https://example.com/mcp"}}}',
        "enable_by_default": True,
    },
)

# Add a general code tool with file upload
tool_ids = client.add_custom_agent_tool(
    tool_type="general_code",
    tool_args={
        "tool_name": "my_tool",
        "description": "A custom code tool",
        "enable_by_default": True,
    },
    custom_tool_path="/path/to/my_tool.py",
)

cURL example​

# Add a remote MCP tool
curl -X POST "https://h2ogpte.genai.h2o.ai/api/v1/agents/custom_tools" \
  -H "Authorization: Bearer sk-XXXXX..." \
  -F "tool_type=remote_mcp" \
  -F 'tool_args={"mcp_config_json": "{\"mcpServers\": {\"my-server\": {\"url\": \"https://example.com/mcp\"}}}", "enable_by_default": true}'

# Add a general code tool with file upload
curl -X POST "https://h2ogpte.genai.h2o.ai/api/v1/agents/custom_tools" \
  -H "Authorization: Bearer sk-XXXXX..." \
  -F "tool_type=general_code" \
  -F 'tool_args={"tool_name": "my_tool", "description": "A custom code tool", "enable_by_default": true}' \
  -F "file=@/path/to/my_tool.py" \
  -F "filename=my_tool.py"

Response​

Success — 201 Created

Returns a JSON array of created tool objects:

[
  {
    "agent_custom_tool_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
]
note

For remote_mcp tools with multiple servers defined in mcpServers, the response contains one entry per server.

Error responses

StatusMessageCause
400"Failed to parse form data."Request body is not valid multipart/form-data
400"tool_type is required."Missing tool_type form field
400"Invalid JSON format for tool_args."tool_args is not valid JSON
400"The request does not contain a file."File is required but not provided (applies to local_mcp, browser_action, general_code)
401"Unauthorized"Missing or invalid API key, or the user lacks ConfigureAgents permission
415"Invalid file extension: {ext}. Allowed extensions are .zip."Wrong file type for local_mcp
415"Invalid file extension: {ext}. Allowed extensions are .zip, .py."Wrong file type for browser_action or general_code
415"Invalid file extension: {ext}. For remote_mcp, allowed extensions are .json."Wrong file type for remote_mcp
413"File is too large, maximum size is 20MB"Uploaded file exceeds the 20 MB size limit

Error response body format:

{
  "code": 400,
  "message": "tool_type is required."
}

Other custom tool operations​

In addition to creating tools, you can list, update, and delete custom tools that belong to the current user.

List custom tools​

Endpoint: GET /api/v1/agents/custom_tools

Returns a JSON array of custom tool objects for the authenticated user.

Example response:

[
  {
    "id": "uuid-string",
    "tool_name": "my_tool",
    "tool_type": "general_code",
    "tool_args": {
      "tool_name": "my_tool",
      "description": "A custom code tool",
      "enable_by_default": true,
      "tool_usage_mode": ["runner", "creator"]
    },
    "owner_email": "user@example.com"
  }
]

Update a custom tool​

Endpoint: PUT /api/v1/agents/custom_tools/{tool_id}

Update the configuration (tool_args) of an existing tool.

Path parameter

NameTypeRequiredDescription
tool_idstringYesID of the custom tool to update (per user)

Request body

application/json with the fields you want to change inside tool_args. For example:

{
  "tool_args": {
    "enable_by_default": false,
    "tool_usage_mode": ["runner"]
  }
}

Response

  • 200 OK with { "agent_custom_tool_id": "<tool-id>" } if the tool was updated.
  • 400 Bad Request with "tool_args is required for update." if tool_args is missing.
  • 404 Not Found with "Custom agent tool not found or no changes made." if the tool does not exist or no changes were applied.

Delete custom tools​

Endpoint: DELETE /api/v1/agents/custom_tools/{tool_ids}

Delete one or more custom tools for the authenticated user.

Path parameter

NameTypeRequiredDescription
tool_idsstring[]YesOne or more tool IDs to be deleted

Pass multiple IDs as a comma-separated list in the path, for example:

/api/v1/agents/custom_tools/id1,id2,id3

Response

  • 200 OK with a JSON Count indicating how many tools were deleted, for example:
{"count": 2}
Feedback