Skip to main content
POST
/
api
/
v1
/
retrieval
/
query
/
collection
curl -X POST "https://your-domain.com/api/v1/retrieval/query/collection" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "collection_names": ["kb_123abc"],
    "query": "How do I install the software?",
    "k": 5,
    "hybrid": true
  }'

{
  "distances": [[0.234, 0.289, 0.312, 0.445, 0.521]],
  "documents": [[
    "To install the software, follow these steps: 1. Download the installer from our website...",
    "Installation requirements: Operating System: Windows 10 or later, macOS 11+...",
    "For Linux installation, use the following command: sudo apt-get install...",
    "After installation, launch the application from the Start menu or Applications folder...",
    "The setup wizard will guide you through the initial configuration..."
  ]],
  "metadatas": [[
    {
      "file_id": "file_abc123",
      "name": "installation_guide.pdf",
      "source": "installation_guide.pdf",
      "created_by": "user_456def",
      "embedding_config": {
        "engine": "openai",
        "model": "text-embedding-3-small"
      }
    },
    {
      "file_id": "file_abc123",
      "name": "installation_guide.pdf",
      "source": "installation_guide.pdf",
      "created_by": "user_456def",
      "embedding_config": {
        "engine": "openai",
        "model": "text-embedding-3-small"
      }
    }
  ]],
  "ids": [[
    "chunk_uuid_1",
    "chunk_uuid_2",
    "chunk_uuid_3",
    "chunk_uuid_4",
    "chunk_uuid_5"
  ]]
}
Query one or more knowledge base collections using semantic search. Returns the most relevant document chunks based on vector similarity and optional reranking.

​
Request

​
Request Body

​
collection_names
array
required
Array of knowledge base collection IDs to query. Each knowledge base has a unique collection ID.
​
query
string
required
The search query text. Will be embedded and compared against document embeddings.
​
k
integer
Number of results to return (default: configured TOP_K value). For hybrid search, this is the initial retrieval size before reranking.
​
k_reranker
integer
Number of results after reranking (only applies when hybrid search is enabled). Default: configured TOP_K_RERANKER.
​
r
float
Relevance threshold (0.0 to 1.0). Results below this threshold are filtered out. Default: configured RELEVANCE_THRESHOLD.
​
hybrid
boolean
Whether to use hybrid search (vector + BM25 + reranking). Default: based on ENABLE_RAG_HYBRID_SEARCH setting.
​
hybrid_bm25_weight
float
Weight for BM25 scores in hybrid search (0.0 to 1.0). Default: configured HYBRID_BM25_WEIGHT.
​
enable_enriched_texts
boolean
Whether to include enriched text snippets. Default: ENABLE_RAG_HYBRID_SEARCH_ENRICHED_TEXTS.

​
Headers

​
Authorization
string
required
Bearer token for authentication

​
Response

Returns an array of relevant document chunks ranked by relevance score.
​
distances
array
Array of arrays containing distance scores (lower is more similar). One array per collection queried.
​
documents
array
Array of arrays containing the text content of matching chunksExample: [["Product guide chapter 1...", "Setup instructions..."]]
​
metadatas
array
Array of arrays containing metadata for each document chunk
​
file_id
string
ID of the source file
​
name
string
Name of the source document
​
source
string
Source identifier or filename
​
created_by
string
User ID who uploaded the document
​
embedding_config
object
Configuration of the embedding model used
​
ids
array
Array of arrays containing unique chunk IDs
​
scores
array
(Hybrid search only) Relevance scores after reranking (higher is better)
curl -X POST "https://your-domain.com/api/v1/retrieval/query/collection" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "collection_names": ["kb_123abc"],
    "query": "How do I install the software?",
    "k": 5,
    "hybrid": true
  }'

{
  "distances": [[0.234, 0.289, 0.312, 0.445, 0.521]],
  "documents": [[
    "To install the software, follow these steps: 1. Download the installer from our website...",
    "Installation requirements: Operating System: Windows 10 or later, macOS 11+...",
    "For Linux installation, use the following command: sudo apt-get install...",
    "After installation, launch the application from the Start menu or Applications folder...",
    "The setup wizard will guide you through the initial configuration..."
  ]],
  "metadatas": [[
    {
      "file_id": "file_abc123",
      "name": "installation_guide.pdf",
      "source": "installation_guide.pdf",
      "created_by": "user_456def",
      "embedding_config": {
        "engine": "openai",
        "model": "text-embedding-3-small"
      }
    },
    {
      "file_id": "file_abc123",
      "name": "installation_guide.pdf",
      "source": "installation_guide.pdf",
      "created_by": "user_456def",
      "embedding_config": {
        "engine": "openai",
        "model": "text-embedding-3-small"
      }
    }
  ]],
  "ids": [[
    "chunk_uuid_1",
    "chunk_uuid_2",
    "chunk_uuid_3",
    "chunk_uuid_4",
    "chunk_uuid_5"
  ]]
}

​
Query Single Document Collection

For querying a single file’s collection: 
POST /api/v1/retrieval/query/doc

​
Request Body

​
collection_name
string
required
Single collection name (usually file-{file_id} for individual files)
​
query
string
required
Search query text
​
k
integer
Number of results to return
​
k_reranker
integer
Number of results after reranking
​
r
float
Relevance threshold
​
hybrid
boolean
Enable hybrid search

​
Search Modes

​
Vector Search (Default)

  • Embeds your query using the configured embedding model
  • Performs cosine similarity search against document embeddings
  • Fast and efficient for semantic similarity
When hybrid=true or ENABLE_RAG_HYBRID_SEARCH is enabled:
  1. Vector Search: Retrieves top k results by embedding similarity
  2. BM25 Search: Retrieves results using keyword matching
  3. Fusion: Combines results using hybrid_bm25_weight
  4. Reranking: Uses cross-encoder model to rerank to top k_reranker results
  5. Filtering: Removes results below relevance threshold r

​
Access Control

  • Users can only query knowledge bases they have read access to
  • Collection names are validated against user permissions
  • Access is granted based on:
    • Knowledge base ownership
    • Group membership with read permissions
    • Admin role

​
Notes

  • Query embedding uses the same model as document embedding for consistency
  • Results are returned in order of relevance (most relevant first)
  • The distances field contains cosine distances (lower = more similar)
  • The scores field (hybrid search only) contains reranking scores (higher = better)
  • Multiple collections are queried in parallel for efficiency
  • Results can be filtered by relevance threshold to improve quality