H2h2o
Collections

Create a Collection

A Collection refers to a group of related Documents. A Collection lets a user aggregate documents in one location. A user can utilize Collections to group particular sets of material (documents) to explore individually through Chats utilizing a large language model (LLM).

post/collections

Request

Request body

namestring required
descriptionstring required
embedding_modelstring
expiry_datestring date-time

Optional expiration date for the collection

workspacestring
vex_encryption'enabled' | 'disabled'

Per-collection vector encryption choice, honored at create time only:

  • enabled — store vectors encrypted (server must have a vector encryption provider configured; the collection cannot later be opened on a server with no provider).
  • disabled — store vectors as plaintext, even if the server has encryption enabled by default.
  • omitted — fall back to the server-level default (H2OGPTE_VEX_ENCRYPTION_ENABLED). Sticky once any data is written: existing collections cannot switch modes after the first write.

Example request

{
  "name": "My sci-fi library",
  "description": "Collection of my favourite sci-fi books",
  "embedding_model": "BAAI/bge-large-en-v1.5",
  "collection_settings": {
    "max_tokens_per_chunk": 320,
    "guardrails_settings": {
      "disallowed_regex_patterns": [
        "secret_disallowed_word",
        "(?!0{3})(?!6{3})[0-8]\\d{2}-(?!0{2})\\d{2}-(?!0{4})\\d{4}"
      ],
      "presidio_labels_to_flag": [
        "IBAN_CODE",
        "US_SSN"
      ],
      "pii_labels_to_flag": [
        "IBAN",
        "SSN"
      ],
      "prompt_guard_labels_to_flag": [
        "JAILBREAK"
      ],
      "guardrails_labels_to_flag": [
        "Violent Crimes",
        "Non-Violent Crimes",
        "Intellectual Property",
        "Code Interpreter Abuse"
      ],
      "guardrails_llm": "h2oai/h2o-danube3-4b-chat",
      "guardrails_safe_category": "Safe",
      "column_redaction_custom_entities_to_flag": [
        "Mother's Maiden Name"
      ],
      "column_redaction_custom_entities": {
        "Mother's Maiden Name": "Mother's maiden name"
      },
      "custom_pii_entities_to_flag": [
        "Mother's Maiden Name"
      ],
      "custom_pii_entities": {
        "Mother's Maiden Name": "Mother's maiden name"
      }
    }
  },
  "expiry_date": "2024-12-31 23:59:59+00:00",
  "vex_encryption": "enabled"
}

Response

Successful operation

idstring required

A unique identifier of the collection

namestring required

Name of the collection

descriptionstring required

Description of the collection

description_auto_generatedboolean

Whether the collection description was generated by the system.

description_generated_atstring date-time

Time when the auto-generated description was last generated.

description_dirty_atstring date-time

Time when document changes made the auto-generated description stale.

description_generation_started_atstring date-time

Time when description regeneration last started.

embedding_modelstring required
document_countinteger required

A number of documents in the collection

document_sizeinteger required

Total size in bytes of all documents in the collection

created_atstring date-time required

Time when the collection was created

updated_atstring date-time required

Last time when the collection was modified

user_countinteger required

A number of users having access to the collection

is_publicboolean required

Is publicly accessible

usernamestring required

Name of the user owning the collection

sessions_countinteger required

A number of chat sessions with the collection

statusstring required

Status of the collection

prompt_template_idstring

A unique identifier of a prompt template associated with the collection.

thumbnailstring

A file name of a thumbnail image.

size_limitinteger

Maximum size of data that could be contained in the collection.

expiry_datestring date-time

An expiry date

inactivity_intervalinteger

The inactivity interval as an integer number of days.

rag_type'auto' | 'llm_only' | 'rag' | 'hyde1' | 'hyde2' | 'rag+' | 'all_data'

RAG type options:

  • auto - Automatically select the best rag_type.
  • llm_only LLM Only - Answer the query without any supporting document contexts. Requires 1 LLM call.
  • rag RAG (Retrieval Augmented Generation) - Use supporting document contexts to answer the query. Requires 1 LLM call.
  • hyde1 LLM Only + RAG composite - HyDE RAG (Hypothetical Document Embedding). Use 'LLM Only' response to find relevant contexts from a collection for generating a response. Requires 2 LLM calls.
  • hyde2 HyDE + RAG composite - Use the 'HyDE RAG' response to find relevant contexts from a collection for generating a response. Requires 3 LLM calls.
  • rag+ Summary RAG - Like RAG, but uses more context and recursive summarization to overcome LLM context limits. Keeps all retrieved chunks, puts them in order, adds neighboring chunks, then uses the summary API to get the answer. Can require several LLM calls.
  • all_data All Data RAG - Like Summary RAG, but includes all document chunks. Uses recursive summarization to overcome LLM context limits. Can require several LLM calls.
metadata_dictMetadata
workspacestring

The workspace associated with the collection.

has_default_guardrailsboolean

Whether this collection was created with default guardrails enabled.

vex_encryption'enabled' | 'disabled' | 'null' nullable

The per-collection vector encryption choice that was set at creation: enabled, disabled, or null when the collection follows the server default. Read-only — cannot be changed after creation.

exempt_from_chat_expiryboolean

Whether chat sessions in this collection are exempt from auto-expiry

Example response

{
  "id": "123e4567-e89b-12d3-a456-426655440000",
  "name": "My sci-fi library",
  "description": "Collection of my favourite sci-fi books",
  "embedding_model": "BAAI/bge-large-en-v1.5",
  "prompt_template_id": "4e400991-c459-455f-995c-dc6f55ffdb90"
}

Changes

No recorded changes to this operation across all 1 revision of this API.