Create a collection and upload documents via API

Collections are a persistent embedding index over uploaded files. Management calls go to https://management-api.x.ai/v1 with a Management API key that has AddFileToCollection (plus Collections Endpoint permissions to create, update, or delete). Chat search still uses the regular XAI_API_KEY.

Create the collection

Mint the management key in Console → Management Keys. Copy it once.

curl https://management-api.x.ai/v1/collections \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY" \
  -d '{"collection_name": "SEC Filings"}'

import os
from xai_sdk import Client

client = Client(
    api_key=os.getenv("XAI_API_KEY"),
    management_api_key=os.getenv("XAI_MANAGEMENT_API_KEY"),
    timeout=3600,
)
collection = client.collections.create(name="SEC Filings")
print(collection)

Upload a document (two steps)

1. POST https://api.x.ai/v1/files with the regular API key.
2. POST https://management-api.x.ai/v1/collections/{collection_id}/documents/{file_id} with the management key.

with open("tesla-20241231.html", "rb") as f:
    document = client.collections.upload_document(
        collection_id="collection_dbc087b1-6c99-493d-86c6-b401fee34a9d",
        name="tesla-20241231.html",
        data=f.read(),
    )
print(document)

Wait until the document is processed before searching. Collection file cap is 100 MB. Account needs Console credits to upload.

Search the index

curl https://api.x.ai/v1/documents/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -d '{
    "query": "What were the key revenue drivers based on the SEC filings?",
    "source": {"collection_ids": ["collection_dbc087b1-6c99-493d-86c6-b401fee34a9d"]},
    "retrieval_mode": {"type": "hybrid"}
  }'

retrieval_mode.type is hybrid (default), keyword, or semantic. For Grok to search during a chat turn, pass file_search with vector_store_ids on /v1/responses (see search-collections-with-grok-api).

Pitfalls

• Create/upload/delete need the management key on management-api.x.ai. /v1/documents/search and chat file_search use the regular API key on api.x.ai.
• Searching a still-processing collection returns empty matches.
• Credits must be on the Console account or uploads fail.
• Console API credits are separate from SuperGrok's weekly pool on grok.com.