Search a knowledge base

POST

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

• API base path

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

The search pipeline:

1. Embed the query into a vector
2. Perform approximate nearest neighbor (ANN) vector search
3. Optionally rerank results using a cross-encoder model (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.

Authorizations

• BearerApiKey

Parameters

Path Parameters

kb_id

required

string

/^kb_/

Example

kb_a1b2c3d4e5

Knowledge base ID

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 for improved result quality. Enabled by default. 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 full-text search (no embedding call, faster). 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

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

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

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

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

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

Query usage limit exceeded

{
  "error": {
    "code": "USAGE_LIMIT_EXCEEDED",
    "message": "Usage limit exceeded for search_queries. Upgrade your plan or wait for the next billing period.",
    "details": {
      "limit": 5000,
      "current_usage": 5000,
      "plan": "starter",
      "requested": 1
    }
  }
}

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": "Embedding service: Request timed out"
  }
}