search` + `file_search` tool)

Status: DOCUMENTED · ACCOUNT_RESTRICTED on the documented base (management-api.x.ai → 401 "Invalid bearer token. Please ensure you use a valid management key." with our inference key) · LIVE_DISCOVERED + LIVE_VERIFIED: the same /v1/collections* paths are served on https://api.x.ai with the inference key (create/list/get/delete 200, add document 200, list/get document 200) · /v1/documents/search FAILED_VERIFICATION (404 while the only document was still indexing; no processed collection within the probe window). Machine-readable: parameters/xai-files-collections-batches.json, endpoints/xai-inference.json, objects/xai-inference-objects.json (Collection, Document, SearchMatch), tools/xai-tools.json (file_search).

Sources: https://docs.x.ai/developers/rest-api-reference/collections/collection (Management API) · https://docs.x.ai/developers/rest-api-reference/collections/search · https://docs.x.ai/developers/files/collections · https://docs.x.ai/developers/files/collections/api · https://docs.x.ai/developers/files/collections/metadata · https://docs.x.ai/developers/tools/collections-search · OpenAPI SearchRequest, SearchResponse, DocumentsSource, RetrievalMode Last verified: 2026-09-19

# Concepts

Collection = group of Files-API files with an embedding index (grok-embedding-small default; chunking configurable; metadata field_definitions with required/unique/inject_into_chunk). One file may belong to several collections. Max file 100 MB (collections guide). Storage $0.10/GiB/day; downloads $0.20/GiB; file_search/collections_search tool $2.50 per 1k calls. Documents must reach DOCUMENT_STATUS_PROCESSED before search works.

# Management endpoints

Documented base https://management-api.x.ai + Management API key (AddFileToCollection permission etc., created in Console → Management Keys). Live: every path below also answered on https://api.x.ai with the ordinary inference key, but with gRPC-gateway strictness — path ids must be repeated in the JSON body, and some documented-optional fields are required.

Method	Path	Body (live requirements on api.x.ai)	Live
POST	`/v1/collections`	`{collection_name, field_definitions: [] ← required (422 otherwise), collection_description?, index_configuration.model_name?, chunk_configuration?, metric_space?}`; each field definition needs `key, required, inject_into_chunk, unique` (+`description`)	200 `collection_<uuid>`
GET	`/v1/collections`	`limit ≤100, order, sort_by, pagination_token, filter, team_id`	200 `{collections[], pagination_token}`
GET	`/v1/collections/{id}`		200 (many undocumented fields: `sharing`, `effective_privilege`, `is_owned`, `owner_team_id`, `total_file_size`, `disable_rag_lookup`, `enable_wiki_summary_generation`, `cloned_from_id`, …; `chunk_configuration.config.BytesConfiguration {4000, 800}`)
PUT	`/v1/collections/{id}`	`{collection_id, collection_name?, collection_description?, chunk_configuration?, field_definition_updates: [{field_definition, operation: FIELD_DEFINITION_ADD\|DELETE}]}` — live needs `collection_id` AND `field_definition_updates`	422 (not completed)
DELETE	`/v1/collections/{id}`		200 `{}`
POST	`/v1/collections/{id}/documents/{file_id}`	`{collection_id, file_id, fields?}` (both ids required in body live)	200 `{}`; indexing async
POST	`/v1/collections/{id}/documents`	guide-only multipart (`name`, `data`, `content_type`, `fields`) on management-api	api.x.ai → 405
GET	`/v1/collections/{id}/documents`	`limit, order, sort_by (NAME\|SIZE\|AGE), pagination_token, filter, name (deprecated)`	200
GET	`/v1/collections/{id}/documents/{file_id}`		200 — `status` returned as integer `1` (PROCESSING) instead of the documented string enum; extra `chunk_count`, `chunks_processed_count`, `file_metadata.processing_status:"Processing"`
PATCH	`/v1/collections/{id}/documents/{file_id}`	reindex	not called
DELETE	`/v1/collections/{id}/documents/{file_id}`		200 `{}` — hazard: the underlying file was deleted too (`GET /v1/files/{id}` → 404), even when the document had never been added
GET	`/v1/collections/{id}/documents:batchGet?file_ids=…`		400 (query encoding `file_ids=` "expected a sequence", `file_ids[]=` "missing field")

Document status enum (docs): DOCUMENT_STATUS_UNKNOWN | PROCESSING | PROCESSED | FAILED. Live a 208-byte txt was still processing after 75 s / 25 polls.

# Search: `POST /v1/documents/search` (api.x.ai, inference key)

Body: query (required), source.collection_ids[] (required; source.rag_pipeline chroma_db|es), limit (10), filter (AIP-160 over metadata: author = "John", year > 2020 AND …, ranges field:10..20), retrieval_mode {type: hybrid|semantic|keyword, reranker?: {model, instructions} | RRF {embedding_weight, text_weight, k}, search_multiplier?}, group_by {keys[], aggregate: min_k|max_k}, instructions, ranking_metric (deprecated). Response {matches[]: {file_id, chunk_id, chunk_content, score, collection_ids[], fields{}, page_number}}. Live: fake id → 404 not found or not accessible; [] → 400 Collection IDs cannot be empty; fresh collection (document processing) → same 404. Default mode hybrid.

# Agentic search: `file_search` tool (Responses)

{"type":"file_search","vector_store_ids":["collection_…"],"max_num_results":10} (alias collections_search, echoed as file_search; vector_store_ids required — 422 otherwise). Output item file_search_call {queries[], results[] (with include:["file_search_call.results"]), status}; citations collections://<collection_id>/files/<file_id>. Live (un-indexed collection): status:"failed", results: [], answer "No documents." — see docs/tools/xai/collections-search.md.

# SDK

xai-sdk: Client(api_key, management_api_key), client.collections.create/list/get/update/delete, upload_document(collection_id, name, data, fields), get_document, remove_document, search(query, collection_ids); proto enum collections_pb2.DOCUMENT_STATUS_PROCESSED.

Examples: examples/xai/collections/ (create → add file → poll → search → cleanup; expects 404 on search until indexed).

# xAI Collections — RAG knowledge bases (management endpoints + /v1/documents/search + file_search tool)