For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Contact usJoin the Discord
ManualAPI GuideAPI Reference
  • Overview
    • API Reference
    • Client libraries
  • API Reference
      • POSTRetrieve Chunks using Semantic, Keyword, or Hybrid Search
LogoLogo
Contact usJoin the Discord
API ReferencePrimitives

Retrieve Chunks using Semantic, Keyword, or Hybrid Search

POST
https://host.com/v1/primitives/search
POST
/v1/primitives/search
$curl -X POST https://host.com/v1/primitives/search \
>     -H "Content-Type: application/json" \
>     -d '{
>  "type": "semantic_search",
>  "context_filter": {
>    "collection": "reports"
>  },
>  "text": "Q3 2023 sales performance",
>  "expand": true,
>  "limit": 10
>}'
1{
2  "object": "list",
3  "model": "private-gpt",
4  "data": [
5    {
6      "object": "context.chunk",
7      "score": 0.89,
8      "document": {
9        "object": "ingest.document",
10        "artifact": "q3_report",
11        "doc_metadata": {
12          "title": "Q3 2023 Report",
13          "file_name": "Q3_Sales.pdf"
14        }
15      },
16      "text": "Q3 sales increased by 25% compared to Q2, driven primarily by new customer acquisitions in the enterprise segment.",
17      "previous_texts": [
18        "Q2 comparison shows steady growth trends."
19      ],
20      "next_texts": [
21        "Regional breakdown indicates strongest performance in North America."
22      ]
23    }
24  ]
25}
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
Was this page helpful?
Previous

Semantic Search

Next
Built with

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

This endpoint expects an object.
semantic_searchobjectRequired
Represents a semantic search operation.
OR
keywords_searchobjectRequired

Represents a keyword-based search operation.

OR
hybrid_searchobjectRequired
Represents a hybrid search operation combining semantic and keyword search.

Response

This endpoint returns any.

Errors

401
Unauthorized
422
Unprocessable Entity
501
Not Implemented