Query Knowledge Bases

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
  }'

import requests

url = "https://your-domain.com/api/v1/retrieval/query/collection"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
}
payload = {
    "collection_names": ["kb_123abc"],
    "query": "How do I install the software?",
    "k": 5,
    "hybrid": True,
    "r": 0.3  # Filter results below 30% relevance
}

response = requests.post(url, headers=headers, json=payload)
results = response.json()

for i, doc in enumerate(results["documents"][0]):
    print(f"Result {i+1}:")
    print(f"Content: {doc[:100]}...")
    if "scores" in results:
        print(f"Score: {results['scores'][0][i]}")
    print(f"Source: {results['metadatas'][0][i]['name']}")
    print()

const response = await fetch(
  'https://your-domain.com/api/v1/retrieval/query/collection',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      collection_names: ['kb_123abc'],
      query: 'How do I install the software?',
      k: 5,
      hybrid: true
    })
  }
);

const results = await response.json();
results.documents[0].forEach((doc, i) => {
  console.log(`Result ${i+1}: ${doc.substring(0, 100)}...`);
  console.log(`Source: ${results.metadatas[0][i].name}`);
});

{
  "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"
  ]]
}

{
  "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..."
  ]],
  "metadatas": [[...]],
  "ids": [["chunk_uuid_1", "chunk_uuid_2", "chunk_uuid_3"]],
  "scores": [[0.89, 0.76, 0.68]]
}

{
  "detail": "Collection kb_invalid not found"
}

POST

api

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
  }'

import requests

url = "https://your-domain.com/api/v1/retrieval/query/collection"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
}
payload = {
    "collection_names": ["kb_123abc"],
    "query": "How do I install the software?",
    "k": 5,
    "hybrid": True,
    "r": 0.3  # Filter results below 30% relevance
}

response = requests.post(url, headers=headers, json=payload)
results = response.json()

for i, doc in enumerate(results["documents"][0]):
    print(f"Result {i+1}:")
    print(f"Content: {doc[:100]}...")
    if "scores" in results:
        print(f"Score: {results['scores'][0][i]}")
    print(f"Source: {results['metadatas'][0][i]['name']}")
    print()

const response = await fetch(
  'https://your-domain.com/api/v1/retrieval/query/collection',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      collection_names: ['kb_123abc'],
      query: 'How do I install the software?',
      k: 5,
      hybrid: true
    })
  }
);

const results = await response.json();
results.documents[0].forEach((doc, i) => {
  console.log(`Result ${i+1}: ${doc.substring(0, 100)}...`);
  console.log(`Source: ${results.metadatas[0][i].name}`);
});

{
  "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"
  ]]
}

{
  "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..."
  ]],
  "metadatas": [[...]],
  "ids": [["chunk_uuid_1", "chunk_uuid_2", "chunk_uuid_3"]],
  "scores": [[0.89, 0.76, 0.68]]
}

{
  "detail": "Collection kb_invalid not found"
}

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

array

required

Array of knowledge base collection IDs to query. Each knowledge base has a unique collection ID.

string

required

The search query text. Will be embedded and compared against document embeddings.

integer

Number of results to return (default: configured TOP_K value). For hybrid search, this is the initial retrieval size before reranking.

integer

Number of results after reranking (only applies when hybrid search is enabled). Default: configured TOP_K_RERANKER.

float

Relevance threshold (0.0 to 1.0). Results below this threshold are filtered out. Default: configured RELEVANCE_THRESHOLD.

boolean

Whether to use hybrid search (vector + BM25 + reranking). Default: based on ENABLE_RAG_HYBRID_SEARCH setting.

float

Weight for BM25 scores in hybrid search (0.0 to 1.0). Default: configured HYBRID_BM25_WEIGHT.

boolean

Whether to include enriched text snippets. Default: ENABLE_RAG_HYBRID_SEARCH_ENRICHED_TEXTS.

Headers

string

required

Bearer token for authentication

Response

Returns an array of relevant document chunks ranked by relevance score.

array

Array of arrays containing distance scores (lower is more similar). One array per collection queried.

array

Array of arrays containing the text content of matching chunksExample: [["Product guide chapter 1...", "Setup instructions..."]]

array

Array of arrays containing metadata for each document chunk

string

ID of the source file

string

Name of the source document

string

Source identifier or filename

string

User ID who uploaded the document

object

Configuration of the embedding model used

array

Array of arrays containing unique chunk IDs

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
  }'

import requests

url = "https://your-domain.com/api/v1/retrieval/query/collection"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
}
payload = {
    "collection_names": ["kb_123abc"],
    "query": "How do I install the software?",
    "k": 5,
    "hybrid": True,
    "r": 0.3  # Filter results below 30% relevance
}

response = requests.post(url, headers=headers, json=payload)
results = response.json()

for i, doc in enumerate(results["documents"][0]):
    print(f"Result {i+1}:")
    print(f"Content: {doc[:100]}...")
    if "scores" in results:
        print(f"Score: {results['scores'][0][i]}")
    print(f"Source: {results['metadatas'][0][i]['name']}")
    print()

const response = await fetch(
  'https://your-domain.com/api/v1/retrieval/query/collection',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      collection_names: ['kb_123abc'],
      query: 'How do I install the software?',
      k: 5,
      hybrid: true
    })
  }
);

const results = await response.json();
results.documents[0].forEach((doc, i) => {
  console.log(`Result ${i+1}: ${doc.substring(0, 100)}...`);
  console.log(`Source: ${results.metadatas[0][i].name}`);
});

{
  "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"
  ]]
}

{
  "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..."
  ]],
  "metadatas": [[...]],
  "ids": [["chunk_uuid_1", "chunk_uuid_2", "chunk_uuid_3"]],
  "scores": [[0.89, 0.76, 0.68]]
}

{
  "detail": "Collection kb_invalid not found"
}

Query Single Document Collection

For querying a single file’s collection:

POST /api/v1/retrieval/query/doc

Request Body

string

required

Single collection name (usually file-{file_id} for individual files)

string

required

Search query text

integer

Number of results to return

integer

Number of results after reranking

float

Relevance threshold

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

Hybrid Search

When hybrid=true or ENABLE_RAG_HYBRID_SEARCH is enabled:

Vector Search: Retrieves top k results by embedding similarity
BM25 Search: Retrieves results using keyword matching
Fusion: Combines results using hybrid_bm25_weight
Reranking: Uses cross-encoder model to rerank to top k_reranker results
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

Overview

Chat & Messages

Models

Users & Groups

Knowledge

Functions & Tools

Files & Media

Channels

Prompts

Notes & Folders

Evaluations

Configuration

Query Knowledge Bases

Request

Request Body

Headers

Response

Query Single Document Collection

Request Body

Search Modes

Vector Search (Default)

Hybrid Search

Access Control

Notes

​Request

​Request Body

​Headers

​Response

​Query Single Document Collection

​Request Body

​Search Modes

​Vector Search (Default)

​Hybrid Search

​Access Control

​Notes

Request

Request Body

Headers

Response

Query Single Document Collection

Request Body

Search Modes

Vector Search (Default)

Hybrid Search

Access Control

Notes