Skip to main content
POST
/
api
/
knowledge-bases
/
search
curl -X POST "https://api.zudu.ai/api/knowledge-bases/search" \
  -H "X-API-KEY: sk_Abc123Def456..." \
  -H "X-API-SECRET: s3cr3t_Xyz789..." \
  -d '{
    "query": "How do I install the product?",
    "knowledge_base_ids": ["kb_abc123", "kb_def456"],
    "limit": 10,
    "score_threshold": 0.7,
    "merge_results": true,
    "fusion_method": "rrf"
  }'

{
  "message": "Search completed successfully",
  "status": "success",
  "error": null,
  "data": {
    "total_results": 5,
    "total_search_time_ms": 245,
    "results_by_knowledge_base": {
      "kb_abc123": [
        {
          "chunk_id": "chunk_123",
          "knowledge_base_id": "kb_abc123",
          "source_id": "src_456",
          "content": "To install the product, first download the installer...",
          "score": 0.92,
          "metadata": {
            "title": "Installation Guide",
            "source_type": "TEXT"
          }
      ],
      "kb_def456": [
        {
          "chunk_id": "chunk_789",
          "knowledge_base_id": "kb_def456",
          "source_id": "src_101",
          "content": "Installation requires Python 3.8 or higher...",
          "score": 0.85,
          "metadata": {
            "title": "Requirements",
            "source_type": "URL"
          }
      ]
    },
    "merged_results": [
      {
        "chunk_id": "chunk_123",
        "knowledge_base_id": "kb_abc123",
        "content": "To install the product, first download the installer...",
        "score": 0.92
      }
    ]
  }
Search across multiple knowledge bases using hybrid search with RRF (Reciprocal Rank Fusion) to combine semantic and keyword search results. Returns relevant content chunks with similarity scores. 
curl -X POST "https://api.zudu.ai/api/knowledge-bases/search" \
  -H "X-API-KEY: sk_Abc123Def456..." \
  -H "X-API-SECRET: s3cr3t_Xyz789..." \
  -d '{
    "query": "How do I install the product?",
    "knowledge_base_ids": ["kb_abc123", "kb_def456"],
    "limit": 10,
    "score_threshold": 0.7,
    "merge_results": true,
    "fusion_method": "rrf"
  }'

{
  "message": "Search completed successfully",
  "status": "success",
  "error": null,
  "data": {
    "total_results": 5,
    "total_search_time_ms": 245,
    "results_by_knowledge_base": {
      "kb_abc123": [
        {
          "chunk_id": "chunk_123",
          "knowledge_base_id": "kb_abc123",
          "source_id": "src_456",
          "content": "To install the product, first download the installer...",
          "score": 0.92,
          "metadata": {
            "title": "Installation Guide",
            "source_type": "TEXT"
          }
      ],
      "kb_def456": [
        {
          "chunk_id": "chunk_789",
          "knowledge_base_id": "kb_def456",
          "source_id": "src_101",
          "content": "Installation requires Python 3.8 or higher...",
          "score": 0.85,
          "metadata": {
            "title": "Requirements",
            "source_type": "URL"
          }
      ]
    },
    "merged_results": [
      {
        "chunk_id": "chunk_123",
        "knowledge_base_id": "kb_abc123",
        "content": "To install the product, first download the installer...",
        "score": 0.92
      }
    ]
  }

​
Headers

​
X-API-KEY
string
required
Your API key (format: sk_...)
​
X-API-SECRET
string
required
Your API secret (format: s3cr3t_...)

​
Request Body

​
query
string
required
Search query textNatural language query to search across knowledge bases.Example: "How do I install the product?"
​
knowledge_base_ids
array
required
Array of knowledge base IDs to search
  • Must belong to your organization
  • At least one knowledge base ID required
  • Can search across multiple knowledge bases simultaneously
Example: ["kb_abc123", "kb_def456"]
​
limit
number
Maximum number of results to return per knowledge base
  • Default: 10
  • Minimum: 1
  • Maximum: 100
Example: 10
​
score_threshold
number
Minimum similarity score threshold
  • Default: 0.7
  • Range: 0.0 to 1.0
  • Results below this threshold are filtered out
Example: 0.7
​
merge_results
boolean
Whether to merge results from all knowledge bases
  • Default: true
  • When true, provides a unified ranked list in merged_results
  • When false, only results_by_knowledge_base is populated
Example: true
​
fusion_method
string
Fusion method for combining search results
  • Default: "rrf" (Reciprocal Rank Fusion)
  • Currently only "rrf" is supported
Example: "rrf"

​
Response Fields

​
total_results
number
Total number of results found across all knowledge bases
​
total_search_time_ms
number
Total search time in milliseconds
​
results_by_knowledge_base
object
Results grouped by knowledge base IDEach knowledge base ID maps to an array of result objects.
​
results_by_knowledge_base[].chunk_id
string
Unique identifier for the content chunk
​
results_by_knowledge_base[].knowledge_base_id
string
Knowledge base ID this result belongs to
​
results_by_knowledge_base[].source_id
string
Source ID this chunk came from
​
results_by_knowledge_base[].content
string
The actual content text from the chunk
​
results_by_knowledge_base[].score
number
Similarity score (0.0 to 1.0)Higher scores indicate better matches.
​
results_by_knowledge_base[].metadata
object
Additional metadata about the chunkMay include:
  • title: Title of the source
  • source_type: Type of source (TEXT, URL, FILE)
  • Other source-specific metadata
​
merged_results
array
Unified ranked list of results from all knowledge basesOnly present when merge_results is true. Results are ranked using RRF fusion.

​
Error Responses

​
error
string
Bad Request - Invalid request or knowledge base access denied
{
  "message": "Access denied",
  "status": "error",
  "error": "Knowledge base 'kb_xyz' does not exist in organization"
}
​
error
string
Unauthorized - Missing or invalid API key/secret
​
error
string
Request Timeout - Search request timed out
{
  "message": "Search timeout",
  "status": "error",
  "error": "Search request timed out. Please try again with a simpler query or fewer knowledge bases."
}
​
error
string
Service Unavailable - Vector search service unavailable
{
  "message": "Search service temporarily unavailable",
  "status": "error",
  "error": "The vector search service is currently unavailable. Please try again later."
}

​
Notes

  • Uses hybrid search combining semantic (vector) and keyword search
  • Results are ranked using Reciprocal Rank Fusion (RRF)
  • All knowledge bases must belong to your organization
  • Search is case-insensitive
  • Results are filtered by score_threshold before returning
  • Processing time depends on the number of knowledge bases and query complexity
  • The vector search service must be operational for this endpoint to work
  • For single knowledge base search, use POST /api/knowledge-bases/search/{knowledgeBaseId}