openapi: 3.2.0
info:
title: h2oGPTe REST Extractors 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: Extractors
paths:
/extractors/{extractor_id}/permissions:
get:
tags:
- Extractors
summary: Returns a list of users having access to given extractor.
description: The returned list of permissions denotes who has access to the extractor.
operationId: get_extractor_permissions
parameters:
- name: extractor_id
in: path
description: Id of the extractor.
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:
- Extractors
summary: Resets and shares an extractor to a new list of users.
description: Resets and shares an extractor to a new list of users.
operationId: reset_and_share_extractor
parameters:
- name: extractor_id
in: path
description: Id of an extractor.
required: true
schema:
type: string
requestBody:
required: true
description: List of usernames the extractor 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:
- Extractors
summary: Removes sharing of an extractor to all other users except the original owner.
description: Removes sharing of an extractor to all other users except the original owner.
operationId: unshare_extractor_for_all
parameters:
- name: extractor_id
in: path
description: Id of the extractor.
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'
/extractors/{extractor_id}/group_permissions:
get:
tags:
- Extractors
summary: Returns a list of group access permissions for a given extractor.
description: The returned list of group permissions denoting which groups have access to the extractor.
operationId: get_extractor_group_permissions
parameters:
- name: extractor_id
in: path
description: Id of the extractor.
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'
default:
$ref: '#/components/responses/Unexpected'
put:
tags:
- Extractors
summary: Resets and shares an extractor to a new list of groups.
description: Resets and shares an extractor to a new list of groups.
operationId: reset_and_share_extractor_with_groups
parameters:
- name: extractor_id
in: path
description: Id of an extractor
required: true
schema:
type: string
requestBody:
required: true
description: List of group ids the extractor 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'
/extractors/{extractor_id}/is_public:
post:
tags:
- Extractors
summary: Updates a flag specifying whether an extractor is private or public.
description: Updates a flag specifying whether an extractor is private or public.
operationId: update_extractor_privacy
parameters:
- name: extractor_id
in: path
description: Id of the extractor.
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
required:
- is_public
properties:
is_public:
description: A flag specifying whether a extractor 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'
/extractors/{extractor_id}/permissions/{username}:
put:
tags:
- Extractors
summary: Shares an extractor to a user.
description: Shares an extractor to a user.
operationId: share_extractor
parameters:
- name: extractor_id
in: path
description: Id of the extractor.
required: true
schema:
type: string
- name: username
in: path
description: User name that will obtain access to the extractor
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:
- Extractors
summary: Removes sharing of an extractor to a user.
description: Removes sharing of an extractor to a user.
operationId: unshare_extractor
parameters:
- name: extractor_id
in: path
description: Id of the extractor.
required: true
schema:
type: string
- name: username
in: path
description: User name that will lose access to the extractor
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'
/extractors/{extractor_id}/group_permissions/{group_id}:
put:
tags:
- Extractors
summary: Shares an extractor to a group.
description: Shares an extractor to a group. The extractor_id attribute denotes the extractor to be shared.
operationId: share_extractor_with_group
parameters:
- name: extractor_id
in: path
description: Id of the extractor.
required: true
schema:
type: string
- name: group_id
in: path
description: Id of a group that will obtain access to the extractor.
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:
- Extractors
summary: Removes sharing of an extractor from a group.
description: Removes sharing of an extractor from a group.
operationId: unshare_extractor_from_group
parameters:
- name: extractor_id
in: path
description: Id of the extractor.
required: true
schema:
type: string
- name: group_id
in: path
description: Id of a group that will lose access to the extractor.
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'
/extractors/{extractor_id}:
get:
operationId: get_extractor
summary: Fetch an extractor by ID
description: 'This endpoint retrieves information about a specific extractor based on its unique ID. It requires an authenticated user and returns a JSON response containing the extractor''s details.
'
tags:
- Extractors
parameters:
- name: extractor_id
in: path
description: ID of the extractor to get.
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Extractor'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
default:
$ref: '#/components/responses/Unexpected'
delete:
tags:
- Extractors
summary: Deletes extractor.
description: Deletes extractor.
operationId: delete_extractor
parameters:
- name: extractor_id
in: path
description: ID of the extractor to delete.
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'
/extractors:
get:
operationId: list_extractors
summary: List extractors.
description: List extractors. The output is sorted by create time in descending order.
tags:
- Extractors
parameters:
- name: offset
in: query
description: How many extractors to skip before returning.
required: false
schema:
type: integer
default: 0
- name: limit
in: query
description: How many extractors to return.
required: false
schema:
type: integer
default: 100
- name: name_filter
in: query
description: Filter extractors by name.
required: false
schema:
type: string
responses:
'200':
description: Successful operation. Fields llm and schema are not populated.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Extractor'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
default:
$ref: '#/components/responses/Unexpected'
post:
operationId: create_extractor
summary: Creates extractor.
tags:
- Extractors
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ExtractorCreateRequest'
examples:
sample:
summary: Example 1
value:
description: Extracts medical data using Meta Llama 3.1-8B
llm: meta-llama/Meta-Llama-3.1-8B-Instruct
name: Medical data extractor
schema: "{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"title\": \"H2O Field Editor Generated Schema\",\n \"type\": \"object\",\n \"properties\": {\n \"fields\": {\n \"type\": \"object\",\n \"properties\": {\n \"clinic_name\": {\n \"type\": \"string\"\n },\n \"patient_surname\": {\n \"type\": \"string\"\n },\n \"patient_first_name\": {\n \"type\": \"string\"\n }\n }\n }\n },\n \"required\": [\n \"fields\"\n ]\n}\n"
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Extractor'
'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'
/extractors/{extractor_id}/run:
post:
tags:
- Extractors
summary: Run an extractor on a collection, document, or uploaded files (synchronous)
description: 'Executes the specified extractor synchronously and returns results with a 200 OK response.
Exactly one of the following must be provided:
- `collection_id` — run on all documents in a collection
- `document_id` — run on a single document in a collection
- `files` — one or more files uploaded directly in the request body (multipart/form-data) without adding them to a collection
This endpoint blocks and waits for the extraction to complete, then returns the results.
This endpoint is primarily intended for short-running extractions where immediate
results are desired.
For very long running extractions use the async endpoint
`/extractors/{extractor_id}/job` instead.
'
operationId: run_extractor
parameters:
- $ref: '#/components/parameters/ExtractorId'
- $ref: '#/components/parameters/ExtractorCollectionId'
- $ref: '#/components/parameters/ExtractorDocumentId'
- $ref: '#/components/parameters/Timeout'
requestBody:
required: false
content:
multipart/form-data:
schema:
type: object
properties:
files:
type: array
description: 'One or more files to run the extractor on directly, without adding them
to a collection. Mutually exclusive with collection_id and document_id.
'
items:
type: string
format: binary
responses:
'200':
description: 'Extraction completed successfully. Returns an array of extraction results,
one for each document processed.
'
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/DocumentExtractionResult'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
default:
$ref: '#/components/responses/Unexpected'
/extractors/{extractor_id}/job:
post:
tags:
- Extractors
summary: Create a job to run an extractor on a collection or document
description: 'Creates a job to execute the specified extractor by running it on all documents
in a collection, or on a single document when document_id is specified.
This endpoint is designed for long-running extractions.
The endpoint immediately returns a 201 Created response with job details.
Exactly one of collection_id or document_id must be provided.
'
operationId: create_extractor_run_job
parameters:
- $ref: '#/components/parameters/ExtractorId'
- $ref: '#/components/parameters/ExtractorCollectionId'
- $ref: '#/components/parameters/ExtractorDocumentId'
- $ref: '#/components/parameters/Timeout'
responses:
'201':
description: 'Job created successfully. The job has been accepted and is being processed.
Use GET /jobs/{job_id} to check progress. Once completed, retrieve results
using `/extractors/{extractor_id}/results?job_id={job_id}`.
'
content:
application/json:
schema:
$ref: '#/components/schemas/JobDetails'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
default:
$ref: '#/components/responses/Unexpected'
/extractors/{extractor_id}/results:
get:
operationId: list_extractor_results
summary: Retrieve extraction results
description: 'Retrieves extraction results produced by this extractor. If job_id is specified,
returns results for that specific extraction run. If job_id is omitted, returns all
results produced by this extractor across all runs.
'
tags:
- Extractors
parameters:
- name: extractor_id
in: path
description: ID of the extractor
required: true
schema:
type: string
- name: job_id
in: query
description: Optional job ID to retrieve results for a specific extraction run. If omitted, returns all results for this extractor.
required: false
schema:
type: string
- name: offset
in: query
description: How many extraction results to skip before returning.
required: false
schema:
type: integer
default: 0
- name: limit
in: query
description: How many extraction results to return.
required: false
schema:
type: integer
responses:
'200':
description: 'Extraction results retrieved successfully. Returns an array of extraction results.
'
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/DocumentExtractionResult'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
default:
$ref: '#/components/responses/Unexpected'
components:
responses:
Forbidden:
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/EndpointError'
NotFound:
description: Not found
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'
Conflict:
description: Conflict
content:
application/json:
schema:
$ref: '#/components/schemas/EndpointError'
Unexpected:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/EndpointError'
schemas:
GroupSharePermission:
required:
- group_id
type: object
properties:
group_id:
type: string
permissions:
type: array
items:
type: string
JobDetailsStatus:
required:
- id
- status
type: object
properties:
id:
type: string
status:
type: string
ResetAndShareRequest:
required:
- usernames
type: object
properties:
usernames:
type: array
items:
type: string
Extractor:
type: object
required:
- name
- description
- id
- created_at
- is_public
properties:
name:
type: string
description: Human-readable name
description:
type: string
description: What this extractor does
llm:
type: string
description: (Optional) Identifier or version of the language model the extractor uses
schema:
type: string
description: (Optional) JSONSchema (or other spec) that the extractor outputs
prompt:
type: string
description: (Optional) Prompt text for the extractor
pre_prompt_summary:
type: string
description: (Optional) Pre-prompt summary text for the extractor
keep_intermediate_results:
type: boolean
description: (Optional) Flag indicating whether to keep intermediate results during extraction
system_prompt:
type: string
description: (Optional) System prompt text for the extractor
max_num_chunks:
type: integer
description: (Optional) Maximum number of chunks to process
vision:
type: string
description: (Optional) Vision mode setting
vision_llm:
type: string
description: (Optional) Vision LLM model identifier
image_batch_image_prompt:
type: string
description: (Optional) Image batch processing prompt
image_batch_final_prompt:
type: string
description: (Optional) Final prompt for image batch processing
guardrails_settings:
$ref: '#/components/schemas/GuardrailsSettings'
id:
type: string
description: Unique identifier of the extractor
is_public:
type: boolean
description: Flag indicating if the extractor is public
created_at:
type: string
format: date-time
description: When the extractor definition was created
SharePermission:
required:
- username
type: object
properties:
username:
type: string
permissions:
type: array
items:
type: string
ResetAndShareWithGroupsRequest:
required:
- groups
type: object
properties:
groups:
type: array
items:
type: string
GuardrailsSettings:
type: object
properties:
exception_message:
description: A message that will be returned in case some guardrails settings are violated.
type: string
show_violated_responses:
description: Admin-only toggle to view the exact content of violated responses. When enabled, admins can see what triggered a guardrail violation. This is disabled by default for privacy and security. Only administrators can enable this setting and view violated content.
type: boolean
default: false
guardrails_on_transcriptions:
description: When enabled, audio and video transcriptions are checked for content safety violations using the guardrails LLM, in addition to the existing PII detection.
type: boolean
default: false
vision_guardrails_enabled:
description: When enabled, images and video frames are checked for content safety violations using a vision-capable guardrails LLM during document ingestion.
type: boolean
default: false
guardrails_vision_llm:
description: Vision-capable LLM for image and video content safety checks. Defaults to auto which selects the best available vision model.
type: string
default: auto
column_redaction_config:
type: array
description: List of [column_pattern, redaction_label], both strings.
items:
type: array
minItems: 2
maxItems: 2
items:
type: string
disallowed_regex_patterns:
description: A list of regular expressions that match custom PII.
type: array
items:
type: string
example:
- secret_disallowed_word
- (?!0{3})(?!6{3})[0-8]\d{2}-(?!0{2})\d{2}-(?!0{4})\d{4}
presidio_labels_to_flag:
description: A list of entities to be flagged as PII by the built-in Presidio model.
type: array
items:
type: string
example:
- IBAN_CODE
- US_SSN
pii_labels_to_flag:
description: A list of entities to be flagged as PII by the built-in PII model.
type: array
items:
type: string
example:
- IBAN
- SSN
pii_detection_parse_action:
description: What to do when PII is detected during parsing of documents. The 'redact' option will replace disallowed content in the ingested documents with redaction bars.
type: string
enum:
- allow
- redact
- fail
pii_detection_llm_input_action:
description: What to do when PII is detected in the input to the LLM (document content and user prompts). The 'redact' option will replace disallowed content with placeholders.
type: string
enum:
- allow
- redact
- fail
pii_detection_llm_output_action:
description: What to do when PII is detected in the output of the LLM. The 'redact' option will replace disallowed content with placeholders.
type: string
enum:
- allow
- redact
- fail
prompt_guard_labels_to_flag:
description: A list of entities to be flagged as safety violations in user prompts by the built-in prompt guard model.
type: array
items:
type: string
example:
- JAILBREAK
guardrails_labels_to_flag:
description: A list of entities to be flagged as safety violations in user prompts. Must be a subset of guardrails_entities, if provided.
type: array
items:
type: string
example:
- Violent Crimes
- Non-Violent Crimes
- Intellectual Property
- Code Interpreter Abuse
guardrails_llm:
description: LLM to use for Guardrails and PII detection
type: string
example: h2oai/h2o-danube3-4b-chat
guardrails_safe_category:
description: Name of the safe category for guardrails. Must be a key in guardrails_entities, if provided. Otherwise uses system defaults.
type: string
example: Safe
guardrails_entities:
description: Dictionary of entities and their descriptions for the guardrails model to classify. The first entry is the "safe" class, the rest are "unsafe" classes.
type: object
additionalProperties:
type: string
example:
Safe: Messages that do not contain any of the following unsafe content
Violent Crimes: 'Messages that enable, encourage, or endorse the commission of violent crimes, including: (1) unlawful violence toward people (ex: terrorism, genocide, murder, hate-motivated violent crimes, child abuse, assault, battery, kidnapping) and (2) unlawful violence toward animals (ex: animal abuse)'
Non-Violent Crimes: 'Messages that enable, encourage, or endorse the commission of non-violent crimes, including: (1) personal crimes (ex: labor trafficking, threats, intimidation, hate-motivated non-violent crimes), (2) financial crimes (ex: fraud, scams, money laundering), (3) property crimes (ex: theft, arson, vandalism), (4) drug crimes (ex: creating or using regulated substances), (5) weapons crimes (ex: producing unlicensed firearms), and (6) cyber crimes (ex: hacking)'
Defamation: Messages that are both verifiably false and likely to injure a living person’s reputation
Specialized Advice: Messages that contain specialized financial, medical, or legal advice, or that indicate dangerous activities or objects are safe
Intellectual Property: Messages that may violate the intellectual property rights of any third party
Code Interpreter Abuse: Messages that seek to abuse code interpreters, including those that enable denial of service attacks, container escapes or privilege escalation exploits
column_redaction_custom_entities_to_flag:
description: Deprecated - Use custom_pii_entities_to_flag. A list of entities to redact in tabular data files. Must be a subset of column_redaction_custom_entities, if provided.
type: array
items:
type: string
example:
- Mother's Maiden Name
column_redaction_custom_entities:
description: (Optional) Deprecated - Use custom_pii_entities. A dictionary of
# --- truncated at 32 KB (38 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/h2o-ai/refs/heads/main/openapi/h2o-ai-extractors-api-openapi.yml