CollectionSettings

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/h2o-ai/main/json-schema/h2o-ai-collection-settings-schema.json",
  "title": "CollectionSettings",
  "x-generated": "2026-10-03",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/h2o-ai-collections-api-openapi.yml#/components/schemas/CollectionSettings",
  "type": "object",
  "properties": {
    "max_tokens_per_chunk": {
      "description": "Approximate max. number of tokens per chunk for text-dominated document pages. For images, chunks can be larger.",
      "type": "integer"
    },
    "chunk_overlap_tokens": {
      "description": "Approximate number of tokens that are overlapping between successive chunks.",
      "type": "integer"
    },
    "gen_doc_summaries": {
      "description": "Whether to auto-generate document summaries (uses LLM)",
      "type": "boolean",
      "default": false
    },
    "gen_doc_questions": {
      "description": "Whether to auto-generate sample questions for each document (uses LLM)",
      "type": "boolean",
      "default": false
    },
    "audio_input_language": {
      "description": "Language of audio files. Defaults to \"auto\" language detection. Pass empty string to see choices.",
      "type": "string",
      "default": "auto"
    },
    "ocr_model": {
      "description": "Which method to use to extract text from images using AI-enabled optical character recognition (OCR) models. Pass empty string to see choices. docTR is best for Latin text, PaddleOCR is best for certain non-Latin languages, Tesseract covers a wide range of languages. Mississippi works well on handwriting. auto - Automatic will auto-select the best OCR model for every page. off - Disable OCR for speed, but all images will then be skipped (also no image captions will be made).",
      "type": "string",
      "default": "auto"
    },
    "tesseract_lang": {
      "description": "Which language to use when using ocr_model=\"tesseract\". Pass empty string to see choices.",
      "type": "string"
    },
    "keep_tables_as_one_chunk": {
      "description": "When tables are identified by the table parser the table tokens will be kept in a single chunk.",
      "type": "boolean"
    },
    "chunk_by_page": {
      "description": "Each page will be a chunk. `keep_tables_as_one_chunk` will be ignored if this is `true`.",
      "type": "boolean"
    },
    "handwriting_check": {
      "description": "Check pages for handwriting. Will use specialized models if handwriting is found.",
      "type": "boolean"
    },
    "ingest_mode": {
      "description": "Default document ingestion mode for uploads.",
      "type": "string",
      "enum": [
        "standard",
        "lite",
        "agent_only"
      ]
    },
    "follow_links": {
      "description": "Whether to import all web pages linked from this URL will be imported. External links will be ignored. Links to other pages on the same domain will be followed as long as they are at the same level or below the URL you specify. Each page will be transformed into a PDF document.",
      "type": "boolean"
    },
    "max_depth": {
      "description": "Max depth of recursion when following links, only when follow_links is `true`. Max_depth of 0 means don't follow any links, max_depth of 1 means follow only top-level links, etc. Use -1 for automatic (system settings).",
      "type": "integer"
    },
    "max_documents": {
      "description": "Max number of documents when following links, only when follow_links is `true`. Use None for automatic (system defaults). Use -1 for max (system limit).",
      "type": "integer"
    },
    "root_dir": {
      "description": "Root directory for document storage",
      "type": "string"
    },
    "copy_document": {
      "description": "Whether to copy the document when importing an existing document",
      "type": "boolean"
    },
    "guardrails_settings": {
      "$ref": "#/$defs/GuardrailsSettings"
    }
  },
  "$defs": {
    "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"
          }
        },
        "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"
          }
        },
        "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"
          }
        },
        "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"
          }
        },
        "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"
          }
        },
        "guardrails_llm": {
          "description": "LLM to use for Guardrails and PII detection",
          "type": "string"
        },
        "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"
        },
        "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"
          }
        },
        "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"
          }
        },
        "column_redaction_custom_entities": {
          "description": "(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.",
          "type": "object",
          "additionalProperties": {
            "type": "string"
          }
        },
        "custom_pii_entities_to_flag": {
          "description": "A list of entities to redact in tabular data files. Must be a subset of custom_pii_entities, if provided.",
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "custom_pii_entities": {
          "description": "(Optional) A dictionary of entities and a short description for the LLM to check for and redact columns containing PII in tabular data files.",
          "type": "object",
          "additionalProperties": {
            "type": "string"
          }
        }
      }
    }
  }
}