CollectionCreateRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/h2o-ai/main/json-schema/h2o-ai-collection-create-request-schema.json",
  "title": "CollectionCreateRequest",
  "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/CollectionCreateRequest",
  "required": [
    "name",
    "description"
  ],
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "description": {
      "type": "string"
    },
    "embedding_model": {
      "type": "string"
    },
    "collection_settings": {
      "$ref": "#/$defs/CollectionSettings"
    },
    "chat_settings": {
      "$ref": "#/$defs/ChatSettings"
    },
    "expiry_date": {
      "type": "string",
      "format": "date-time",
      "description": "Optional expiration date for the collection"
    },
    "workspace": {
      "type": "string"
    },
    "vex_encryption": {
      "type": "string",
      "enum": [
        "enabled",
        "disabled"
      ],
      "description": "Per-collection vector encryption choice, honored at create time only:\n  * `enabled` — store vectors encrypted (server must have a vector\n    encryption provider configured; the collection cannot later be\n    opened on a server with no provider).\n  * `disabled` — store vectors as plaintext, even if the server has\n    encryption enabled by default.\n  * omitted — fall back to the server-level default\n    (`H2OGPTE_VEX_ENCRYPTION_ENABLED`).\nSticky once any data is written: existing collections cannot switch modes after the first write.\n"
    }
  },
  "$defs": {
    "ChatCompletionRAGConfig": {
      "type": "object",
      "description": "A map with arguments to control RAG (retrieval-augmented-generation) types.:\n  * `rag_type` **(type=enum[auto, llm_only, rag, hyde1, hyde2, rag+, all_data])** RAG type options:\n    * `auto` - Automatically select the best rag_type.\n    * `llm_only` LLM Only - Answer the query without any supporting document contexts.\n       Requires 1 LLM call.\n    * `rag` RAG (Retrieval Augmented Generation) - Use supporting document contexts\n       to answer the query. Requires 1 LLM call.\n    * `hyde1` LLM Only + RAG composite - HyDE RAG (Hypothetical Document Embedding).\n       Use 'LLM Only' response to find relevant contexts from a collection for generating\n       a response. Requires 2 LLM calls.\n    * `hyde2` HyDE + RAG composite - Use the 'HyDE RAG' response to find relevant\n       contexts from a collection for generating a response. Requires 3 LLM calls.\n    * `rag+` Summary RAG - Like RAG, but uses more context and recursive\n       summarization to overcome LLM context limits. Keeps all retrieved chunks, puts\n       them in order, adds neighboring chunks, then uses the summary API to get the\n       answer. Can require several LLM calls.\n    * `all_data` All Data RAG - Like Summary RAG, but includes all document\n       chunks. Uses recursive summarization to overcome LLM context limits.\n       Can require several LLM calls.\n  * `hyde_no_rag_llm_prompt_extension` **(type=string, example=\\\\\\\\nKeep the answer brief, and list the 5 most relevant key words at the end.)** -\n    Add this prompt to every user's prompt, when generating answers to be used for subsequent retrieval during HyDE.\n    Only used when rag_type is `hyde1` or `hyde2`.\n  * `num_neighbor_chunks_to_include` **(type=integer, default=1)** - A number of neighboring chunks to include \n    for every retrieved relevant chunk. It helps to keep surrounding context together. Only enabled for rag_type `rag+`.\n  * `meta_data_to_include` **(type=map)** - A map with flags that indicate whether each piece of document metadata \n    is to be included as part of the context for a chat with a collection.\n    * `name` **(type: boolean, default=True)**\n    * `text` **(type: boolean, default=True)**\n    * `page` **(type: boolean, default=True)**\n    * `captions` **(type: boolean, default=True)**\n    * `uri` **(type: boolean, default=False)**\n    * `connector` **(type: boolean, default=False)**\n    * `original_mtime` **(type: boolean, default=False)**\n    * `age` **(type: boolean, default=False)**\n    * `score` **(type: boolean, default=False)**\n  * `rag_max_chunks` **(type=integer, default=-1)** - Maximum number of document chunks to retrieve for RAG.\n    Actual number depends on rag_type and admin configuration. Set to >0 values to enable. \n    Can be combined with rag_min_chunk_score.\n  * `rag_min_chunk_score` **(type=double, default=0.0)** - Minimum score of document chunks to retrieve for RAG.\n    Set to >0 values to enable. Can be combined with rag_max_chunks.\n  * `graph_rag_auto_select` **(type=boolean, default=true)** - When `rag_type` is `auto` and the collection has\n    a successfully built knowledge graph, auto-select `graph_rag` as the rag_type for the chat. Set to `false`\n    to keep auto on normal RAG even when a graph exists, e.g. when an admin wants to retain control over when\n    graph mode becomes the default.\n"
    },
    "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_reasoning_effort` **(type=integer, default=None)** - Effort level for main reasoning.\n  * `agent_advanced_reasoning_effort` **(type=integer, default=None)** - Effort level for advanced reasoning.\n  * `agent_max_confidence_level` **(type=integer, default=None)** - Maximum confidence level for agent responses.\n  * `agent_planning_forced_mode` **(type=boolean, default=None)** - Whether to force planning mode for agent.\n  * `agent_too_soon_forced_mode` **(type=boolean, default=None)** - Whether to force \"too soon\" mode for agent.\n  * `agent_critique_forced_mode` **(type=integer, default=None)** - Whether to force critique mode for agent.\n  * `agent_query_understanding_parallel_calls` **(type=integer, default=None)** - Number of parallel calls for query understanding.\n  * `task_tracking` **(type=boolean, default=None)** - Enable task tracking for agent.\n  * `task_update_steps` **(type=integer, default=None)** - Number of steps for task update tracking (0-5, None for auto).\n  * `tool_building_mode` **(type=string, default=None)** - Mode for tool building configuration.\n  * `agent_stream_files` **(type=boolean, default=True)** - Whether to stream files from agent.\n  * `final_answer_guidelines_mode` **(type=string, default=\"auto\")** - Mode for formatting agent final answers. Only applies when use_agent=True. Options: \"auto\" (chooses detailed, may later adapt), \"detailed\" (full final answer guidelines), \"detailed_no_file_links\", \"detailed_no_image_links\", \"detailed_no_links\", \"file_template\" (use custom template), \"raw_LLM\" (bypass final answer guidelines). Available modes may vary by deployment.\n",
      "additionalProperties": true
    },
    "ChatCompletionSelfReflectionConfig": {
      "type": "object",
      "description": "A map with self reflection settings:\n  * `llm_reflection` **(type=string, example=gpt-4-0613)**\n  * `prompt_reflection` **(type=string, example=\\\"\\\"\\\"Prompt:\\\\\\\\n%s\\\\\\\\n\\\"\\\"\\\"\\\\\\\\n\\\\\\\\n\\\"\\\"\\\")**\n  * `system_prompt_reflection` **(type=string)**\n  * `llm_args_reflection` **(type=string, example={})**\n",
      "additionalProperties": true
    },
    "ChatSettings": {
      "type": "object",
      "properties": {
        "llm": {
          "type": "string",
          "description": "LLM name to send the query. Use \"auto\" for automatic model routing, set cost_controls of llm_args for detailed control over automatic routing."
        },
        "llm_args": {
          "$ref": "#/$defs/ChatCompletionRequestLLMArgs"
        },
        "self_reflection_config": {
          "$ref": "#/$defs/ChatCompletionSelfReflectionConfig"
        },
        "rag_config": {
          "$ref": "#/$defs/ChatCompletionRAGConfig"
        },
        "include_chat_history": {
          "type": "string",
          "enum": [
            "on",
            "off",
            "auto"
          ],
          "description": "Whether to include chat history. Includes previous questions and answers for the current chat session for each new chat request. Disable if require deterministic answers for a given question."
        },
        "tags": {
          "oneOf": [
            {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            {
              "$ref": "#/$defs/TagFilter"
            }
          ],
          "description": "Filter documents by tags for RAG context. Supports two formats:\n  - Array format (backward compatible): [\"red\", \"blue\"] includes documents with 'red' OR 'blue' tags\n  - Object format (with exclusions): {\"include\": [\"color\"], \"exclude\": [\"red\", \"blue\"]}\n"
        }
      }
    },
    "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"
        }
      }
    },
    "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"
          }
        }
      }
    },
    "TagFilter": {
      "type": "object",
      "description": "Filter for document tags supporting inclusion and exclusion.\n\nNote: The exclude list takes priority over the include list. If a document has a tag\nthat appears in both lists, the document will be excluded.\n\nExamples:\n  - Include only documents with 'red' OR 'blue' tags: {\"include\": [\"red\", \"blue\"]}\n  - Exclude documents with 'red' OR 'blue' tags: {\"exclude\": [\"red\", \"blue\"]}\n  - Include documents with 'color' tag BUT exclude 'red' and 'blue': {\"include\": [\"color\"], \"exclude\": [\"red\", \"blue\"]}\n",
      "properties": {
        "include": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Include documents with ANY of these tags (OR operation)."
        },
        "exclude": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Exclude documents with ANY of these tags (OR operation). Takes priority over include."
        }
      }
    }
  }
}