---
title: "Creates extractor."
method: POST
path: "/extractors"
tags: ["Extractors"]
---

# Creates extractor.

`POST /extractors`

## Request

- Base URL: `https://h2ogpte.genai.h2o.ai/api/v1`
- URL: `https://h2ogpte.genai.h2o.ai/api/v1/extractors`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/h2o/apis/h2ogpte-rest-api/docs/extractors/post.ts> (a function with typed inputs; its response is checked against the schema)

## Request body

- ExtractorCreateRequest
  - `name` string, required: Human-readable name
  - `description` string, required: What this extractor does
  - `llm` string, required: Identifier or version of the language model the extractor uses
  - `schema` string, required: JSONSchema that the extractor outputs, serialized as a string. Must be empty or a JSON object; a string, array or other non-object value is rejected with 400. When schema is not empty, the output is always returned as a JSON object. When schema is empty the extractor is unconstrained and its results are returned as free-form text rather than an object.
  - `prompt` string: Custom prompt text for the extractor. If empty, default prompt will be used. If combined with schema, prompt can customize the output, but cannot change its format as it will always be JSON object.
  - `pre_prompt_summary` string: (Optional) Pre-prompt summary text for the extractor
  - `keep_intermediate_results` boolean: (Optional) Flag indicating whether to keep intermediate results during extraction
  - `system_prompt` string: (Optional) System prompt text for the extractor
  - `max_num_chunks` integer: (Optional) Maximum number of chunks to process
  - `vision` string: (Optional) Vision mode setting
  - `vision_llm` string: (Optional) Vision LLM model identifier
  - `image_batch_image_prompt` string: (Optional) Image batch processing prompt
  - `image_batch_final_prompt` string: (Optional) Final prompt for image batch processing
  - `guardrails_settings` GuardrailsSettings
    - `exception_message` string: A message that will be returned in case some guardrails settings are violated.
    - `show_violated_responses` boolean: 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.
    - `guardrails_on_transcriptions` boolean: When enabled, audio and video transcriptions are checked for content safety violations using the guardrails LLM, in addition to the existing PII detection.
    - `vision_guardrails_enabled` boolean: When enabled, images and video frames are checked for content safety violations using a vision-capable guardrails LLM during document ingestion.
    - `guardrails_vision_llm` string: Vision-capable LLM for image and video content safety checks. Defaults to auto which selects the best available vision model.
    - `column_redaction_config` array[]: List of [column_pattern, redaction_label], both strings.
      - string[]
    - `disallowed_regex_patterns` string[]: A list of regular expressions that match custom PII.
    - `presidio_labels_to_flag` string[]: A list of entities to be flagged as PII by the built-in Presidio model.
    - `pii_labels_to_flag` string[]: A list of entities to be flagged as PII by the built-in PII model.
    - `pii_detection_parse_action` 'allow' | 'redact' | 'fail': 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.
    - `pii_detection_llm_input_action` 'allow' | 'redact' | 'fail': 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.
    - `pii_detection_llm_output_action` 'allow' | 'redact' | 'fail': What to do when PII is detected in the output of the LLM. The 'redact' option will replace disallowed content with placeholders.
    - `prompt_guard_labels_to_flag` string[]: A list of entities to be flagged as safety violations in user prompts by the built-in prompt guard model.
    - `guardrails_labels_to_flag` string[]: A list of entities to be flagged as safety violations in user prompts. Must be a subset of guardrails_entities, if provided.
    - `guardrails_llm` string: LLM to use for Guardrails and PII detection
    - `guardrails_safe_category` string: Name of the safe category for guardrails. Must be a key in guardrails_entities, if provided. Otherwise uses system defaults.
    - `guardrails_entities` object: (Optional) Dictionary mapping each guardrails category name to its definition, used by the guardrails model to classify messages. The first entry is the "safe" class; the rest are "unsafe" classes. Omit this field to inherit the server's maintained default category definitions and keep receiving improvements to them. Supplying it REPLACES the defaults wholesale (the dict is not merged with them), so a value copied from documentation pins the collection to those exact definitions permanently — including wordings later found too weak to classify reliably. Pass it only when you deliberately own the full category set. No example is shown here on purpose, to avoid inviting such a copy.
    - `column_redaction_custom_entities_to_flag` string[]: 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.
    - `column_redaction_custom_entities` object: (Optional) Deprecated - Use custom_pii_entities. A dictionary of entities and a short description for the LLM to check for and redact columns containing PII in tabular data files.
    - `custom_pii_entities_to_flag` string[]: A list of entities to redact in tabular data files. Must be a subset of custom_pii_entities, if provided.
    - `custom_pii_entities` object: (Optional) A dictionary of entities and a short description for the LLM to check for and redact columns containing PII in tabular data files.

## Response `200`

OK

- Extractor
  - `name` string, required: Human-readable name
  - `description` string, required: What this extractor does
  - `llm` string: (Optional) Identifier or version of the language model the extractor uses
  - `schema` string: (Optional) JSONSchema (or other spec) that the extractor outputs
  - `prompt` string: (Optional) Prompt text for the extractor
  - `pre_prompt_summary` string: (Optional) Pre-prompt summary text for the extractor
  - `keep_intermediate_results` boolean: (Optional) Flag indicating whether to keep intermediate results during extraction
  - `system_prompt` string: (Optional) System prompt text for the extractor
  - `max_num_chunks` integer: (Optional) Maximum number of chunks to process
  - `vision` string: (Optional) Vision mode setting
  - `vision_llm` string: (Optional) Vision LLM model identifier
  - `image_batch_image_prompt` string: (Optional) Image batch processing prompt
  - `image_batch_final_prompt` string: (Optional) Final prompt for image batch processing
  - `guardrails_settings` GuardrailsSettings
    - `exception_message` string: A message that will be returned in case some guardrails settings are violated.
    - `show_violated_responses` boolean: 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.
    - `guardrails_on_transcriptions` boolean: When enabled, audio and video transcriptions are checked for content safety violations using the guardrails LLM, in addition to the existing PII detection.
    - `vision_guardrails_enabled` boolean: When enabled, images and video frames are checked for content safety violations using a vision-capable guardrails LLM during document ingestion.
    - `guardrails_vision_llm` string: Vision-capable LLM for image and video content safety checks. Defaults to auto which selects the best available vision model.
    - `column_redaction_config` array[]: List of [column_pattern, redaction_label], both strings.
      - string[]
    - `disallowed_regex_patterns` string[]: A list of regular expressions that match custom PII.
    - `presidio_labels_to_flag` string[]: A list of entities to be flagged as PII by the built-in Presidio model.
    - `pii_labels_to_flag` string[]: A list of entities to be flagged as PII by the built-in PII model.
    - `pii_detection_parse_action` 'allow' | 'redact' | 'fail': 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.
    - `pii_detection_llm_input_action` 'allow' | 'redact' | 'fail': 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.
    - `pii_detection_llm_output_action` 'allow' | 'redact' | 'fail': What to do when PII is detected in the output of the LLM. The 'redact' option will replace disallowed content with placeholders.
    - `prompt_guard_labels_to_flag` string[]: A list of entities to be flagged as safety violations in user prompts by the built-in prompt guard model.
    - `guardrails_labels_to_flag` string[]: A list of entities to be flagged as safety violations in user prompts. Must be a subset of guardrails_entities, if provided.
    - `guardrails_llm` string: LLM to use for Guardrails and PII detection
    - `guardrails_safe_category` string: Name of the safe category for guardrails. Must be a key in guardrails_entities, if provided. Otherwise uses system defaults.
    - `guardrails_entities` object: (Optional) Dictionary mapping each guardrails category name to its definition, used by the guardrails model to classify messages. The first entry is the "safe" class; the rest are "unsafe" classes. Omit this field to inherit the server's maintained default category definitions and keep receiving improvements to them. Supplying it REPLACES the defaults wholesale (the dict is not merged with them), so a value copied from documentation pins the collection to those exact definitions permanently — including wordings later found too weak to classify reliably. Pass it only when you deliberately own the full category set. No example is shown here on purpose, to avoid inviting such a copy.
    - `column_redaction_custom_entities_to_flag` string[]: 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.
    - `column_redaction_custom_entities` object: (Optional) Deprecated - Use custom_pii_entities. A dictionary of entities and a short description for the LLM to check for and redact columns containing PII in tabular data files.
    - `custom_pii_entities_to_flag` string[]: A list of entities to redact in tabular data files. Must be a subset of custom_pii_entities, if provided.
    - `custom_pii_entities` object: (Optional) A dictionary of entities and a short description for the LLM to check for and redact columns containing PII in tabular data files.
  - `id` string, required: Unique identifier of the extractor
  - `is_public` boolean, required: Flag indicating if the extractor is public
  - `created_at` string, date-time, required: When the extractor definition was created

## Other responses

- `400`: Bad request
- `401`: Unauthorized - Invalid or missing API key
- `403`: Forbidden
- `404`: Not found
- `default`: Unexpected error

---

[API](https://skmtc.dev/h2o/apis/h2ogpte-rest-api.md) - [All operations](https://skmtc.dev/h2o/apis/h2ogpte-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/h2o/apis/h2ogpte-rest-api/revisions/a82a117320f4?raw)