The document search endpoint

Querying your knowledge bases

So far you’ve built the container: collections, indexed documents, metadata. None of this matters unless you know how to ask a question. That’s the job of POST /v1/documents/search, which takes a natural language query and returns the passages from your documents that answer it best. Imagine a support team that receives “What is the withdrawal period?” Instead of making an agent read the terms and conditions, you send the question to the endpoint and retrieve the three useful paragraphs, complete with their score and source.

Request structure

First thing to remember, and this is a common source of errors: this endpoint lives on the standard API (api.x.ai), not the Management API you used to create collections. You authenticate with your usual API key. The minimal request comes down to three fields.

curl -X POST https://api.x.ai/v1/documents/search \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "How do I configure OAuth authentication?",
    "source": {
      "collection_ids": ["col_xyz789"]
    },
    "retrieval_mode": {
      "type": "hybrid"
    }
  }'

Main parameters

• query: your question in natural language. The more specific the question, the more relevant the results
• source.collection_ids: an array of collection IDs to query. You can search across multiple collections in a single request
• retrieval_mode.type: the search mode to use (keyword, semantic, or hybrid)

Reading the response

The API doesn’t return entire documents but fragments, the chunks created during indexing, ranked from most to least relevant.

{
  "results": [
    {
      "content": "To configure OAuth, start by...",
      "score": 0.92,
      "document_id": "file_abc123",
      "metadata": {
        "filename": "security-guide.pdf",
        "page": 12
      }
    },
    {
      "content": "The OAuth 2.0 flow uses...",
      "score": 0.87,
      "document_id": "file_def456",
      "metadata": {
        "filename": "api-reference.pdf",
        "page": 45
      }
    }
  ]
}

Each entry carries four pieces of information:

• content: the text excerpt from the document
• score: a relevance score between 0 and 1
• document_id: the ID of the source file
• metadata: the document metadata (name, page, custom fields)

In the example above, the first excerpt comes from page 12 of security-guide.pdf with a score of 0.92, the second from page 45 of another file at 0.87. These two values are enough to build an interface that displays the answer and, just below it, a “view original passage, page 12” link. The score acts as a threshold: many teams discard any result below 0.5 rather than letting the model reason on noise.

Searching across multiple collections

If collection_ids is an array, that’s no accident. A customer question often mixes several document universes, and you don’t want to make three calls then merge the results by hand.

{
  "query": "Refund policy",
  "source": {
    "collection_ids": [
      "col_docs_produit",
      "col_faq",
      "col_conditions_generales"
    ]
  },
  "retrieval_mode": {
    "type": "hybrid"
  }
}

Here, product documentation, the FAQ, and terms and conditions are queried together. Results come back merged and sorted by score, regardless of their original collection: a FAQ excerpt at 0.94 will rank above a T&C excerpt at 0.71. You cross heterogeneous sources in a single network round-trip.

Cost

Searching collections costs $2.50 per 1,000 calls, and this rate doesn’t change based on the number of collections queried or the size of the indexed documents. Compare this to file attachments, those individual files passed via input_file, billed at $10 per 1,000 calls: as soon as you query the same documents repeatedly, collections cost four times less. An internal assistant handling 20,000 questions per month pays $50 with collections versus $200 with attachments—and gets faster results into the bargain, since the index already exists.

Pricing as of August 5, 2026 — prices change regularly: before any budget calculation, check the current rate card on the official xAI models and pricing page.

Key takeaways

• The POST /v1/documents/search endpoint queries your collections in natural language
• Three search modes available: keyword, semantic, hybrid
• You can search across multiple collections simultaneously
• Results are ranked by relevance score with source content
• Cost is $2.50 per 1,000 calls, four times cheaper than file attachments