Retrieve Knowledge Base
Embed query and return the top-k matching chunks from the KB.
Auth: write:agents. Chunks are customer data, same threat
model as /agents/{id}/logs.
Tenant scoping: a kb_id from another tenant returns 404 just
like the read endpoint — no existence leak.
Rate limit: BUCKET_KB_RETRIEVAL at 30 req/min/tenant — same
budget as the other outbound-call endpoints (MCP discovery,
validate-llm, models-live).
Dual-surface model: this endpoint is one of three KB retrieval
paths. The Java agent runtime queries Pinecone directly at deploy
time via its own mirror (off the hot path through this BE); the
streamkap-tools MCP server exposes streamkap_kb_retrieve and
proxies through this endpoint for third-party agents.
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
Body
Request body for POST /knowledge-bases/{kb_id}/retrieve.
query is the user's text; the BE embeds it against the KB's
saved embedding connection and runs a similarity search against
the saved vector-store connection. top_k caps the number of
matches returned.
Response
Successful Response
Response envelope for KB retrieval — ordered list of matches.