Create and manage collections

From isolated files to a knowledge base

Until now, each document stood alone: you uploaded it, referenced it, and the index built for the occasion disappeared with the query. Collections change the scale: they group your files into structured knowledge bases, indexed once and queryable indefinitely. This is the foundation of RAG—Retrieval-Augmented Generation—with Grok, and the difference shows as soon as a support team queries two hundred product sheets instead of a single PDF.

Think of a collection as a smart folder. You deposit documents, xAI indexes them for semantic search, and Grok searches this base to answer with precision, pulling the three useful passages from among thousands.

A separate API, and why

You don’t manage collections from the API you’ve used since the start of the course. They fall under the Management API, hosted on management-api.x.ai, with the base URL:

https://management-api.x.ai/v1

This separation isn’t an architectural whim. Creating, modifying, or deleting a collection are administrative operations with heavy consequences, and xAI requires a dedicated key for them: a Management API Key, with the AddFileToCollection permission. The benefit is immediate for teams: the service querying the base from your public application receives the standard key and can’t destroy anything; only your ingestion pipeline holds the management key.

Create your first collection

Creation boils down to a single call with a name:

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

The response returns the identifier to keep:

{
  "collection_id": "col_xyz789",
  "collection_name": "technical-docs",
  "created_at": "2026-04-01T10:00:00Z"
}

Choose this name carefully: it will appear in all your lists and, six months later, will be the only clue letting you distinguish two neighboring bases. technical-docs fills this role; test2 won’t. Adopt a convention from the first collection, because renaming a base already referenced by three applications costs more than naming it well from the start.

The five available operations

The Management API exposes a full CRUD set on collections:

Listing your collections happens without parameters and gives a useful overview before any maintenance operation:

curl https://management-api.x.ai/v1/collections \
  -H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY"

Deletion follows the same logic, designating the identifier obtained at creation:

curl -X DELETE https://management-api.x.ai/v1/collections/col_xyz789 \
  -H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY"

One thing should reassure you when you run this command: deleting a collection removes the indexing, not the files. Your documents remain accessible via the Files API and can be reindexed elsewhere. You lose the search structure, not the raw material—which makes rebuilding a poorly organized base far less risky than it seems.

Key takeaways

• Collections group your files into indexed knowledge bases for RAG
• Management happens via the Management API (management-api.x.ai), not the standard API
• A Management API Key with AddFileToCollection permission is required
• Limits are 100,000 files and 100 GB per account
• The five CRUD operations cover creation, reading, updating, and deletion