Query knowledge base

POST

/knowledge-bases/{knowledgeBaseId}/query

Production API

Performs vector similarity search on the knowledge base, returning ranked chunks and community rankings. Uses the embedding model configured for the knowledge base to embed the query.

Authorizations

bearerAuth
cookieAuth

Parameters

Path Parameters

knowledgeBaseId

required

Unique identifier for the knowledge base to retrieve

string

Unique identifier for the knowledge base to retrieve

Request Body

object

query

required

Search query text

string

>= 1 characters

model

Embedding model to use for this query (defaults to KB’s primary model). Must be configured for this KB.

string

Allowed values: BAAI/bge-small-en-v1.5 BAAI/bge-base-en-v1.5 BAAI/bge-large-en-v1.5 sentence-transformers/all-MiniLM-L6-v2 sentence-transformers/all-mpnet-base-v2 nomic-ai/nomic-embed-text-v1.5

limit

Maximum number of results to return (1-100, default: 100)

integer

default: 100 >= 1 <= 100

filter

MongoDB-style metadata filter (e.g., {“status”: “final”, “version”: {“$gt”: 1}})

object

key

additional properties

Any of:

object

$eq

required

Any of:

string

searchMode

Search mode: semantic (vector search), keyword (BM25 full-text), or hybrid (RRF fusion). Default: semantic

string

default: semantic

Allowed values: semantic keyword hybrid

semanticWeight

Weight for semantic results in hybrid mode (0-1, default: 0.6)

number

default: 0.6 nullable <= 1

keywordWeight

Weight for keyword results in hybrid mode (0-1, default: 0.4)

number

default: 0.4 nullable <= 1

Responses

200

Query results

object

results

required

Chunks ranked by similarity

Array<object>

object

chunkId

required

Unique identifier for the chunk

string

content

required

Text content of the chunk

string

score

required

Primary score: cosine distance (semantic), BM25 (keyword), or RRF (hybrid)

number

communityL0Id

required

Level 0 community ID (finest granularity)

string

nullable

communityL1Id

required

Level 1 community ID

string

nullable

fileId

required

Source file ID (if from file source)

string

nullable

datasetTableId

required

Source dataset table ID (if from table source)

string

nullable

charStart

required

Character offset where chunk starts in source

number

charEnd

required

Character offset where chunk ends in source

number

semanticScore

Semantic search score (only in semantic/hybrid modes)

number

keywordScore

Keyword search BM25 score (only in keyword/hybrid modes)

number

combinedScore

RRF combined score (only in hybrid mode)

number

communities

required

Communities ranked by best chunk score

Array<object>

object

communityId

required

Unique identifier for the community

string

level

required

Community hierarchy level (0 = finest, 3 = coarsest)

integer

<= 3

bestScore

required

Best (lowest) chunk score in this community

number

chunkCount

required

Number of matching chunks in this community

integer

metadata

required

object

searchMode

required

Search mode used

string

Allowed values: semantic keyword hybrid

fallback

Whether hybrid mode fell back to semantic

boolean

400

Bad Request - Validation error or invalid input

object

error

required

string

code

string

details

nullable

retryable

boolean

401

Unauthorized - Authentication required or invalid token

object

error

required

string

code

string

details

nullable

retryable

boolean

403

Forbidden - Insufficient permissions

object

error

required

string

code

string

details

nullable

retryable

boolean

404

Not Found - Resource does not exist

object

error

required

string

code

string

details

nullable

retryable

boolean