---
title: "Retrieve Chunks using Semantic, Keyword, or Hybrid Search"
method: POST
path: "/v1/primitives/search"
tags: ["Primitives", "Primitives"]
---

# Retrieve Chunks using Semantic, Keyword, or Hybrid Search

`POST /v1/primitives/search`

Perform document chunk search using semantic, keyword, or hybrid strategies.

This endpoint provides flexible search capabilities across ingested documents
with support for different search strategies based on use case requirements.

Search Types:
* **Semantic Search**: Uses vector embeddings to find chunks with similar meaning
  to the provided text query, regardless of exact keyword matches
* **Keyword Search**: Finds chunks containing specific keywords with exact or
  fuzzy matching capabilities (implementation pending)
* **Hybrid Search**: Combines semantic similarity with keyword matching for
  comprehensive results (implementation pending)

Key Features:
* **Score-based Ranking**: Results include similarity/relevance scores
* **Context Filtering**: Narrow search to specific collections,
artifacts, or metadata
* **Adjacent Context**: Optionally retrieve surrounding chunks for richer context
* **Configurable Limits**: Control result count (1-100 chunks)
* **Flexible Matching**: Choose optimal strategy based on query type

Search Process:
1. Parse request to determine search strategy and parameters
2. Apply context filters to narrow search scope
3. Execute search using appropriate algorithm (semantic/keyword/hybrid)
4. Rank results by relevance score
5. Optionally expand results with adjacent chunks for context

Current Implementation Status:
* ✅ Semantic Search: Fully implemented and production-ready
* 🚧 Keyword Search: Planned feature, returns 400 if requested
* 🚧 Hybrid Search: Planned feature, returns 400 if requested

Notes:
* Higher scores indicate better matches
* Expansion increases response time but provides richer context
* Use `/artifacts/list` to discover available collections and metadata
* Semantic search works best for conceptual queries
* Keyword search (when available) will excel at exact term matching

## Request body

- union — Request body for searching document chunks using different strategies. Supports three search types: - **semantic_search**: Find chunks based on semantic similarity to the text query - **keywords_search**: Find chunks containing specific keywords (coming soon) - **hybrid_search**: Combine semantic and keyword matching (coming soon) The request body defines search criteria, context filtering options, result limits, and expansion settings for retrieving relevant document chunks.
  - SemanticSearch — Represents a semantic search operation.
    - `type` 'semantic_search' — Type of search operation, always 'semantic_search' for semantic searches
    - `text` string, required — The text query to find relevant chunks
    - `context_filter` ContextFilter, required — Filter by collection, artifacts and metadata in the ingested context. The main filter is the collection the context is part of. All artifacts ids are ensured to be part of the context. If any of the ids is not usable in the context (i.e. doesn't exist), the related task will fail. The metadata filter will look for all context matching the metadata, if any, and add it to the context. The filter is a dictionary of key-value pairs. The key is the metadata key, and the value is the metadata value. If both artifacts and metadata filters are provided, the result will be the intersection of the two filters.
      - `collection` string — The name of the collection to filter on.
      - `artifacts` string[], nullable — Artifacts ids to filter on.
      - `metadata_filter` object[], nullable — Metadata filter to apply on the context.
    - `limit` integer — Maximum number of chunks to return
    - `score_threshold` number — Minimum similarity score threshold for returned chunks
    - `expand` boolean — Whether to include adjacent chunks for more context
  - KeywordSearch — Represents a keyword-based search operation.
    - `type` 'keywords_search' — Type of search operation, always 'keywords_search' for keyword searches
    - `keywords` string[], required — List of keywords to find relevant chunks
    - `context_filter` ContextFilter, required — Filter by collection, artifacts and metadata in the ingested context. The main filter is the collection the context is part of. All artifacts ids are ensured to be part of the context. If any of the ids is not usable in the context (i.e. doesn't exist), the related task will fail. The metadata filter will look for all context matching the metadata, if any, and add it to the context. The filter is a dictionary of key-value pairs. The key is the metadata key, and the value is the metadata value. If both artifacts and metadata filters are provided, the result will be the intersection of the two filters.
      - `collection` string — The name of the collection to filter on.
      - `artifacts` string[], nullable — Artifacts ids to filter on.
      - `metadata_filter` object[], nullable — Metadata filter to apply on the context.
    - `limit` integer — Maximum number of chunks to return
  - HybridSearch — Represents a hybrid search operation combining semantic and keyword search.
    - `type` 'hybrid_search' — Type of search operation, always 'hybrid_search' for combined searches
    - `text` string, required — The text query to find relevant chunks
    - `keywords` string[], required — List of keywords to find relevant chunks
    - `context_filter` ContextFilter, required — Filter by collection, artifacts and metadata in the ingested context. The main filter is the collection the context is part of. All artifacts ids are ensured to be part of the context. If any of the ids is not usable in the context (i.e. doesn't exist), the related task will fail. The metadata filter will look for all context matching the metadata, if any, and add it to the context. The filter is a dictionary of key-value pairs. The key is the metadata key, and the value is the metadata value. If both artifacts and metadata filters are provided, the result will be the intersection of the two filters.
      - `collection` string — The name of the collection to filter on.
      - `artifacts` string[], nullable — Artifacts ids to filter on.
      - `metadata_filter` object[], nullable — Metadata filter to apply on the context.
    - `limit` integer — Maximum number of chunks to return
    - `expand` boolean — Whether to include adjacent chunks for more context

## Response `200`

Successful chunk retrieval

- unknown

## Other responses

- `401` — Unauthorized
- `422` — Validation Error - Invalid request parameters
- `501` — Not Implemented - Search type not yet supported

## Changes

- **2026-06-02** `c711b911f68e` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/zylon-ai/apis/private-gpt-api/changes/v1/primitives/search/post.md)

---

[API](https://skmtc.dev/zylon-ai/apis/private-gpt-api.md) · [All operations](https://skmtc.dev/zylon-ai/apis/private-gpt-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/zylon-ai/private-gpt-api/revisions/4e828cf153c4/schema)