Update a collection via the Management API

Rename a collection, change its description, tweak chunk settings, or add/remove metadata field definitions with PUT https://management-api.x.ai/v1/collections/{collection_id} and a Management API key. Field schema details: Set collection metadata fields and filter search.

Rename

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 (2025)",
    "collection_description": "10-K and 10-Q filings for financial analysis"
  }'

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"),
)
collection = client.collections.update(
    "collection_dbc087b1-6c99-493d-86c6-b401fee34a9d",
    name="SEC Filings (2025)",
)
print(collection.collection_id, collection.collection_name)

Add or delete field definitions

Send field_definition_updates on the same PUT. Each item pairs a field_definition with an operation:

• FIELD_DEFINITION_ADD — create the field, or replace the definition when the key already exists. You cannot add a new field with required: true (existing documents would fail validation).
• FIELD_DEFINITION_DELETE — drop the definition and cascade remove that field's values from every document in the collection.

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 '{
    "field_definition_updates": [
      {
        "operation": "FIELD_DEFINITION_ADD",
        "field_definition": {
          "key": "region",
          "required": false,
          "inject_into_chunk": true,
          "description": "Filing region code"
        }
      },
      {
        "operation": "FIELD_DEFINITION_DELETE",
        "field_definition": { "key": "legacy_tag" }
      }
    ]
  }'

Pitfalls

• Index embedding model is set at create time; use update for name, description, chunk config, and field definitions.
• FIELD_DEFINITION_DELETE removes stored values for that key across the collection. Confirm before you send it.
• Management key only. Search still uses XAI_API_KEY.
• Console API credits are a separate bill from SuperGrok's weekly pool on grok.com.