List, update, and delete collections via API

After Create a collection and upload documents via API, manage the collection itself on https://management-api.x.ai/v1 with a Management API key that has Collections Endpoint permissions (create/update/delete) plus AddFileToCollection when you still upload. Inference search keeps using the regular XAI_API_KEY on api.x.ai.

List

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

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,
)
print(client.collections.list())

Get one

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

print(client.collections.get("collection_dbc087b1-6c99-493d-86c6-b401fee34a9d"))

Rename / update

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

print(client.collections.update(
    "collection_dbc087b1-6c99-493d-86c6-b401fee34a9d",
    name="SEC Filings (New)",
))

Metadata field definitions are set at create (or update when the docs allow). Filtering on those fields is covered in Set collection metadata fields and filter search.

Remove a document

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

client.collections.remove_document(
    collection_id="collection_dbc087b1-6c99-493d-86c6-b401fee34a9d",
    file_id="file_55a709d4-8edc-4f83-84d9-9f04fe49f832",
)

Delete the collection

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

client.collections.delete(collection_id="collection_dbc087b1-6c99-493d-86c6-b401fee34a9d")

Pitfalls

• Management key on management-api.x.ai for list/get/update/delete. Regular team key on api.x.ai for documents/search and chat file_search.
• Mint the management key in Console → Management Keys and copy it once — you will not see it again.
• Collection file cap is 100 MB per document on the Collections path. Wait until a document is processed before searching.