Set chunk configuration on a Grok collection

Control how uploaded documents split into embedding chunks with chunk_configuration on create (POST /v1/collections) or update (PUT /v1/collections/{collection_id}). Calls go to https://management-api.x.ai/v1 with a Management API key. Rename and field-definition updates live in Update a collection via the Management API.

Create with token chunks

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": "SEC Filings",
    "index_configuration": { "model_name": "grok-embedding-small" },
    "chunk_configuration": {
      "tokens_configuration": {
        "max_chunk_size_tokens": 1024,
        "chunk_overlap_tokens": 200,
        "encoding_name": "o200k_base"
      },
      "strip_whitespace": true,
      "inject_name_into_chunks": false
    },
    "collection_description": "Filings from the SEC for financial analysis"
  }'

Pick one primary size mode inside chunk_configuration:

Block	Size / overlap fields
tokens_configuration	max_chunk_size_tokens, chunk_overlap_tokens, encoding_name
chars_configuration	max_chunk_size_chars, chunk_overlap_chars
bytes_configuration	max_chunk_size_bytes, chunk_overlap_bytes
markdown_tokens_configuration / markdown_chars_configuration	markdown-aware token or char splits
code_tokens_configuration / code_chars_configuration	code-aware token or char splits
table_configuration	max_chunk_size_tokens, encoding_name

Shared flags on chunk_configuration: strip_whitespace, inject_name_into_chunks. Prefer code_tokens_configuration / code_chars_configuration over deprecated ast_configuration.

Update chunk settings later

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 '{
    "chunk_configuration": {
      "tokens_configuration": {
        "max_chunk_size_tokens": 512,
        "chunk_overlap_tokens": 64,
        "encoding_name": "o200k_base"
      },
      "strip_whitespace": true,
      "inject_name_into_chunks": true
    }
  }'

After you change chunk settings, reindex each document so existing files pick up the new splits.

Pitfalls

• Embedding index_configuration.model_name is set at create. Update covers name, description, chunk config, and field definitions.
• inject_name_into_chunks prepends the document name into produced chunks; metadata inject_into_chunk on field definitions is separate (Set collection metadata fields and filter search).
• Management key only. Search still uses XAI_API_KEY.
• Console API credits are a separate bill from SuperGrok's weekly pool on grok.com.