hot.dev/xai / ::xai::collections

Values

MANAGEMENT_BASE_URL

MANAGEMENT_BASE_URL: Str "https://management-api.x.ai"

Functions

add-document

fn (collection-id: Str, file-id: Str): Document | HttpError
fn (collection-id: Str, file-id: Str, fields: Map): Document | HttpError

Add an existing file to a collection. The file must first be uploaded via the Files API.

Optionally pass metadata fields as a third argument.

Example

// First upload file via ::xai::files/upload, then add to collection
doc add-document("col_abc123", "file_xyz789")
doc.id // => "doc_..."

// With metadata fields
doc add-document("col_abc123", "file_xyz789", {category: "report", year: "2024"})

create

fn (request: CreateCollectionRequest): Collection | HttpError

Create a new collection for document storage and search.

Requires a Management API Key with "AddFileToCollection" permission.

Example

collection create(CreateCollectionRequest({
    name: "My Documents",
    description: "Research papers and notes"
}))

collection.id // => "collection_abc123..."
collection.name // => "My Documents"

delete

fn (collection-id: Str): Map | HttpError

Delete a collection and all its associated documents.

Example

delete("collection_abc123")

get

fn (collection-id: Str): Collection | HttpError

Get a collection by ID.

Example

collection get("collection_abc123")
collection.name // => "My Documents"
collection.file_count // => 42

keyword-search

fn (query: Str, collection-ids: Vec): SearchResponse | HttpError

Keyword search - exact word/phrase matching.

Best for finding specific terms, numbers, or exact phrases in documents.

Example

results keyword-search("Q3 2024 revenue", ["col_abc123"])
results.results // => [{content: "...", score: 0.88, ...}, ...]

list

fn (): CollectionListResponse | HttpError

List all collections accessible with the Management API Key.

Returns a CollectionListResponse containing a Vec of Collection objects.

Example

result list()
result.collections // => [{id: "col_abc", name: "My Docs", ...}, ...]

names map(result.collections, %.name)

management-request

fn (method: Str, url: Str, additional-headers: Map, body: Any): ::hot::http/HttpResponse
fn (method: Str, url: Str): ::hot::http/HttpResponse

Make an HTTP request with Management API Key. Required for Collections API.

remove-document

fn (collection-id: Str, file-id: Str): Map | HttpError

Remove a document from a collection by collection ID and file ID.

Example

remove-document("col_abc123", "file_xyz789")

search

fn (request: SearchRequest): SearchResponse | HttpError

Search documents across one or more collections using semantic, keyword, or hybrid search.

Uses the regular API key (not the Management API Key).

Search Modes:

• hybrid (default) - Combines keyword and semantic for best results
• keyword - Exact matches of words, phrases, numbers
• semantic - Understands meaning and context

Example

results search(SearchRequest({
    query: "What were the key revenue drivers?",
    collection_ids: ["col_abc123"],
    max_results: 10,
    retrieval_mode: MODE_SEMANTIC
}))

first-result first(results.results)
first-result.score // => 0.95
first-result.file_name // => "annual_report.pdf"
first-result.content // => "The key revenue drivers were..."

search-simple

fn (query: Str, collection-ids: Vec): SearchResponse | HttpError

Simple search - query across collections using default hybrid retrieval.

A convenience wrapper around search() that takes just a query string and collection IDs.

Example

results search-simple("revenue analysis", ["col_abc123"])
results.results // => [{content: "...", score: 0.92, ...}, ...]

semantic-search

fn (query: Str, collection-ids: Vec): SearchResponse | HttpError

Semantic search - finds conceptually related content by meaning.

Understands context and returns results that are conceptually similar, even if they don't contain the exact query terms.

Example

results semantic-search("financial performance", ["col_abc123"])
results.results // => [{content: "...", score: 0.91, ...}, ...]

update

fn (collection-id: Str, request: UpdateCollectionRequest): Collection | HttpError

Update a collection's name or description.

Example

collection update("collection_abc123", UpdateCollectionRequest({
    name: "Updated Name",
    description: "New description"
}))
collection.name // => "Updated Name"

Types

Collection

Collection type {
    id: Str,
    name: Str,
    description: Str?,
    created_at: Str?,
    updated_at: Str?,
    file_count: Int?,
    metadata_fields: Vec?
}

CollectionListResponse

CollectionListResponse type {
    collections: Vec
}

CreateCollectionRequest

CreateCollectionRequest type {
    name: Str,
    description: Str?,
    metadata_fields: Vec?
}

Document

Document type {
    id: Str,
    name: Str,
    collection_id: Str?,
    content_type: Str?,
    size: Int?,
    created_at: Str?,
    status: Str?,
    fields: Map?
}

HttpError

HttpError type {
    status: Int,
    headers: Map,
    body: Any
}

MetadataField

MetadataField type {
    name: Str,
    type: Str?,
    required: Bool?,
    unique: Bool?,
    inject_into_chunk: Bool?
}

RetrievalMode

RetrievalMode type {
    type: Str
}

SearchRequest

SearchRequest type {
    query: Str,
    collection_ids: Vec,
    max_results: Int?,
    retrieval_mode: RetrievalMode?
}

SearchResponse

SearchResponse type {
    results: Vec
}

SearchResult

SearchResult type {
    content: Str?,
    file_id: Str?,
    file_name: Str?,
    score: Dec?,
    metadata: Map?
}

UpdateCollectionRequest

UpdateCollectionRequest type {
    name: Str?,
    description: Str?
}