Skip to main content
POST
Search a knowledge base

Authorizations

Authorization
string
header
required

API key issued by EverOS, sent as Authorization: Bearer <api_key>.

Path Parameters

kb_id
string
required

Body

application/json

POST body (kb_id rides the path, not the body).

query
string | null

What to retrieve against within this knowledge base, up to 2000 characters. Optional: omit it and pass filters.tag_ids to page through tagged topics instead, which skips retrieval entirely — every hit then scores 0.0.

Maximum string length: 2000
method
enum<string>
default:hybrid

Retrieval strategy: "keyword" (lexical), "vector" (embedding similarity) or "hybrid" (default, both).

Available options:
keyword,
vector,
hybrid
page
integer
default:1

Filter-only page number; query search supports page 1 only

Required range: x >= 1
top_k
integer
default:10

Maximum number of topics to return, 1 to 100 (default 10). On a query search the server also bounds the result by its rerank pool — 50 candidates by default — so asking for more than that returns what the pool held. On a filter-only request (tags without a query) it is the page size instead, and page walks the rest.

Required range: 1 <= x <= 100
score_threshold
number | null

Drop hits whose final score is below this. Mind what that score is: it is normalized within each response (see score on a hit), so this cuts a RELATIVE position in one result set, not an absolute relevance bar — a response whose hits are all poor still has a top hit near the top of the range. Two traps follow from the edge values: a filter-only request scores every hit 0.0, so any positive threshold empties it, and a failed rerank batch scores -100.0, which every positive threshold silently removes. Tune it against real results rather than from a BM25 or cosine intuition.

include
string[]

e.g. ['content']

boost_tag_ids
string[]

Reweight, do not filter: topics carrying these tags are pushed up, and topics without them still come back. Use filters.tag_ids when the intent is to exclude everything else.

Maximum array length: 100

Opaque semantic tag id

Required string length: 1 - 128
filters
SearchFilters · object

Optional filters narrowing what is searched.

Response

Successful Response

request_id
string
required

Request trace id (peer to data)

data
KbSearchData · object
required

Endpoint-defined business result