---
title: "Search for content related to the query within the given collections."
method: POST
path: "/v1/documents/search"
tags: ["v1"]
---

# Search for content related to the query within the given collections.

`POST /v1/documents/search`

## Request body

- SearchRequest — SearchRequest defines the request to search for documents.
  - `filter` string, nullable — 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` GroupBy — Group search results by metadata key(s) and keep top-k per group.
    - `aggregate` union — Aggregation function to apply within each group.
      - object — Keep the k records with the smallest values (best scores).
        - `min_k` object, required — Keep the k records with the smallest values (best scores).
          - `k` integer, required — Number of records to keep per group. Must be >= 1.
          - `keys` string[], required — Key(s) to sort by within each group. Use "#score" for relevance score.
      - object — Keep the k records with the largest values.
        - `max_k` object, required — Keep the k records with the largest values.
          - `k` integer, required — Number of records to keep per group. Must be >= 1.
          - `keys` string[], required — Key(s) to sort by within each group.
    - `keys` string[], required — Metadata key(s) to group results by (e.g. "category", "department"). At least one key is required.
  - `instructions` string, nullable — User-defined instructions to be included in the search query. Defaults to generic search instructions.
  - `limit` integer, nullable — The number of chunks to return. Will always return the top matching chunks. Optional, defaults to 10.
  - `query` string, required — 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` 'RANKING_METRIC_UNKNOWN' | 'RANKING_METRIC_L2_DISTANCE' | 'RANKING_METRIC_COSINE_SIMILARITY' — Deprecated: Metric now comes from collection creation.
  - `retrieval_mode` union — Retrieval mode configuration for document search.
    - object — Hybrid search combining keyword and semantic search.
      - `reranker` union — Reranker configuration for hybrid retrieval.
        - object — Use a reranker model to perform the reranking.
          - `instructions` string, nullable — Instructions for the reranking model. Defaults to generic reranking instructions.
          - `model` string, nullable — The model to use for reranking. Defaults to standard reranker model.
          - `type` 'reranker_model', required
        - object — Use RRF to perform the reranking.
          - `embedding_weight` number, float — Weight for embedding (dense) search results. Should be between 0 and 1. Defaults to 0.5.
          - `k` integer, nullable — The RRF constant k used in the reciprocal rank fusion formula. Defaults to 60.
          - `text_weight` number, float — Weight for keyword (sparse) search results. Should be between 0 and 1. Defaults to 0.5.
          - `type` 'rrf', required
      - `search_multiplier` integer, nullable — Additional multiplier to requested search limit. Valid range is [1, 100]. Defaults to 1 when unset.
      - `type` 'hybrid', required
    - object — Semantic search using dense embeddings.
      - `reranker` RerankerModel — Configuration for model-based reranking.
        - `instructions` string, nullable — Instructions for the reranking model. Defaults to generic reranking instructions.
        - `model` string, nullable — The model to use for reranking. Defaults to standard reranker model.
      - `type` 'semantic', required
    - object — Keyword search using sparse embeddings.
      - `reranker` RerankerModel — Configuration for model-based reranking.
        - `instructions` string, nullable — Instructions for the reranking model. Defaults to generic reranking instructions.
        - `model` string, nullable — The model to use for reranking. Defaults to standard reranker model.
      - `type` 'keyword', required
  - `source` DocumentsSource, required — DocumentsSource defines the source of documents to search over.
    - `collection_ids` string[], required — The collection IDs to search in.
    - `rag_pipeline` 'chroma_db' | 'es'

## Response `200`

Success

- SearchResponse — SearchResponse defines the response to a search request.
  - `matches` SearchMatch[], required — The search matches.
    - `chunk_content` string, required — The chunk content.
    - `chunk_id` string, required — The chunk ID.
    - `collection_ids` string[], required — The collection ID(s).
    - `fields` object, required — Metadata fields belonging to the document of this chunk.
    - `file_id` string, required — The document ID.
    - `page_number` integer — The dominant page number this chunk belongs to (0 for single-page docs).
    - `score` number, float, required — The relevance score.

## Other responses

- `400` — Bad request. The request is invalid or an invalid API key is provided.

---

[API](https://skmtc.net/x/apis/xai-s-rest-api.md) · [All operations](https://skmtc.net/x/apis/xai-s-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/x/xai-s-rest-api/versions/8f6014272113/schema)