Set collection metadata fields and filter search

Attach structured attributes to documents in a collection so search can filter on them and embeddings can carry title (or other) context into every chunk. Management calls use https://management-api.x.ai/v1 with a Management API key. Document search uses the regular XAI_API_KEY on https://api.x.ai/v1. Create the collection first (Create a collection and upload documents via API).

Define fields on create

Pass field_definitions when you create the collection:

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": "research_papers",
    "field_definitions": [
      { "key": "author", "required": true },
      { "key": "year", "required": true, "unique": true },
      { "key": "title", "inject_into_chunk": true }
    ]
  }'

Option	Default	Effect
required	false	Upload must include this field
unique	false	Only one document may hold a given value
inject_into_chunk	false	Prepends the field value to every embedding chunk

Upload with fields

Send metadata as a JSON object in the multipart fields part:

curl -X POST "https://management-api.x.ai/v1/collections/$COLLECTION_ID/documents" \
  -H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY" \
  -F "name=paper.pdf" \
  -F "data=@paper.pdf" \
  -F "content_type=application/pdf" \
  -F 'fields={"author": "Sandra Kim", "year": "2024", "title": "Q3 Revenue Analysis"}'

Filter search (AIP-160)

Restrict hits with filter on POST https://api.x.ai/v1/documents/search:

curl -X POST "https://api.x.ai/v1/documents/search" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "revenue growth",
    "source": { "collection_ids": ["collection_xxx"] },
    "filter": "author=\"Sandra Kim\" AND year>=2020"
  }'

Operators: =, !=, <, >, <=, >=, AND, OR. AND binds tighter than OR; use parentheses when you need the other grouping. Strings with spaces need quotes. Wildcards like author="E*" are not supported — comparisons are exact. Filtering on a field that is not on the documents returns no results.

Pitfalls

• Declaring required or unique after documents already exist — set field_definitions at create time.
• Assuming inject_into_chunk changes the stored PDF — it only changes what goes into each embedding chunk.
• Using Management API credentials on documents/search — search needs the inference key.