openapi: 3.2.0
info:
  title: xAI's REST Documents API
  description: REST API for xAI compatible with other providers.
  license:
    name: ''
  version: 1.0.0
tags:
- name: Documents
paths:
  /v1/documents/search:
    post:
      tags:
      - Documents
      summary: Search for content related to the query within the given collections
      operationId: handle_document_search_request_v2
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
            example:
              query: What is the revenue in the last quarter?
              source:
                collection_ids:
                - collection_80100614-300c-4609-959b-a138fa90f542
              filter: document_type = "financial_report" AND year > 2020
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
              example:
                matches:
                - file_id: file_ac3c5728-7399-41fc-bd62-0fef0042de9c
                  chunk_id: 0199717c-511b-7a80-bab3-dfe9a27f82ab
                  chunk_content: ', deferred revenue related to such customer payments amounted to $2.10 billion and $1.77 billion, respectively, mainly due to contractual payment terms. Revenue recognized from the deferred revenue balances as of December 31, 2024 and 2023 was $944 million and $873 million for the six months ended June 30, 2025 and 2024, respectively. We have elected the practical expedient to omit disclosure of the amount of the transaction price allocated to remaining performance obligations for contracts with an original expected contract length of one year or less. As of June 30, 2025, total transaction price allocated to performance obligations that were unsatisfied or partially unsatisfied for contracts with an original expected length of more than one year was $10.38 billion. Of this amount, we expect to recognize $5.47 billion in the next 12 months and the rest over the remaining performance obligation period. Changes in government and economic incentives or tariffs may impact the transaction price or our ability to e'
                  score: 1.1447691
                  collection_ids:
                  - collection_80100614-300c-4609-959b-a138fa90f542
        '400':
          description: Bad request. The request is invalid or an invalid API key is provided.
      security:
      - bearerAuth: []
components:
  schemas:
    SemanticRetrieval:
      type: object
      description: Document search using semantic similarity (dense embeddings).
      properties:
        reranker:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/RerankerModel'
            description: Optional, but always used when doing search across multiple collections.
    SearchMatch:
      type: object
      description: SearchMatch defines a single match from a search request.
      required:
      - file_id
      - chunk_id
      - chunk_content
      - score
      - collection_ids
      - fields
      properties:
        chunk_content:
          type: string
          description: The chunk content.
        chunk_id:
          type: string
          description: The chunk ID.
        collection_ids:
          type: array
          items:
            type: string
          description: The collection ID(s).
        fields:
          type: object
          description: Metadata fields belonging to the document of this chunk.
          additionalProperties:
            type: string
          propertyNames:
            type: string
        file_id:
          type: string
          description: The document ID.
        page_number:
          type: integer
          format: int32
          description: The dominant page number this chunk belongs to (0 for single-page docs).
        score:
          type: number
          format: float
          description: The relevance score.
    RerankerModel:
      type: object
      description: Configuration for model-based reranking.
      properties:
        instructions:
          type:
          - string
          - 'null'
          description: Instructions for the reranking model. Defaults to generic reranking instructions.
        model:
          type:
          - string
          - 'null'
          description: The model to use for reranking. Defaults to standard reranker model.
    SearchResponse:
      type: object
      description: SearchResponse defines the response to a search request.
      required:
      - matches
      properties:
        matches:
          type: array
          items:
            $ref: '#/components/schemas/SearchMatch'
          description: The search matches.
    RetrievalMode:
      oneOf:
      - allOf:
        - $ref: '#/components/schemas/HybridRetrieval'
          description: Hybrid search combining keyword and semantic search.
        - type: object
          required:
          - type
          properties:
            type:
              type: string
              enum:
              - hybrid
        description: Hybrid search combining keyword and semantic search.
      - allOf:
        - $ref: '#/components/schemas/SemanticRetrieval'
          description: Semantic search using dense embeddings.
        - type: object
          required:
          - type
          properties:
            type:
              type: string
              enum:
              - semantic
        description: Semantic search using dense embeddings.
      - allOf:
        - $ref: '#/components/schemas/KeywordRetrieval'
          description: Keyword search using sparse embeddings.
        - type: object
          required:
          - type
          properties:
            type:
              type: string
              enum:
              - keyword
        description: Keyword search using sparse embeddings.
      description: Retrieval mode configuration for document search.
    GroupByAggregate:
      oneOf:
      - type: object
        description: Keep the k records with the smallest values (best scores).
        required:
        - min_k
        properties:
          min_k:
            type: object
            description: Keep the k records with the smallest values (best scores).
            required:
            - keys
            - k
            properties:
              k:
                type: integer
                format: int32
                description: Number of records to keep per group. Must be >= 1.
              keys:
                type: array
                items:
                  type: string
                description: Key(s) to sort by within each group. Use "#score" for relevance score.
      - type: object
        description: Keep the k records with the largest values.
        required:
        - max_k
        properties:
          max_k:
            type: object
            description: Keep the k records with the largest values.
            required:
            - keys
            - k
            properties:
              k:
                type: integer
                format: int32
                description: Number of records to keep per group. Must be >= 1.
              keys:
                type: array
                items:
                  type: string
                description: Key(s) to sort by within each group.
      description: Aggregation function to apply within each group.
    SearchRequest:
      type: object
      description: SearchRequest defines the request to search for documents.
      required:
      - query
      - source
      properties:
        filter:
          type:
          - string
          - 'null'
          description: 'Optional metadata filter string to apply to search results.

            Uses AIP-160 filter syntax for querying document metadata.

            Supports comparison operators: `=`, `!=`, `>`, `>=`, `<`, `<=`

            Supports logical operators: `AND`, `OR`

            Supports range syntax: `field:10..20` (inclusive)

            Examples: `author = "John"` or `year > 2020 AND category = "finance"`'
        group_by:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/GroupBy'
            description: 'Optional group_by to diversify search results by metadata key(s).

              When set, results are grouped by the specified key(s) and only the

              top-k records per group are returned. Applied after ranking and filtering.

              Documents missing a group_by key are placed in a shared null group.

              Grouping is applied per-collection, not across the combined result set.'
        instructions:
          type:
          - string
          - 'null'
          description: User-defined instructions to be included in the search query. Defaults to generic search instructions.
        limit:
          type:
          - integer
          - 'null'
          format: int32
          description: 'The number of chunks to return.

            Will always return the top matching chunks.

            Optional, defaults to 10.'
        query:
          type: string
          description: 'The query to search for which will be embedded using the

            same embedding model as the one used for the source to query.'
        ranking_metric:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/RankingMetric'
            description: 'Deprecated: Metric now comes from collection creation.'
        retrieval_mode:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/RetrievalMode'
            description: How to perform the document search. Defaults to hybrid retrieval.
        source:
          $ref: '#/components/schemas/DocumentsSource'
          description: The source to query.
    ReciprocalRankFusion:
      type: object
      description: Configuration for reciprocal rank fusion (RRF) reranking.
      properties:
        embedding_weight:
          type: number
          format: float
          description: Weight for embedding (dense) search results. Should be between 0 and 1. Defaults to 0.5.
        k:
          type:
          - integer
          - 'null'
          format: int32
          description: The RRF constant k used in the reciprocal rank fusion formula. Defaults to 60.
        text_weight:
          type: number
          format: float
          description: Weight for keyword (sparse) search results. Should be between 0 and 1. Defaults to 0.5.
    KeywordRetrieval:
      type: object
      description: Document search using keyword matching (sparse embeddings).
      properties:
        reranker:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/RerankerModel'
            description: Optional, but always used when doing search across multiple collections.
    RagPipeline:
      type: string
      enum:
      - chroma_db
      - es
    GroupBy:
      type: object
      description: Group search results by metadata key(s) and keep top-k per group.
      required:
      - keys
      properties:
        aggregate:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/GroupByAggregate'
            description: Aggregation function per group. Defaults to MinK(k=1, keys=["#score"]).
        keys:
          type: array
          items:
            type: string
          description: 'Metadata key(s) to group results by (e.g. "category", "department").

            At least one key is required.'
    HybridRetrieval:
      type: object
      description: Document search using a combination of keyword and semantic search.
      properties:
        reranker:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/HybridReranker'
            description: Which reranker to use to limit results to the desired value.
        search_multiplier:
          type:
          - integer
          - 'null'
          format: int32
          description: 'Additional multiplier to requested search limit.

            Valid range is [1, 100]. Defaults to 1 when unset.'
    HybridReranker:
      oneOf:
      - allOf:
        - $ref: '#/components/schemas/RerankerModel'
          description: Use a reranker model to perform the reranking.
        - type: object
          required:
          - type
          properties:
            type:
              type: string
              enum:
              - reranker_model
        description: Use a reranker model to perform the reranking.
      - allOf:
        - $ref: '#/components/schemas/ReciprocalRankFusion'
          description: Use RRF to perform the reranking.
        - type: object
          required:
          - type
          properties:
            type:
              type: string
              enum:
              - rrf
        description: Use RRF to perform the reranking.
      description: Reranker configuration for hybrid retrieval.
    DocumentsSource:
      type: object
      description: DocumentsSource defines the source of documents to search over.
      required:
      - collection_ids
      properties:
        collection_ids:
          type: array
          items:
            type: string
          description: The collection IDs to search in.
        rag_pipeline:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/RagPipeline'
            description: Which RAG pipeline to use. Defaults to `chroma_db` when unset.
    RankingMetric:
      type: string
      description: 'Deprecated: Metric now comes from collection creation.'
      enum:
      - RANKING_METRIC_UNKNOWN
      - RANKING_METRIC_L2_DISTANCE
      - RANKING_METRIC_COSINE_SIMILARITY
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer