Skip to content
RAG API

Search a knowledge base

POST
/v1/knowledge-bases/{kb_id}/search

Perform semantic search over a knowledge base. Returns ranked chunks with scores.

The search pipeline:

  1. Embed the query using Voyage AI
  2. Perform approximate nearest neighbor search via pgvector (HNSW)
  3. Optionally rerank results using Voyage AI Reranker (enabled by default)
  4. Apply score threshold filter
  5. Return top-k results with metadata

Reranking is enabled by default and significantly improves result quality. Set rerank: false to skip reranking (faster but lower quality).

Metadata filtering supports operators: $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin. Filters are applied post-retrieval with adaptive over-fetch.

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters ”
kb_id
required
string
/^kb_/
Example
kb_a1b2c3d4e5

Knowledge base ID

Request Body required

Section titled “Request Body required ”
object
query
required

Natural language search query

string
>= 1 characters <= 2000 characters
Example
How do I configure authentication?
top_k

Number of results to return

integer
default: 10 >= 1 <= 50
Example
10
rerank

Whether to apply cross-encoder reranking via Voyage AI Reranker. Enabled by default for better result quality. Set to false for lower latency.

boolean
default: true
Example
true
filter

Metadata filter object. Keys are metadata field names. Values are filter expressions using operators: $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin.

Example: {"department": {"$eq": "engineering"}, "version": {"$gte": 2}}

object
key
additional properties
any
Example
{
  "department": {
    "$eq": "engineering"
  },
  "version": {
    "$gte": 2
  }
}
score_threshold

Minimum score threshold. Results below this score are excluded.

number format: float
0 <= 1
Example
0.5
include_metadata

Whether to include chunk and document metadata in results

boolean
default: true
Example
true
mode

Search mode. vector (default) uses semantic embedding similarity. keyword uses PostgreSQL full-text search (no embedding call, faster/cheaper). hybrid runs both in parallel and fuses results with Reciprocal Rank Fusion (RRF).

string
default: vector
Allowed values: vector keyword hybrid
Example
hybrid
keyword

Optional keyword query for keyword/hybrid modes. If omitted, the query field is used for both semantic and keyword search. Useful when you want different queries for each search component.

string
>= 1 characters <= 2000 characters
Example
authentication config
alpha

Weight for vector results in hybrid mode (0 = keyword only, 1 = vector only). Only used when mode is hybrid. Default 0.6 (slightly favors semantic search).

number format: float
default: 0.6 <= 1
Example
0.6

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Search results returned

object
data
required
object
query
required

The original search query

string
Example
How do I configure authentication?
results
required
Array<object>
object
chunk_id
required

Chunk ID (prefixed with chk_)

string
Example
chk_k1l2m3n4o5
document_id
required

Source document ID

string
Example
doc_f6g7h8i9j0
document_name
required

Source document file name

string
Example
product-guide.pdf
text
required

The chunk text content

string
Example
To configure authentication, navigate to Settings > Auth and enable...
score
required

Relevance score (0 to 1). Higher is more relevant.

number format: float
Example
0.94
metadata

Chunk metadata (included when include_metadata is true)

object
chunk_index

Position of this chunk within the document

integer
Example
3
start_page

Starting page number

integer
nullable
Example
5
end_page

Ending page number

integer
nullable
Example
5
section_heading

Section heading this chunk belongs to

string
nullable
Example
Authentication Setup
key
additional properties
any
document_metadata

Document-level metadata (included when include_metadata is true)

object
key
additional properties
any
Example
{
  "department": "engineering",
  "version": 2
}
usage
required
object
embedding_tokens
required

Number of tokens used for query embedding (0 for keyword-only mode)

integer
Example
12
rerank_applied
required

Whether reranking was applied. May be false even if rerank: true was requested, if the reranker timed out or encountered an error (graceful degradation).

boolean
Example
true
rerank_queries
required

Number of rerank API calls made (0 if reranking was not applied)

integer
Example
1
chunks_searched
required

Total number of chunks searched

integer
Example
1420
search_mode
required

The search mode that was used for this query

string
Allowed values: vector keyword hybrid
Example
vector

400

Section titled “400 ”

Request validation failed

object
error
required
object
code
required

Machine-readable error code

string
Allowed values: VALIDATION_ERROR AUTHENTICATION_ERROR NOT_FOUND CONFLICT RATE_LIMIT_EXCEEDED USAGE_LIMIT_EXCEEDED EXTERNAL_SERVICE_ERROR INTERNAL_ERROR
Example
VALIDATION_ERROR
message
required

Human-readable error message

string
Example
Invalid request body
details

Additional error details (e.g., validation issues)

object
key
additional properties
any
Example
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request body",
    "details": {
      "issues": [
        {
          "path": [
            "name"
          ],
          "message": "Required"
        }
      ]
    }
  }
}

401

Section titled “401 ”

Authentication failed or missing

object
error
required
object
code
required

Machine-readable error code

string
Allowed values: VALIDATION_ERROR AUTHENTICATION_ERROR NOT_FOUND CONFLICT RATE_LIMIT_EXCEEDED USAGE_LIMIT_EXCEEDED EXTERNAL_SERVICE_ERROR INTERNAL_ERROR
Example
VALIDATION_ERROR
message
required

Human-readable error message

string
Example
Invalid request body
details

Additional error details (e.g., validation issues)

object
key
additional properties
any
Example
{
  "error": {
    "code": "AUTHENTICATION_ERROR",
    "message": "Invalid or missing API key"
  }
}

404

Section titled “404 ”

Resource not found

object
error
required
object
code
required

Machine-readable error code

string
Allowed values: VALIDATION_ERROR AUTHENTICATION_ERROR NOT_FOUND CONFLICT RATE_LIMIT_EXCEEDED USAGE_LIMIT_EXCEEDED EXTERNAL_SERVICE_ERROR INTERNAL_ERROR
Example
VALIDATION_ERROR
message
required

Human-readable error message

string
Example
Invalid request body
details

Additional error details (e.g., validation issues)

object
key
additional properties
any
Example
{
  "error": {
    "code": "NOT_FOUND",
    "message": "KnowledgeBase not found: kb_nonexistent"
  }
}

429

Section titled “429 ”

Rate limit or usage limit exceeded

object
error
required
object
code
required

Machine-readable error code

string
Allowed values: VALIDATION_ERROR AUTHENTICATION_ERROR NOT_FOUND CONFLICT RATE_LIMIT_EXCEEDED USAGE_LIMIT_EXCEEDED EXTERNAL_SERVICE_ERROR INTERNAL_ERROR
Example
VALIDATION_ERROR
message
required

Human-readable error message

string
Example
Invalid request body
details

Additional error details (e.g., validation issues)

object
key
additional properties
any
Examples

Rate limit exceeded

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded"
  }
}

502

Section titled “502 ”

External service error (embedding or reranking service unavailable)

object
error
required
object
code
required

Machine-readable error code

string
Allowed values: VALIDATION_ERROR AUTHENTICATION_ERROR NOT_FOUND CONFLICT RATE_LIMIT_EXCEEDED USAGE_LIMIT_EXCEEDED EXTERNAL_SERVICE_ERROR INTERNAL_ERROR
Example
VALIDATION_ERROR
message
required

Human-readable error message

string
Example
Invalid request body
details

Additional error details (e.g., validation issues)

object
key
additional properties
any
Example
{
  "error": {
    "code": "EXTERNAL_SERVICE_ERROR",
    "message": "Voyage AI: Request timed out"
  }
}